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

package/src/Selector/Selector.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: 'Selector',
@@ -21,10 +21,16 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-selector', visualProps: ['size', 'status']},
+      {
+        className: 'astryx-selector',
+        visualProps: ['variant', 'size', 'status'],
+        states: ['disabled'],
+      },
       {className: 'astryx-selector-option'},
+      {className: 'astryx-selector-empty-state'},
       {className: 'astryx-selector-clear-icon'},
       {className: 'astryx-selector-indicator-icon', states: ['state']},
+      {className: 'astryx-selector-check'},
     ],
   },
   description: 'Dropdown selector for choosing from a list of options.',
@@ -63,7 +69,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.',
       default: 'false',
     },
     {
@@ -84,6 +90,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: 'isDisabled',
       type: 'boolean',
@@ -132,10 +145,10 @@ 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',
@@ -159,7 +172,7 @@ export const docs = {
   components: [{name: 'SelectorOption'}],
   usage: {
     description:
-      'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options.',
+      'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options. Keyboard typeahead matches a native select: typing on the focused closed trigger selects the matching option directly, repeated presses cycle through options sharing a first letter, and spaces count as match characters ("new y" reaches "New York"). With the menu open, typing moves the highlight and Enter commits. With hasSearch, typing on the closed trigger opens the popup and seeds the search input.',
     bestPractices: [
       {
         guidance: true,
@@ -186,6 +199,11 @@ export const docs = {
         description:
           'Use inside InputGroup only when the selector needs a short prefix or suffix addon as part of one decorated input surface.',
       },
+      {
+        guidance: true,
+        description:
+          'Use variant="ghost" when a 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:
@@ -252,11 +270,11 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
-      'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options.',
+      'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options. Keyboard typeahead matches a native select: typing on the focused closed trigger selects the matching option directly, repeated presses cycle through options sharing a first letter, and spaces count as match characters ("new y" reaches "New York"). With the menu open, typing moves the highlight and Enter commits. With hasSearch, typing on the closed trigger opens the popup and seeds the search input.',
     bestPractices: [
       {
         guidance: true,
@@ -344,11 +362,11 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   usage: {
     description:
-      'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options.',
+      'A dropdown selector for choosing a single value from a list of options. Supports labels, validation, descriptions, and required/optional states. Use it in forms and settings when presenting a moderate number of options. Keyboard typeahead matches a native select: typing on the focused closed trigger selects the matching option directly, repeated presses cycle through options sharing a first letter, and spaces count as match characters ("new y" reaches "New York"). With the menu open, typing moves the highlight and Enter commits. With hasSearch, typing on the closed trigger opens the popup and seeds the search input.',
     bestPractices: [
       {
         guidance: true,
@@ -375,6 +393,11 @@ export const docsDense = {
         description:
           'Use inside InputGroup only when the selector needs a short prefix or suffix addon.',
       },
+      {
+        guidance: true,
+        description:
+          'Use variant="ghost" in toolbars with ghost buttons; prefer statusVariant="tooltip" for compact validation status.',
+      },
       {
         guidance: false,
         description: