@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/Markdown/parser.perf.test.ts

@@ -116,15 +116,19 @@ describe('parseMarkdown performance', () => {
 
   // Full re-parse benchmarks
   for (const size of sizes) {
-    it(`full re-parse ${size.name} (${size.paragraphs} paragraphs) under ${size.maxMs}ms`, () => {
-      const text = generateAIResponse(size.paragraphs);
-      const {elapsed, result} = measureBest(3, () => parseMarkdown(text));
-      console.log(
-        `  ${size.name} full parse: ${elapsed.toFixed(2)}ms → ${result.length} blocks`,
-      );
-      expect(elapsed).toBeLessThan(size.maxMs);
-      expect(result.length).toBeGreaterThan(0);
-    });
+    it(
+      `full re-parse ${size.name} (${size.paragraphs} paragraphs) under ${size.maxMs}ms`,
+      () => {
+        const text = generateAIResponse(size.paragraphs);
+        const {elapsed, result} = measureBest(3, () => parseMarkdown(text));
+        console.log(
+          `  ${size.name} full parse: ${elapsed.toFixed(2)}ms → ${result.length} blocks`,
+        );
+        expect(elapsed).toBeLessThan(size.maxMs);
+        expect(result.length).toBeGreaterThan(0);
+      },
+      size.maxMs + 5000,
+    );
   }
 
   // Streaming with full re-parse
@@ -132,19 +136,23 @@ describe('parseMarkdown performance', () => {
     {name: 'Medium', paragraphs: 50, maxMs: 5000},
     {name: 'XL', paragraphs: 500, maxMs: 30000},
   ]) {
-    it(`streaming full re-parse ${size.name} under ${size.maxMs}ms`, () => {
-      const text = generateAIResponse(size.paragraphs);
-      const chunkSize = 50;
-      const iterations = Math.ceil(text.length / chunkSize);
-      const start = performance.now();
-      const result = simulateStreamingFullReparse(text, chunkSize);
-      const elapsed = performance.now() - start;
-      console.log(
-        `  ${size.name} streaming full re-parse: ${elapsed.toFixed(2)}ms (${iterations} iterations)`,
-      );
-      expect(elapsed).toBeLessThan(size.maxMs);
-      expect(result.length).toBeGreaterThan(0);
-    });
+    it(
+      `streaming full re-parse ${size.name} under ${size.maxMs}ms`,
+      () => {
+        const text = generateAIResponse(size.paragraphs);
+        const chunkSize = 50;
+        const iterations = Math.ceil(text.length / chunkSize);
+        const start = performance.now();
+        const result = simulateStreamingFullReparse(text, chunkSize);
+        const elapsed = performance.now() - start;
+        console.log(
+          `  ${size.name} streaming full re-parse: ${elapsed.toFixed(2)}ms (${iterations} iterations)`,
+        );
+        expect(elapsed).toBeLessThan(size.maxMs);
+        expect(result.length).toBeGreaterThan(0);
+      },
+      size.maxMs + 5000,
+    );
   }
 
   // Streaming with incremental parse
@@ -152,19 +160,23 @@ describe('parseMarkdown performance', () => {
     {name: 'Medium', paragraphs: 50, maxMs: 5000},
     {name: 'XL', paragraphs: 500, maxMs: 30000},
   ]) {
-    it(`streaming incremental ${size.name} under ${size.maxMs}ms`, () => {
-      const text = generateAIResponse(size.paragraphs);
-      const chunkSize = 50;
-      const iterations = Math.ceil(text.length / chunkSize);
-      const start = performance.now();
-      const result = simulateStreamingIncremental(text, chunkSize);
-      const elapsed = performance.now() - start;
-      console.log(
-        `  ${size.name} streaming incremental: ${elapsed.toFixed(2)}ms (${iterations} iterations)`,
-      );
-      expect(elapsed).toBeLessThan(size.maxMs);
-      expect(result.length).toBeGreaterThan(0);
-    });
+    it(
+      `streaming incremental ${size.name} under ${size.maxMs}ms`,
+      () => {
+        const text = generateAIResponse(size.paragraphs);
+        const chunkSize = 50;
+        const iterations = Math.ceil(text.length / chunkSize);
+        const start = performance.now();
+        const result = simulateStreamingIncremental(text, chunkSize);
+        const elapsed = performance.now() - start;
+        console.log(
+          `  ${size.name} streaming incremental: ${elapsed.toFixed(2)}ms (${iterations} iterations)`,
+        );
+        expect(elapsed).toBeLessThan(size.maxMs);
+        expect(result.length).toBeGreaterThan(0);
+      },
+      size.maxMs + 5000,
+    );
   }
 
   // --- Incremental vs Full speedup benchmark ---

package/src/MetadataList/MetadataList.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: 'MetadataList',
@@ -89,7 +89,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -109,7 +109,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'label/value metadata display; column layout, collapse, orientation variants',
   usage: {

package/src/MetadataList/MetadataList.test.tsx

@@ -5,6 +5,7 @@ import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MetadataList} from './MetadataList';
 import {MetadataListItem} from './MetadataListItem';
+import {InternationalizationProvider} from '../i18n';
 
 describe('MetadataList', () => {
   it('renders a description list with items', () => {
@@ -87,6 +88,29 @@ describe('MetadataList', () => {
     expect(screen.queryByText('B')).not.toBeInTheDocument();
   });
 
+  it('localizes the show more / show less labels through the i18n catalog', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.metadataList.showMore': 'Afficher plus',
+            '@astryx.metadataList.showLess': 'Afficher moins',
+          },
+        }}>
+        <MetadataList maxNumOfItems={1}>
+          <MetadataListItem label="A">1</MetadataListItem>
+          <MetadataListItem label="B">2</MetadataListItem>
+        </MetadataList>
+      </InternationalizationProvider>,
+    );
+
+    await user.click(screen.getByText('Afficher plus'));
+    expect(screen.getByText('Afficher moins')).toBeInTheDocument();
+  });
+
   it('does not show toggle in horizontal mode even with maxNumOfItems', () => {
     render(
       <MetadataList orientation="horizontal" maxNumOfItems={1}>
@@ -99,6 +123,64 @@ describe('MetadataList', () => {
     expect(screen.getByText('A')).toBeInTheDocument();
     expect(screen.getByText('B')).toBeInTheDocument();
   });
+
+  describe('numeric columns', () => {
+    // A fixed column count is a runtime value, so it arrives as a StyleX
+    // dynamic style: the template lands in the element's inline style (as the
+    // generated custom property) rather than in a static class rule.
+    const gridTemplateOf = (container: HTMLElement) =>
+      container.querySelector('dl')?.getAttribute('style') ?? '';
+
+    it('renders the requested number of columns with stacked labels', () => {
+      const {container} = render(
+        <MetadataList columns={3}>
+          <MetadataListItem label="A">1</MetadataListItem>
+        </MetadataList>,
+      );
+
+      expect(gridTemplateOf(container)).toContain('repeat(3, 1fr)');
+    });
+
+    it('renders label and value tracks per column with side labels', () => {
+      const {container} = render(
+        <MetadataList columns={3} label={{position: 'start'}}>
+          <MetadataListItem label="A">1</MetadataListItem>
+        </MetadataList>,
+      );
+
+      expect(gridTemplateOf(container)).toContain('repeat(3, auto 1fr)');
+    });
+
+    it('leaves the grid to the static rule for columns="multi"', () => {
+      const {container} = render(
+        <MetadataList columns="multi">
+          <MetadataListItem label="A">1</MetadataListItem>
+        </MetadataList>,
+      );
+
+      expect(gridTemplateOf(container)).not.toContain('repeat(');
+    });
+
+    it('ignores numeric columns in horizontal orientation', () => {
+      const {container} = render(
+        <MetadataList columns={3} orientation="horizontal">
+          <MetadataListItem label="A">1</MetadataListItem>
+        </MetadataList>,
+      );
+
+      expect(gridTemplateOf(container)).not.toContain('repeat(');
+    });
+
+    it('still applies a custom label width with side labels', () => {
+      const {container} = render(
+        <MetadataList label={{position: 'start', width: 120}}>
+          <MetadataListItem label="A">1</MetadataListItem>
+        </MetadataList>,
+      );
+
+      expect(gridTemplateOf(container)).toContain('120px 1fr');
+    });
+  });
 });
 
 describe('MetadataListItem', () => {

package/src/MetadataList/MetadataList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file MetadataList.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens, MetadataListContext
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, MetadataListContext, i18n (useTranslator)
  * @output Exports MetadataList component, MetadataListProps, MetadataListColumns types
  * @position Core implementation; consumed by index.ts, tested by MetadataList.test.tsx
  *
@@ -13,7 +13,7 @@
  * - /packages/core/src/MetadataList/MetadataList.test.tsx
  * - /packages/core/src/MetadataList/index.ts
  * - /apps/storybook/stories/MetadataList.stories.tsx
- * - /packages/cli/templates/blocks/components/MetadataList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/MetadataList/ (showcase blocks)
  */
 
 import {Children, useId, useMemo, useState, type ReactNode} from 'react';
@@ -31,6 +31,7 @@ import {
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -156,6 +157,12 @@ const styles = stylex.create({
   },
 });
 
+// A fixed numeric column count (and a custom label width) is only known at
+// runtime, so it comes from a dynamic style rather than a static rule.
+const dynamicStyles = stylex.create({
+  gridTemplate: (gridTemplateColumns: string) => ({gridTemplateColumns}),
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -197,6 +204,7 @@ export function MetadataList({
   const labelConfig = label ?? (isMultiColumn ? LABEL_TOP : LABEL_START);
   const [isShowAll, setIsShowAll] = useState(false);
   const contentId = useId();
+  const t = useTranslator();
 
   const contextValue = useMemo(
     () => ({
@@ -239,20 +247,32 @@ export function MetadataList({
     return styles.gridMulti;
   };
 
-  // For numeric columns > 1 with side labels, use inline style for dynamic grid
-  const dynamicGridStyle =
-    !isHorizontal &&
-    labelConfig.position === 'start' &&
-    typeof columns === 'number' &&
-    columns > 1
-      ? {gridTemplateColumns: `repeat(${columns}, auto 1fr)`}
-      : !isHorizontal &&
-          labelConfig.position === 'start' &&
-          labelConfig.width != null
-        ? {
-            gridTemplateColumns: `${typeof labelConfig.width === 'number' ? `${labelConfig.width}px` : labelConfig.width} 1fr`,
-          }
-        : undefined;
+  // The grid template for a fixed numeric column count, or for a custom label
+  // width. Both are runtime values, so they resolve to a dynamic style below.
+  // The track shape depends on the label position: stacked labels put a whole
+  // item in one cell, while side labels split each item into a label track and
+  // a value track.
+  const getGridTemplateColumns = () => {
+    if (isHorizontal) {
+      return null;
+    }
+    const isStacked = labelConfig.position === 'top';
+    if (typeof columns === 'number' && columns > 1) {
+      return isStacked
+        ? `repeat(${columns}, 1fr)`
+        : `repeat(${columns}, auto 1fr)`;
+    }
+    // A custom label width only applies to the label track of side labels.
+    if (!isStacked && labelConfig.width != null) {
+      const width =
+        typeof labelConfig.width === 'number'
+          ? `${labelConfig.width}px`
+          : labelConfig.width;
+      return `${width} 1fr`;
+    }
+    return null;
+  };
+  const gridTemplateColumns = getGridTemplateColumns();
 
   return (
     <MetadataListContext value={contextValue}>
@@ -271,9 +291,12 @@ export function MetadataList({
         {titleContent}
         <dl
           id={contentId}
-          {...mergeProps(stylex.props(styles.dl, getGridStyle()), {
-            style: dynamicGridStyle,
-          })}>
+          {...stylex.props(
+            styles.dl,
+            getGridStyle(),
+            gridTemplateColumns != null &&
+              dynamicStyles.gridTemplate(gridTemplateColumns),
+          )}>
           {visibleChildren}
         </dl>
         {isExceedMax && (
@@ -283,7 +306,9 @@ export function MetadataList({
             aria-expanded={isShowAll}
             onClick={() => setIsShowAll(prev => !prev)}
             {...stylex.props(styles.toggleButton)}>
-            {isShowAll ? 'Show less' : 'Show more'}
+            {isShowAll
+              ? t('@astryx.metadataList.showLess')
+              : t('@astryx.metadataList.showMore')}
           </button>
         )}
       </div>

package/src/MetadataList/MetadataListItem.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: 'MetadataListItem',

package/src/MetadataList/MetadataListItem.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/MetadataList/MetadataList.test.tsx
  * - /packages/core/src/MetadataList/index.ts
  * - /apps/storybook/stories/MetadataList.stories.tsx
- * - /packages/cli/templates/blocks/components/MetadataList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/MetadataList/ (showcase blocks)
  */
 
 import {use, type ReactNode} from 'react';

package/src/MobileNav/MobileNav.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: 'MobileNav',
@@ -109,7 +109,7 @@ export const docs = {
     ],
   },
 };
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'MobileNav',
   displayName: 'Mobile Nav',
@@ -171,7 +171,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Slide-out drawer overlay for mobile navigation. Mobile counterpart to SideNav; accepts same children (SideNavSection, SideNavItem, or any ReactNode).',

package/src/MobileNav/MobileNav.tsx

@@ -23,7 +23,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/MobileNav/index.ts (exports if types change)
- * - /packages/cli/templates/blocks/components/MobileNav/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/MobileNav/ (showcase blocks)
  */
 
 import {
@@ -453,9 +453,9 @@ export function MobileNav({
         {/* Header — content + close button */}
         <div {...stylex.props(styles.header, !header && styles.headerNoTitle)}>
           {typeof header === 'string' ? (
-            <span {...stylex.props(styles.headerText)}>
-              <Heading level={2}>{header}</Heading>
-            </span>
+            <Heading level={2} xstyle={styles.headerText}>
+              {header}
+            </Heading>
           ) : (
             (header ?? null)
           )}

package/src/MoreMenu/MoreMenu.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: 'MoreMenu',
@@ -77,7 +77,7 @@ export const docs = {
     ],
   },
 };
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'MoreMenu',
   displayName: 'More Menu',
@@ -142,7 +142,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Overflow menu w/ three-dot icon trigger. Convenience wrapper composing icon-only Button w/ dropdown menu, eliminating boilerplate for state management, positioning, accessibility.',

package/src/MoreMenu/MoreMenu.test.tsx

@@ -10,7 +10,7 @@
  */
 
 import {describe, it, expect, vi, beforeEach} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MoreMenu} from './MoreMenu';
 
@@ -197,4 +197,31 @@ describe('MoreMenu', () => {
     const menu = screen.getByRole('menu', {hidden: true});
     expect(menu.className).toContain('astryx-more-menu');
   });
+
+  it('pointer open focuses the menu container, not the first item (#4477)', async () => {
+    const user = userEvent.setup();
+    render(<MoreMenu items={defaultItems} />);
+
+    await user.click(screen.getByRole('button', {name: 'More options'}));
+
+    const menu = screen.getByRole('menu', {hidden: true});
+    await waitFor(() => expect(menu).toHaveFocus());
+    expect(
+      screen.getByRole('menuitem', {name: 'Edit', hidden: true}),
+    ).not.toHaveFocus();
+  });
+
+  it('first ArrowDown after a pointer open moves focus to the first item (#4477)', async () => {
+    const user = userEvent.setup();
+    render(<MoreMenu items={defaultItems} />);
+
+    await user.click(screen.getByRole('button', {name: 'More options'}));
+    const menu = screen.getByRole('menu', {hidden: true});
+    await waitFor(() => expect(menu).toHaveFocus());
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitem', {name: 'Edit', hidden: true}),
+    ).toHaveFocus();
+  });
 });

package/src/MoreMenu/MoreMenu.tsx

@@ -15,11 +15,11 @@
  * - /packages/core/src/MoreMenu/MoreMenu.test.tsx
  * - /packages/core/src/MoreMenu/index.ts
  * - /apps/storybook/stories/MoreMenu.stories.tsx
- * - /packages/cli/templates/blocks/components/MoreMenu/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/MoreMenu/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';
-import {getIcon} from '../Icon/globalIconRegistry';
+import {useIcon} from '../Icon';
 import {DropdownMenu} from '../DropdownMenu/DropdownMenu';
 import {useSize} from '../SizeContext/SizeContext';
 import type {DropdownMenuOption} from '../DropdownMenu';
@@ -119,7 +119,7 @@ export function MoreMenu({
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.moreMenu.label');
   const size = useSize(sizeProp, 'md');
-  const moreIcon = getIcon('moreHorizontal');
+  const moreIcon = useIcon('moreHorizontal');
 
   return (
     <DropdownMenu

package/src/MultiSelector/MultiSelector.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: 'MultiSelector',
@@ -20,8 +20,13 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-multi-selector', visualProps: ['size', 'status']},
+      {
+        className: 'astryx-multi-selector',
+        visualProps: ['variant', 'size', 'status'],
+        states: ['disabled'],
+      },
       {className: 'astryx-multi-selector-clear-icon'},
+      {className: 'astryx-multi-selector-empty-state'},
       {
         className: 'astryx-multi-selector-indicator-icon',
         states: ['state'],
@@ -77,6 +82,13 @@ export const docs = {
           description: 'Size variant for the selector.',
           default: "'md'",
         },
+        {
+          name: 'variant',
+          type: "'input' | 'ghost'",
+          description:
+            'Visual trigger style. input is the bordered input treatment for forms; ghost is borderless and matches ghost buttons for toolbar usage.',
+          default: "'input'",
+        },
         {
           name: 'triggerDisplay',
           type: "'count' | 'labels' | 'badges'",
@@ -105,7 +117,7 @@ export const docs = {
           name: 'hasSearch',
           type: 'boolean',
           description:
-            'Whether to show a search input for filtering options. As the user types, the match count (or "No results found") is announced to screen readers via a polite live region.',
+            'Whether to show a search input for filtering options. As the user types, the match count (or "No results found") is announced to screen readers via a polite live region. The search field has built-in affordances: a leading magnifier icon and, once a query is typed, a trailing clear (✕) button that resets the query and returns focus to the input.',
         },
         {
           name: 'searchPlaceholder',
@@ -162,10 +174,11 @@ export const docs = {
         },
         {
           name: 'statusVariant',
-          type: "'attached' | 'detached'",
+          type: "'attached' | 'detached' | 'tooltip'",
           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'",
+            'How the status message is placed relative to the input. attached overlaps directly below the bordered input and is only valid for the input variant; ghost selectors detach attached status messages by default. Use tooltip for compact toolbar controls.',
+          default:
+            "'attached' for input selectors; 'detached' for ghost selectors",
         },
         {
           name: 'renderOption',
@@ -217,6 +230,11 @@ export const docs = {
         description:
           'Use inside InputGroup only when the control needs a short prefix or suffix addon as part of one decorated input surface; prefer count or labels trigger display so the group stays single-line.',
       },
+      {
+        guidance: true,
+        description:
+          'Use variant="ghost" when a multi-selector sits in a toolbar with ghost buttons. If validation status is needed there, prefer statusVariant="tooltip" so the toolbar height stays compact.',
+      },
       {
         guidance: false,
         description: 'Use for single-value selection; use Selector instead.',
@@ -234,7 +252,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   components: [
     {
@@ -268,7 +286,8 @@ export const docsZh = {
         isRequired: '将字段标记为必填。',
         isLoading: '在触发器中显示加载旋转器。',
         status: '带可选消息的验证状态。',
-        statusVariant: '状态消息的放置方式：attached 直接叠加在输入框下方；detached 作为独立元素浮于下方并留有间距。',
+        statusVariant:
+          '状态消息的放置方式：attached 直接叠加在输入框下方；detached 作为独立元素浮于下方并留有间距。',
         renderOption:
           '每个可选选项的自定义渲染函数。不会用于分隔线、分组或全选行。',
         xstyle: '布局自定义的 StyleX 样式，必须是 stylex.create() 值。',
@@ -316,7 +335,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'checkbox multi-select dropdown for finite sets like column toggles or filter facets',
@@ -349,6 +368,11 @@ export const docsDense = {
         description:
           'Use inside InputGroup only for a short prefix or suffix addon; prefer count or labels trigger display so the group stays single-line.',
       },
+      {
+        guidance: true,
+        description:
+          'Use variant="ghost" in toolbars with ghost buttons; prefer statusVariant="tooltip" for compact validation status.',
+      },
       {
         guidance: false,
         description: 'Use for single-value selection; use Selector instead.',
@@ -378,6 +402,8 @@ export const docsDense = {
         changeAction: 'async; fires after onChange',
         placeholder: 'text when nothing selected',
         size: 'size variant',
+        variant:
+          'visual trigger style: input bordered control or ghost toolbar control',
         triggerDisplay: 'how to show selected in trigger',
         maxBadges: 'max badges before "+N"; badges mode only',
         hasSelectAll: 'show select-all checkbox',
@@ -394,7 +420,8 @@ export const docsDense = {
         isRequired: 'marks required',
         isLoading: 'spinner in trigger',
         status: 'validation status w/ optional message',
-        statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
+        statusVariant:
+          'status message placement; ghost detaches attached by default; use tooltip for compact toolbars.',
         renderOption:
           'custom render fn per selectable option; not dividers/sections/select-all',
         xstyle: 'StyleX layout styles; stylex.create() only',