@astryxdesign/core 0.4.1 → 0.4.2-canary.01592f7

package/src/AvatarGroup/AvatarGroup.test.tsx

@@ -104,6 +104,20 @@ describe('AvatarGroupOverflow', () => {
     expect(overflow).toHaveTextContent('+5');
   });
 
+  it('applies the group size class to the overflow chip', () => {
+    render(
+      <AvatarGroup size="lg">
+        <Avatar name="Alice" />
+        <AvatarGroupOverflow count={5} />
+      </AvatarGroup>,
+    );
+
+    const overflow = screen.getByLabelText('5 more');
+    expect(overflow.className).toContain('astryx-avatar-group-overflow');
+    expect(overflow.className).toContain('lg');
+    expect(overflow).toHaveAttribute('data-size', 'lg');
+  });
+
   it('renders as button when onClick is provided', () => {
     render(
       <AvatarGroup>

package/src/AvatarGroup/AvatarGroupOverflow.tsx

@@ -146,6 +146,7 @@ export function AvatarGroupOverflow({
 }: AvatarGroupOverflowProps): ReactNode {
   const t = useTranslator();
   const group = useAvatarGroup();
+  const size = group?.size ?? 'md';
   const numericSize = group?.numericSize ?? 36;
   const overlap = group?.overlap ?? 0;
 
@@ -162,7 +163,7 @@ export function AvatarGroupOverflow({
         aria-label={label}
         data-avatar-item=""
         {...mergeProps(
-          themeProps('avatar-group-overflow'),
+          themeProps('avatar-group-overflow', {size}),
           focusOutlineProps.focusVisible(
             styles.base,
             styles.button,
@@ -186,7 +187,7 @@ export function AvatarGroupOverflow({
       {...rest}
       aria-label={label}
       {...mergeProps(
-        themeProps('avatar-group-overflow'),
+        themeProps('avatar-group-overflow', {size}),
         stylex.props(
           styles.base,
           styles.overlap,

package/src/Button/Button.tsx

@@ -438,8 +438,10 @@ const loadingStyles = stylex.create({
  *
  * Layers always carry the native `popover` attribute (useLayer.tsx), and a
  * popover is never an in-flow member — it is `display: none` until shown, then
- * promoted to the top layer. So "last member" is: no following element sibling
- * that isn't a popover.
+ * promoted to the top layer. Context layers also retain an inert `<template>`
+ * marker so they can re-resolve their JSX position. Neither element is a group
+ * member, so "last member" is: no following element sibling besides those two
+ * pieces of layer infrastructure.
  *
  * Reading it the other way round — marking the *buttons* and testing for a
  * marked sibling — is the trap: it silently reclassifies anything it doesn't
@@ -455,7 +457,7 @@ const loadingStyles = stylex.create({
  * The leading edge still uses `:first-child` — a member's button always precedes
  * its own layer, so the first button is genuinely `:first-child`.
  */
-const IS_LAST_ITEM = ':not(:has(~ *:not([popover])))';
+const IS_LAST_ITEM = ':not(:has(~ *:not([popover]):not(template)))';
 
 const groupStyles = stylex.create({
   horizontal: {

package/src/ButtonGroup/ButtonGroup.test.tsx

@@ -202,9 +202,9 @@ describe('ButtonGroup', () => {
   // Trailing radius (issue #2508)
   //
   // The trailing end cap cannot be keyed off `:last-child`: members render an
-  // invisible layer AFTER their button (tooltip'd Button, DropdownMenu), and
-  // useLayer renders it inline rather than portaling it, so the layer steals the
-  // slot. See IS_LAST_ITEM in Button.tsx.
+  // invisible layer infrastructure AFTER their button (tooltip'd Button,
+  // DropdownMenu), and useLayer renders a marker plus the layer inline when the
+  // host is safe, so they steal the slot. See IS_LAST_ITEM in Button.tsx.
   //
   // HOW THESE TESTS CATCH THE BUG
   // jsdom applies no StyleX CSS, so a DOM-only test cannot prove which rule
@@ -219,7 +219,9 @@ describe('ButtonGroup', () => {
   describe('trailing radius (#2508)', () => {
     /** The group members, in DOM order (excludes invisible layer siblings). */
     const items = (group: HTMLElement): Element[] =>
-      Array.from(group.querySelectorAll(':scope > *:not([popover])'));
+      Array.from(
+        group.querySelectorAll(':scope > *:not([popover]):not(template)'),
+      );
 
     // -- Compiled CSS, read from the source -----------------------------------
 
@@ -375,6 +377,7 @@ describe('ButtonGroup', () => {
           // .stylex.ts file it compiles to a mangled selector like `[x13pbwiz]`
           // that matches nothing in the DOM.
           expect(selector).toContain('[popover]');
+          expect(selector).toContain('template');
         }
       },
     );

package/src/Card/Card.doc.mjs

@@ -95,6 +95,8 @@ export const docs = {
     ],
     vars: [
       {name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
+      {name: '--_card-elevation', description: 'Resting shadow of the card, set from the elevation prop. Composed into the card box-shadow list alongside --_card-ring rather than written as boxShadow directly, so a ring and an elevation can coexist.', default: '0 0 transparent', private: true},
+      {name: '--_card-ring', description: 'Inset ring drawn in the card box-shadow list. SelectableCard sets it to show selection without taking over the shadow.', default: '0 0 transparent', private: true},
     ],
     derived: [
       {property: 'borderRadius', vars: ['--_card-radius']},

package/src/Chat/Chat.doc.mjs

@@ -67,6 +67,7 @@ export const docs = {
       { guidance: true, description: 'Use the group prop on bubbles (first, middle, last) when a single sender sends multiple consecutive messages; it tightens corner radius to visually connect them.' },
       { guidance: true, description: 'Use ChatSystemMessage with variant="divider" for date separators and default for inline status notices like joins, leaves, or topic changes.' },
       { guidance: true, description: 'Put name on the first bubble and metadata on the last bubble in a message so they align with the bubble\'s inline padding.' },
+      { guidance: true, description: 'Wrap custom in-message content (cards, attachments, citations) in a ghost bubble so it aligns with the bubble text column; add width="100%" when it should span the full message column instead of the default bubble width cap.' },
       { guidance: true, description: 'Provide an emptyState prop so new users see a clear prompt to start a conversation instead of a blank screen.' },
       { guidance: true, description: 'Use the ghost bubble variant for AI-style responses that show rich content like code blocks or markdown without a visible boundary.' },
       { guidance: false, description: 'Don\'t use ChatSystemMessage for sender content; it has no avatar, alignment, or bubble. Use ChatMessage with a sender role instead.' },
@@ -84,7 +85,7 @@ export const docs = {
       { name: 'Empty state', required: false, description: 'Centered placeholder shown when no messages exist. Use EmptyState for a consistent look.' },
       { name: 'Avatar', required: false, description: 'A sender avatar rendered beside the message. Typically Avatar with size="md". Hidden for system messages.' },
       { name: 'Name', required: false, description: 'Sender name above the message body. Place on the bubble when using bubbles, or on the message wrapper for raw content.' },
-      { name: 'Content', required: true, description: 'The message body: one or more ChatMessageBubble elements, or any free-form ReactNode like images or tool calls.' },
+      { name: 'Content', required: true, description: 'The message body: one or more ChatMessageBubble elements, or any free-form ReactNode like images or tool calls. Wrap non-bubble content in a ghost bubble to align it with the bubble text column.' },
       { name: 'Metadata', required: false, description: 'Timestamp, delivery status, and footer actions below the message. Place on the last bubble or on the message wrapper.' },
     ],
   },
@@ -100,6 +101,7 @@ export const docsZh = {
       { guidance: true, description: '当同一发送者发送多条连续消息时，使用气泡的 group 属性（first、middle、last）来视觉上连接相关消息。' },
       { guidance: true, description: '使用 ChatSystemMessage 的 variant="divider" 作为日期分隔线，使用 default 作为内联状态通知。' },
       { guidance: true, description: '将 name 放在第一个气泡上，metadata 放在最后一个气泡上，使其与气泡的内边距对齐。' },
+      { guidance: true, description: '将自定义消息内容（卡片、附件、引用）包裹在 ghost 变体的气泡中，使其与气泡文本列对齐；需要占满消息列宽度时设置 width="100%"。' },
       { guidance: true, description: '提供 emptyState 属性，让新用户看到开始对话的提示，而不是空白屏幕。' },
       { guidance: true, description: '使用 ghost 气泡变体显示代码块或 Markdown 等富内容，无需可见边界。' },
       { guidance: false, description: '不要将 ChatSystemMessage 用于发送者内容，它没有头像、对齐或气泡。请使用带有发送者角色的 ChatMessage。' },
@@ -131,6 +133,7 @@ export const docsDense = {
       { guidance: true, description: 'Group prop on bubbles (first/middle/last) for consecutive same-sender messages; tightens corner radius.' },
       { guidance: true, description: 'SystemMessage: divider variant for date breaks, default for status notices.' },
       { guidance: true, description: 'Name on first bubble, metadata on last; aligns with bubble inline padding.' },
+      { guidance: true, description: 'Ghost bubble wraps custom content (cards/attachments); width="100%" spans full message column (default cap max(80%,280px)).' },
       { guidance: true, description: 'Provide emptyState so new users see a prompt, not a blank screen.' },
       { guidance: true, description: 'Ghost bubble variant for rich AI content like code/markdown without visible boundary.' },
       { guidance: false, description: 'SystemMessage for sender content: no avatar/alignment/bubble. Use ChatMessage instead.' },

package/src/Chat/ChatMessage.doc.mjs

@@ -17,7 +17,7 @@ export const docs = {
     {
       name: 'children',
       type: 'ReactNode',
-      description: 'Free-form content: bubbles, asset lists, tool calls, images.',
+      description: 'Free-form content: bubbles, asset lists, tool calls, images. Custom (non-bubble) children render flush with the message edge; wrap them in a ghost ChatMessageBubble to align them with the bubble text column.',
       required: true,
     },
     {
@@ -67,7 +67,7 @@ export const docsZh = {
   description: '发送者上下文包装器，根据发送者角色处理头像、名称、元数据和对齐方式。',
   propDescriptions: {
     sender: '消息发送者，控制对齐和布局。',
-    children: '自由内容：气泡、资源列表、工具调用、图片。',
+    children: '自由内容：气泡、资源列表、工具调用、图片。非气泡的自定义子内容默认与消息边缘齐平，可用 ghost 变体的 ChatMessageBubble 包裹使其与气泡文本列对齐。',
     avatar: '消息旁边渲染的头像元素。通常是 Avatar。',
     name: '消息正文上方渲染的发送者名称。当第一个子元素不是气泡时使用。',
     metadata: '消息正文下方渲染的元数据。当最后一个子元素不是气泡时使用。',
@@ -81,7 +81,7 @@ export const docsDense = {
   description: 'sender context wrapper; handles avatar+name+metadata+alignment by sender role',
   propDescriptions: {
     sender: 'who sent; controls alignment+layout',
-    children: 'free-form: bubbles, assets, tool calls, images',
+    children: 'free-form: bubbles, assets, tool calls, images; wrap non-bubble content in a ghost bubble to align with bubble text column',
     avatar: 'avatar element beside msg; typically Avatar',
     name: 'sender name above body; use when first child is raw (not bubble)',
     displayName: 'sender name above body; use when first child is raw (not bubble)',

package/src/Chat/ChatMessage.tsx

@@ -41,6 +41,13 @@ import {useTranslator} from '../i18n';
 export interface ChatMessageProps extends BaseProps<HTMLElement> {
   ref?: React.Ref<HTMLElement>;
   sender: ChatMessageSender;
+  /**
+   * Message body — bubbles, tool calls, images, or any free-form content.
+   * Custom (non-bubble) children render flush with the message edge; wrap
+   * them in a ghost bubble (`<ChatMessageBubble variant="ghost">`) to align
+   * them with the bubble's text column, and add `width="100%"` when they
+   * should span the full message column.
+   */
   children: ReactNode;
   avatar?: ReactNode;
   /**

package/src/Chat/ChatMessageBubble.doc.mjs

@@ -45,6 +45,11 @@ export const docs = {
       type: "'first' | 'middle' | 'last'",
       description: 'Position within a multi-bubble group. Controls corner radius reduction on the sender side. Leave unset for standalone bubbles (full radius).',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description: 'Width of the bubble (number = pixels, string = used as-is). When set, replaces the default max(80%, 280px) width cap. Combine with variant="ghost" to let custom content (an artifact card, attachments) span the full message column.',
+    },
   ],
 };
 
@@ -59,6 +64,7 @@ export const docsZh = {
     name: '气泡上方渲染的发送者名称，与气泡文本内边距对齐。用于消息中的第一个气泡。',
     metadata: '气泡下方渲染的元数据内容，与气泡文本内边距对齐。用于消息中的最后一个气泡。',
     group: '多气泡组中的位置。控制发送者侧的圆角缩减。',
+    width: '气泡宽度（数字 = 像素，字符串 = 按原样使用）。设置后替代默认的 max(80%, 280px) 宽度上限；与 ghost 变体组合可让自定义内容占满消息列宽度。',
   },
 };
 
@@ -74,5 +80,6 @@ export const docsDense = {
     displayName: 'sender name above bubble, aligned w/ bubble padding',
     metadata: 'metadata below bubble, aligned w/ bubble padding',
     group: 'position in multi-bubble group; controls corner radius reduction',
+    width: 'bubble width (number=px, string=as-is); replaces default max(80%,280px) cap; ghost+width="100%" spans full message column',
   },
 };

package/src/Chat/ChatMessageBubble.test.tsx

@@ -7,6 +7,16 @@ import {ChatMessageBubble} from './ChatMessageBubble';
 import {ChatMessageList} from './ChatMessageList';
 import {ChatMessageMetadata} from './ChatMessageMetadata';
 
+/**
+ * Classes shared between two elements. StyleX emits one atomic class per
+ * style declaration, so two elements share a class exactly when they share
+ * a declaration — e.g. the same density paddingInline.
+ */
+function sharedClasses(a: Element, b: Element): string[] {
+  const bClasses = new Set(Array.from(b.classList));
+  return Array.from(a.classList).filter(c => bClasses.has(c));
+}
+
 describe('ChatMessageBubble', () => {
   it('renders children', () => {
     render(
@@ -29,9 +39,7 @@ describe('ChatMessageBubble', () => {
 
   it('defaults to assistant when no context', () => {
     render(
-      <ChatMessageBubble data-testid="bubble">
-        Standalone
-      </ChatMessageBubble>,
+      <ChatMessageBubble data-testid="bubble">Standalone</ChatMessageBubble>,
     );
     const el = screen.getByTestId('bubble');
     expect(el.className).toContain('assistant');
@@ -41,9 +49,7 @@ describe('ChatMessageBubble', () => {
     render(
       <ChatMessageList density="compact">
         <ChatMessage sender="assistant">
-          <ChatMessageBubble data-testid="bubble">
-            Compact
-          </ChatMessageBubble>
+          <ChatMessageBubble data-testid="bubble">Compact</ChatMessageBubble>
         </ChatMessage>
       </ChatMessageList>,
     );
@@ -59,6 +65,89 @@ describe('ChatMessageBubble', () => {
     );
     expect(screen.getByTestId('my-bubble')).toBeTruthy();
   });
+
+  it('ghost variant aligns custom content with the bubble text column (#2574)', () => {
+    // Repro from the issue: a raw child renders flush with the message
+    // edge — it carries none of the inset the bubble's name slot gets.
+    const {container} = render(
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble name="Navi">Hello</ChatMessageBubble>
+        <div data-testid="raw">Artifact card</div>
+        <ChatMessageBubble variant="ghost" data-testid="ghost">
+          Artifact card
+        </ChatMessageBubble>
+      </ChatMessage>,
+    );
+    const nameSlot = container.querySelector('[data-chat-name]')!;
+    expect(nameSlot).toBeTruthy();
+
+    // Unwrapped custom content: no shared inset — the misalignment case.
+    expect(sharedClasses(screen.getByTestId('raw'), nameSlot)).toEqual([]);
+
+    // Ghost-wrapped content: shares the bubble slot's paddingInline
+    // declaration, so its text column matches the filled bubble exactly.
+    expect(
+      sharedClasses(screen.getByTestId('ghost'), nameSlot).length,
+    ).toBeGreaterThan(0);
+  });
+
+  it('ghost inset tracks message density', () => {
+    const renderAtDensity = (density: 'balanced' | 'spacious') => {
+      const {container} = render(
+        <ChatMessage sender="assistant" density={density}>
+          <ChatMessageBubble name="Navi">Hello</ChatMessageBubble>
+          <ChatMessageBubble variant="ghost" data-testid={`ghost-${density}`}>
+            Card
+          </ChatMessageBubble>
+        </ChatMessage>,
+      );
+      return sharedClasses(
+        screen.getByTestId(`ghost-${density}`),
+        container.querySelector('[data-chat-name]')!,
+      );
+    };
+
+    const balancedInset = renderAtDensity('balanced');
+    const spaciousInset = renderAtDensity('spacious');
+
+    // Both densities align with their own bubble's slot padding...
+    expect(balancedInset.length).toBeGreaterThan(0);
+    expect(spaciousInset.length).toBeGreaterThan(0);
+    // ...and spacious uses a wider inset than balanced.
+    expect(spaciousInset).not.toEqual(balancedInset);
+  });
+
+  it('width prop replaces the default width cap', () => {
+    render(
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble data-testid="capped">Text</ChatMessageBubble>
+        <ChatMessageBubble variant="ghost" width="100%" data-testid="full">
+          Card
+        </ChatMessageBubble>
+      </ChatMessage>,
+    );
+    const capped = screen.getByTestId('capped');
+    const full = screen.getByTestId('full');
+
+    // Default bubbles keep the cap; a width bubble replaces it with none.
+    expect(getComputedStyle(capped).maxWidth).toMatch(/^max\(80%,\s*280px\)$/);
+    expect(getComputedStyle(full).maxWidth).toBe('none');
+    // The dynamic width value is set on the element (string passes through).
+    expect(full.getAttribute('style')).toContain('100%');
+  });
+
+  it('numeric width is treated as pixels', () => {
+    render(
+      <ChatMessage sender="assistant">
+        <ChatMessageBubble width={420} data-testid="fixed">
+          Artifact
+        </ChatMessageBubble>
+      </ChatMessage>,
+    );
+    expect(screen.getByTestId('fixed').getAttribute('style')).toContain(
+      '420px',
+    );
+  });
 });
 
 describe('ChatMessageMetadata', () => {

package/src/Chat/ChatMessageBubble.tsx

@@ -15,6 +15,9 @@
  * - If you use bubbles on one side (e.g. assistant), use them consistently
  *   for all messages on that side. Use `ghost` variant for content that
  *   needs alignment without a visual boundary.
+ * - For custom content (cards, attachments, citations) that should span
+ *   the full message column instead of the default width cap, combine
+ *   `ghost` with `width="100%"` (#2574).
  * - Put `name` on the first bubble in a message, `metadata` on the last.
  * - For unbubbled messages, use ChatMessage's `name` and `metadata`
  *   props instead.
@@ -36,6 +39,7 @@ import {
 } from '../theme/tokens.stylex';
 import {useChatMessageContext} from './ChatContext';
 import {mergeProps} from '../utils';
+import type {SizeValue} from '../utils/types';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
@@ -83,6 +87,15 @@ export interface ChatMessageBubbleProps extends BaseProps<HTMLDivElement> {
    * Leave unset for standalone bubbles (full radius).
    */
   group?: 'first' | 'middle' | 'last';
+
+  /**
+   * Width of the bubble.
+   * Numbers are treated as pixels, strings are used as-is (e.g. "100%").
+   * When set, replaces the default `max(80%, 280px)` width cap; leave unset
+   * to keep the cap. Combine with `variant="ghost"` to let custom content
+   * (an artifact card, attachments) span the full message column.
+   */
+  width?: SizeValue;
 }
 
 // =============================================================================
@@ -189,6 +202,16 @@ const styles = stylex.create({
   },
 });
 
+// Dynamic styles for sizing props
+const dynamicStyles = stylex.create({
+  sizing: (width: SizeValue) => ({
+    width,
+    // An explicit width replaces the default cap — a full-column or
+    // fixed-width bubble shouldn't also be clamped by max(80%, 280px).
+    maxWidth: 'none',
+  }),
+});
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -216,6 +239,7 @@ export function ChatMessageBubble({
   name,
   metadata,
   group,
+  width,
   xstyle,
   className,
   style: styleProp,
@@ -292,6 +316,7 @@ export function ChatMessageBubble({
             paddingStyle,
             variant === 'ghost' && styles.paddingBlockNone,
             groupStyle,
+            width != null && dynamicStyles.sizing(width),
             xstyle,
           ),
           className,

package/src/Chat/ChatTokenizedText.tsx

@@ -74,7 +74,7 @@ function isCustomToken(
 }
 
 function escapeRegExp(str: string): string {
-  return str.replace(/[.*+?^${}()|[\\]\\]/g, '\\$&');
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
 // =============================================================================

package/src/CheckboxInput/CheckboxInput.tsx

@@ -81,6 +81,26 @@ const styles = stylex.create({
     opacity: 0,
     cursor: 'pointer',
     zIndex: 1,
+    minInlineSize: {
+      default: null,
+      '@media (pointer: coarse)': '24px',
+    },
+    minBlockSize: {
+      default: null,
+      '@media (pointer: coarse)': '24px',
+    },
+    insetBlockStart: {
+      default: null,
+      '@media (pointer: coarse)': '50%',
+    },
+    insetInlineStart: {
+      default: null,
+      '@media (pointer: coarse)': '50%',
+    },
+    transform: {
+      default: null,
+      '@media (pointer: coarse)': 'translate(-50%, -50%)',
+    },
   },
   inputDisabled: {
     cursor: 'not-allowed',

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -146,6 +146,9 @@ export const docs = {
       {className: 'astryx-codeblock-title', visualProps: ['size', 'language']},
       {className: 'astryx-codeblock-copy-button'},
     ],
+    vars: [
+      {name: '--_codeblock-gutter-width', description: 'Width of the line-number gutter, computed from the digit count of the last line so the code column starts at a stable offset.', default: '2ch', private: true},
+    ],
   },
   usage: {
     description: 'CodeBlock renders syntax-highlighted code with line numbers, a copy button, and optional collapsible sections. Use CodeBlock for multi-line snippets like source files, terminal commands, and configuration examples. Use Code for inline references to function names, variables, or CLI flags within body text.',

package/src/CommandPalette/CommandPaletteFooter.tsx

@@ -24,6 +24,7 @@ import {
 } from '../theme/tokens.stylex';
 import {Kbd} from '../Kbd';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 const styles = stylex.create({
   footer: {
@@ -85,6 +86,8 @@ export function CommandPaletteFooter({
   style,
   ...props
 }: CommandPaletteFooterProps) {
+  const t = useTranslator();
+
   return (
     <div
       ref={ref}
@@ -100,15 +103,15 @@ export function CommandPaletteFooter({
           <span {...stylex.props(styles.hint)}>
             <Kbd keys="up" />
             <Kbd keys="down" />
-            Navigate
+            {t('@astryx.commandPalette.footer.navigate')}
           </span>
           <span {...stylex.props(styles.hint)}>
             <Kbd keys="enter" />
-            Select
+            {t('@astryx.commandPalette.footer.select')}
           </span>
           <span {...stylex.props(styles.hint)}>
             <Kbd keys="escape" />
-            Close
+            {t('@astryx.commandPalette.footer.close')}
           </span>
         </>
       )}

package/src/ComplexSelector/ComplexSelector.doc.mjs

@@ -1,5 +1,14 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/**
+ * @file ComplexSelector.doc.mjs
+ * @input ComplexSelector public API and composition contract
+ * @output Exports full and dense component documentation
+ * @position Core documentation consumed by CLI and Storybook autodocs
+ *
+ * SYNC: When modified, update ComplexSelector.tsx, tests, and stories.
+ */
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -19,7 +28,10 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-complex-selector', visualProps: ['size', 'status']},
+      {
+        className: 'astryx-complex-selector',
+        visualProps: ['variant', 'size', 'status'],
+      },
       {
         className: 'astryx-complex-selector-indicator-icon',
         states: ['state'],
@@ -32,7 +44,7 @@ export const docs = {
       name: 'ComplexSelector',
       displayName: 'Complex Selector',
       description:
-        'A field and dialog-popover shell for custom selector content.',
+        'An input or toolbar trigger and dialog-popover shell for custom selector content.',
       props: [
         {
           name: 'label',
@@ -93,9 +105,21 @@ export const docs = {
         {
           name: 'size',
           type: "'sm' | 'md' | 'lg'",
-          description: 'Trigger and field size.',
+          description: 'Exact trigger height: sm 28px, md 32px, or lg 36px.',
           default: "'md'",
         },
+        {
+          name: 'variant',
+          type: "'input' | 'ghost'",
+          description:
+            'Visual trigger style. Input is the bordered form treatment; ghost matches toolbar buttons.',
+          default: "'input'",
+        },
+        {
+          name: 'startIcon',
+          type: 'ReactNode | IconType',
+          description: 'Icon displayed at the start of the trigger.',
+        },
         {
           name: 'width',
           type: 'SizeValue',
@@ -107,6 +131,18 @@ export const docs = {
           description: 'Popup placement.',
           default: "'below'",
         },
+        {
+          name: 'alignment',
+          type: "'start' | 'center' | 'end'",
+          description: 'Popup alignment along the placement axis.',
+          default: "'start'",
+        },
+        {
+          name: 'handleRef',
+          type: 'React.Ref<ComplexSelectorHandle>',
+          description:
+            'Imperative handle for programmatic control. Exposes open(), close(), toggle(), and isOpen().',
+        },
         {
           name: 'contentXstyle',
           type: 'StyleXStyles',
@@ -119,6 +155,16 @@ export const docs = {
     description:
       'Use ComplexSelector when a selection needs richer custom content than a Selector option row. It is intentionally one component: ComplexSelector owns the field, trigger, popover, focus restore, and changeAction flow, while the content render prop owns the selector-specific accessible structure.',
     bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use variant="ghost" with a startIcon when the selector is triggered from a toolbar. Use alignment="end" when a wide surface should align its end edge to the trigger.',
+      },
+      {
+        guidance: true,
+        description:
+          'For staged editors, keep draft state in the composed content and call the provided onChange helper only from Apply. Cancel or dismiss without committing.',
+      },
       {
         guidance: true,
         description:
@@ -164,7 +210,7 @@ export const docsDense = {
   group: 'Selector',
   category: 'Data Input',
   description:
-    'Field+dialog-popover shell for rich custom selectors. Content gets value/onChange/close/state; content owns semantics. Use focus hooks and evaluate custom content against WCAG 2.2.',
+    'Input/ghost trigger + dialog-popover shell for rich custom selectors. Content gets value/onChange/close/state; content owns semantics. Use focus hooks and evaluate custom content against WCAG 2.2.',
   usage: {
     description:
       'Use when a selection needs richer custom content than a Selector row. One component: it owns field, trigger, popover, focus restore, and changeAction; the render prop owns the selector-specific accessible structure.',
@@ -211,10 +257,13 @@ export const docsDense = {
     value: 'Controlled value.',
     onChange: 'Commit value.',
     changeAction: 'Async action after onChange; drives optimistic value/busy.',
-    children:
-      'Render custom dialog content from (value,onChange,close,state).',
+    children: 'Render custom dialog content from (value,onChange,close,state).',
     triggerLabel: 'Closed trigger label/content.',
+    variant: 'input for forms; ghost for toolbar triggers.',
+    startIcon: 'Leading trigger icon.',
     placement: 'Popup placement.',
+    alignment: 'Popup alignment.',
+    handleRef: 'Imperative open/close/toggle handle.',
     accessibility:
       'Custom content must provide its own accessible structure. Use focus hooks and evaluate against WCAG 2.2.',
   },