@coinbase/cds-mcp-server 8.52.2 → 8.53.1

package/mcp-docs/web/components/Alert.txt

@@ -157,7 +157,7 @@ function AlertOnModalExample() {
 | `onDidClose` | `((() => void) & (() => void))` | No | `-` | Callback fired after the component is closed. |
 | `onDismissActionPress` | `(() => void)` | No | `-` | Callback function fired when the dismiss action is pressed |
 | `onPreferredActionPress` | `(() => void)` | No | `-` | Callback function fired when the preferred action is pressed |
-| `pictogram` | `key \| done \| loop \| cardSuccess \| warning \| error \| add \| arrowsUpDown \| browser \| calculator \| calendar \| checkmark \| clock \| coinbaseOneLogo \| crystalBallInsight \| derivativesProduct \| email \| gasFees \| identityCard \| instantUnstakingClock \| laptop \| learningRewardsProduct \| lock \| passport \| paypal \| phone \| pieChartData \| pieChartWithArrow \| planet \| robot \| safe \| securityKey \| settings \| shield \| support \| taxes \| tokenSales \| trading \| verifiedPools \| wallet \| 2fa \| accountsNavigation \| accreditedInvestor \| addCard \| addPayment \| addPhone \| addressBook \| addToWatchlist \| addWallet \| advancedTradingDesktop \| advancedTradingNavigation \| advancedTradingRebates \| agent \| alerts \| alertsCoinbaseOne \| analyticsNavigation \| apartOfDropsNft \| applyForHigherLimits \| apyInterest \| assetEncryption \| assetHubNavigation \| assetManagement \| assetManagementNavigation \| assetMeasurements \| assetMovement \| authenticationApp \| authenticator \| authenticatorAlt \| authenticatorProgress \| avatarAa \| avatarAb \| avatarAc \| avatarAd \| avatarAe \| avatarAf \| avatarAg \| avatarAh \| avatarAi \| avatarAj \| avatarBa \| avatarBb \| avatarBc \| avatarBd \| avatarBe \| avatarBf \| avatarBg \| avatarBh \| avatarBi \| avatarBj \| avatarCa \| avatarCb \| avatarCc \| avatarCd \| avatarCe \| avatarCf \| avatarCg \| avatarCh \| avatarCi \| avatarCj \| avatarDa \| avatarDb \| avatarDc \| avatarDd \| avatarDe \| avatarDf \| avatarDg \| avatarDh \| avatarDi \| avatarDj \| avatarEa \| avatarEb \| avatarEc \| avatarEd \| avatarEe \| avatarEf \| avatarEg \| avatarEh \| avatarEi \| avatarEj \| avatarFa \| avatarFb \| avatarFc \| avatarFd \| avatarFe \| avatarFf \| avatarFg \| avatarFh \| avatarFi \| avatarFj \| avatarGa \| avatarGb \| avatarGc \| avatarGd \| avatarGe \| avatarGf \| avatarGg \| avatarGh \| avatarGi \| avatarGj \| avatarHa \| avatarHb \| avatarHc \| avatarHd \| avatarHe \| avatarHf \| avatarHg \| avatarHh \| avatarHi \| avatarHj \| avatarIa \| avatarIb \| avatarIc \| avatarId \| avatarIe \| avatarIf \| avatarIg \| avatarIh \| avatarIi \| avatarIj \| avatarJa \| avatarJb \| avatarJc \| avatarJd \| avatarJe \| avatarJf \| avatarJg \| avatarJh \| avatarJi \| avatarJj \| barChart \| baseAscend \| baseCertificateStar \| baseChartSmall \| baseChatBubbleHeart \| baseCheckSmall \| baseCoinCryptoSmall \| baseCoinNetworkSmall \| baseCoinStack \| baseCoinStar \| baseComet \| baseComputer \| baseConfetti \| baseConnectApps \| baseConnectSmall \| baseCreatorCoin \| baseDecentralizationSmall \| baseDiamondSmall \| baseDiamondTrophy \| baseDoor \| baseEarnedBadge \| baseEmptySmall \| baseErrorButterflySmall \| baseErrorSmall \| baseExchange \| baseFire \| baseGem \| baseGlobe \| baseHandStar \| baseLayout \| baseLightningbolt \| baseLoadingSmall \| baseLocationSmall \| baseLogo \| baseLogoNavigation \| baseMedal \| baseMessaging \| baseMintNftSmall \| baseNetworkSmall \| baseNftSmall \| basePaycoinSmall \| basePeopleSmall \| basePiechartSmall \| basePlant \| basePower \| baseRibbon \| baseRocket \| baseRockon \| baseSaved \| baseSecuritySmall \| baseSendSmall \| baseSignin \| baseSmile \| baseStack \| baseStar \| baseTargetSmall \| baseTile \| bigBtcSend \| bitcoin \| bitcoinPizza \| bitcoinRewards \| bitcoinWhitePaper \| blockchainConnection \| bonusFivePercent \| bonusTwoPercent \| borrowCoins \| borrowingLending \| borrowNavigation \| browserMultiPlatform \| browserTransaction \| btcOneHundred \| bundle \| businessProduct \| calendarCaution \| calendarHighlight \| candleSticksGraph \| cardBlocked \| cardDeclined \| cardNavigation \| cb1BankTransfers \| chart \| chat \| cloudNavigation \| coinbaseLogoAdvancedBrand \| coinbaseLogoNavigation \| coinbaseOneAuthenticator \| coinbaseOneChat \| coinbaseOneEarn \| coinbaseOneEarnCoins \| coinbaseOneEarnCoinsLogo \| coinbaseOneFiat \| coinbaseOneProductIcon \| coinbaseOneProductInvestWeekly \| coinbaseOneRefreshed \| coinbaseOneShield \| coinbaseOneTrade \| coinbaseOneTrusted \| coinbaseOneUnlimitedRewards \| coinbaseUnlockOffers \| coinbaseWalletApp \| coinFocus \| coinShare \| coldStorageCheck \| collectionOfAssets \| commerceCheckout \| commerceInvoice \| commerceNavigation \| commodities \| completeQuiz \| complianceNavigation \| congratulations \| connectNavigation \| contactInfo \| controlWalletStorage \| creative \| creditCard \| crypto101 \| cryptoCard \| cryptoCoins \| cryptoFolder \| custodialJourney \| custodyNavigation \| dataMarketplaceNavigation \| decentralizationEverything \| decentralizedExchange \| decentralizedIdentity \| decentralizedWeb3 \| defiEarnMoment \| delegate \| delegateNavigation \| derivativesNavigation \| developerPlatformNavigation \| developerSDKNavigation \| directDepositNavigation \| dollarShowcase \| driversLicense \| driversLicenseWheel \| earnCoins \| earnGraph \| earnNavigation \| easyToUse \| economyGlobal \| emailAndMessages \| enableVoting \| envelope \| ethereumFocus \| ethRewards \| ethStaking \| ethStakingChart \| ethStakingRewards \| ethToken \| exchangeNavigation \| explore \| fast \| faucetNavigation \| feesRestriction \| fiat \| finance \| findYourSelection \| formDownload \| futures \| futuresCoinbaseOne \| gem \| genericCountryIDCard \| getStarted \| giftbox \| globalConnections \| globalPayments \| globalTransactions \| googleAuthenticator \| governance \| hardwareWallet \| helpCenterNavigation \| higherLimits \| holdingCoin \| idBlock \| idError \| idVerification \| increaseLimits \| institutionalNavigation \| institutions \| internationalExchangeNavigation \| internet \| investGraph \| laptopCharts \| laptopVideo \| layerNetworks \| leadGraph \| learn \| learningRewardsNavigation \| lightbulbLearn \| lightningNetworkSend \| linkYourAccount \| listingFees \| locationUsa \| lowFees \| manageWeb3SignersAcct \| miningCoins \| mintedNft \| mobileCharts \| mobileError \| mobileNotifcation \| mobileSuccess \| mobileWarning \| moneyCrypto \| moneyEarn \| moneySwift \| monitoringPerformance \| moreThanBitcoin \| multiAccountsAndCards \| multiPlatform \| multipleAssets \| musicAndSounds \| myNumberCard \| newUserChecklistBuyCrypto \| newUserChecklistCompleteAccount \| newUserChecklistVerifyId \| nftAvatar \| nftLibrary \| nftNavigation \| noAnnualFee \| noNftFound \| notificationHubAnalysis \| notificationHubNews \| notificationHubPortfolio \| notificationHubSocial \| notifications \| noVisibility \| noWiFi \| orders \| outage \| partialCoins \| participateNavigation \| passwordWalletLocked \| payNavigation \| peerToPeer \| pieChart \| pieChartWithArrowBlue \| pizza \| pluginBrowser \| podium \| positiveReviews \| predictionMarkets \| premiumInvestor \| priceTracking \| primeMobileApp \| primeNavigation \| privateClientNavigation \| proNavigation \| protectionPlan \| queryTransactNavigation \| receipt \| recurringPurchases \| restaking \| reviewAndAdd \| rewardsNavigation \| riskStaking \| rosettaNavigation \| securedAssets \| security \| securityCoinShield \| seedPhrase \| selectAddNft \| selfCustodyWallet \| selfServe \| sellSendAnytime \| sendPaymentToOthers \| settled \| sideChainSide \| signInNavigation \| smsAuthenticate \| sparkleCoinbaseOne \| ssnCard \| stableCoinMetaphor \| stacking \| stakingGraph \| standWithCryptoLogoNavigation \| startToday \| strongInfo \| strongWarning \| successPhone \| supportChat \| takeQuiz \| target \| taxBeta \| taxCenterNavigation \| taxesArrangement \| taxSeason \| timingCheck \| tokenBaskets \| transferSend \| transistor \| trendingAssets \| trusted \| tryAgainLater \| twoBonus \| typeScript \| ubiKey \| usaProduct \| usdcEarn \| usdcInterest \| usdcLoan \| usdcLogo \| usdcRewards \| usdcRewardsRibbon \| usdcToken \| venturesNavigation \| videoCalendar \| videoContent \| waiting \| waitingForConsensus \| walletAsServiceNavigation \| walletDeposit \| walletError \| walletExchange \| walletLinkNavigation \| walletLogoNavigation \| walletNavigation \| walletPassword \| walletSuccess \| walletWarning \| winBTC \| worldwide \| wrapEth` | No | `-` | Illustration pictogram name for alert |
+| `pictogram` | `key \| done \| loop \| cardSuccess \| warning \| error \| add \| arrowsUpDown \| browser \| calculator \| calendar \| checkmark \| clock \| coinbaseOneLogo \| crystalBallInsight \| derivativesProduct \| download \| email \| gasFees \| identityCard \| instantUnstakingClock \| laptop \| learningRewardsProduct \| lock \| passport \| paypal \| phone \| pieChartData \| pieChartWithArrow \| planet \| robot \| safe \| securityKey \| settings \| shield \| support \| taxes \| tokenSales \| trading \| verifiedPools \| wallet \| 2fa \| accountsNavigation \| accreditedInvestor \| addCard \| addPayment \| addPhone \| addressBook \| addToWatchlist \| addWallet \| advancedTradingDesktop \| advancedTradingNavigation \| advancedTradingRebates \| agent \| alerts \| alertsCoinbaseOne \| analyticsNavigation \| apartOfDropsNft \| applyForHigherLimits \| apyInterest \| assetEncryption \| assetHubNavigation \| assetManagement \| assetManagementNavigation \| assetMeasurements \| assetMovement \| authenticationApp \| authenticator \| authenticatorAlt \| authenticatorProgress \| avatarAa \| avatarAb \| avatarAc \| avatarAd \| avatarAe \| avatarAf \| avatarAg \| avatarAh \| avatarAi \| avatarAj \| avatarBa \| avatarBb \| avatarBc \| avatarBd \| avatarBe \| avatarBf \| avatarBg \| avatarBh \| avatarBi \| avatarBj \| avatarCa \| avatarCb \| avatarCc \| avatarCd \| avatarCe \| avatarCf \| avatarCg \| avatarCh \| avatarCi \| avatarCj \| avatarDa \| avatarDb \| avatarDc \| avatarDd \| avatarDe \| avatarDf \| avatarDg \| avatarDh \| avatarDi \| avatarDj \| avatarEa \| avatarEb \| avatarEc \| avatarEd \| avatarEe \| avatarEf \| avatarEg \| avatarEh \| avatarEi \| avatarEj \| avatarFa \| avatarFb \| avatarFc \| avatarFd \| avatarFe \| avatarFf \| avatarFg \| avatarFh \| avatarFi \| avatarFj \| avatarGa \| avatarGb \| avatarGc \| avatarGd \| avatarGe \| avatarGf \| avatarGg \| avatarGh \| avatarGi \| avatarGj \| avatarHa \| avatarHb \| avatarHc \| avatarHd \| avatarHe \| avatarHf \| avatarHg \| avatarHh \| avatarHi \| avatarHj \| avatarIa \| avatarIb \| avatarIc \| avatarId \| avatarIe \| avatarIf \| avatarIg \| avatarIh \| avatarIi \| avatarIj \| avatarJa \| avatarJb \| avatarJc \| avatarJd \| avatarJe \| avatarJf \| avatarJg \| avatarJh \| avatarJi \| avatarJj \| barChart \| baseAscend \| baseCertificateStar \| baseChartSmall \| baseChatBubbleHeart \| baseCheckSmall \| baseCoinCryptoSmall \| baseCoinNetworkSmall \| baseCoinStack \| baseCoinStar \| baseComet \| baseComputer \| baseConfetti \| baseConnectApps \| baseConnectSmall \| baseCreatorCoin \| baseDecentralizationSmall \| baseDiamondSmall \| baseDiamondTrophy \| baseDoor \| baseEarnedBadge \| baseEmptySmall \| baseErrorButterflySmall \| baseErrorSmall \| baseExchange \| baseFire \| baseGem \| baseGlobe \| baseHandStar \| baseLayout \| baseLightningbolt \| baseLoadingSmall \| baseLocationSmall \| baseLogo \| baseLogoNavigation \| baseMedal \| baseMessaging \| baseMintNftSmall \| baseNetworkSmall \| baseNftSmall \| basePaycoinSmall \| basePeopleSmall \| basePiechartSmall \| basePlant \| basePower \| baseRibbon \| baseRocket \| baseRockon \| baseSaved \| baseSecuritySmall \| baseSendSmall \| baseSignin \| baseSmile \| baseStack \| baseStar \| baseTargetSmall \| baseTile \| bigBtcSend \| bitcoin \| bitcoinPizza \| bitcoinRewards \| bitcoinWhitePaper \| blockchainConnection \| bonusFivePercent \| bonusTwoPercent \| borrowCoins \| borrowingLending \| borrowNavigation \| browserMultiPlatform \| browserTransaction \| btcOneHundred \| bundle \| businessProduct \| calendarCaution \| calendarHighlight \| candleSticksGraph \| cardBlocked \| cardDeclined \| cardNavigation \| cb1BankTransfers \| chart \| chat \| cloudNavigation \| coinbaseLogoAdvancedBrand \| coinbaseLogoNavigation \| coinbaseOneAuthenticator \| coinbaseOneChat \| coinbaseOneEarn \| coinbaseOneEarnCoins \| coinbaseOneEarnCoinsLogo \| coinbaseOneFiat \| coinbaseOneProductIcon \| coinbaseOneProductInvestWeekly \| coinbaseOneRefreshed \| coinbaseOneShield \| coinbaseOneTrade \| coinbaseOneTrusted \| coinbaseOneUnlimitedRewards \| coinbaseUnlockOffers \| coinbaseWalletApp \| coinFocus \| coinShare \| coldStorageCheck \| collectionOfAssets \| commerceCheckout \| commerceInvoice \| commerceNavigation \| commodities \| completeQuiz \| complianceNavigation \| congratulations \| connectNavigation \| contactInfo \| controlWalletStorage \| creative \| creditCard \| crypto101 \| cryptoCard \| cryptoCoins \| cryptoFolder \| custodialJourney \| custodyNavigation \| dataMarketplaceNavigation \| decentralizationEverything \| decentralizedExchange \| decentralizedIdentity \| decentralizedWeb3 \| defiEarnMoment \| delegate \| delegateNavigation \| derivativesNavigation \| developerPlatformNavigation \| developerSDKNavigation \| directDepositNavigation \| dollarShowcase \| driversLicense \| driversLicenseWheel \| earnCoins \| earnGraph \| earnNavigation \| easyToUse \| economyGlobal \| emailAndMessages \| enableVoting \| envelope \| ethereumFocus \| ethRewards \| ethStaking \| ethStakingChart \| ethStakingRewards \| ethToken \| exchangeNavigation \| explore \| fast \| faucetNavigation \| feesRestriction \| fiat \| finance \| findYourSelection \| formDownload \| futures \| futuresCoinbaseOne \| gem \| genericCountryIDCard \| getStarted \| giftbox \| globalConnections \| globalPayments \| globalTransactions \| googleAuthenticator \| governance \| hardwareWallet \| helpCenterNavigation \| higherLimits \| holdingCoin \| idBlock \| idError \| idVerification \| increaseLimits \| institutionalNavigation \| institutions \| instoAccount \| instoAddressBook \| instoAdvancedTradingRebates \| instoApyInterest \| instoAuthenticatorProgress \| instoBorrowingLending \| instoCoinbaseOneShield \| instoCrypto101 \| instoDecentralizationEverything \| instoDecentralizedExchange \| instoDecentralizedWeb3 \| instoDelegate \| instoEarnCoins \| instoEarnGraph \| instoEth \| instoEthRewards \| instoEthStakingChart \| instoFiat \| instoGem \| instoKey \| instoNftLibrary \| instoPasswordWalletLocked \| instoprimeMobileApp \| instoRestaking \| instoRiskStaking \| instoSelfCustodyWallet \| instoStakingGraph \| instoTrading \| instoWalletWarning \| internationalExchangeNavigation \| internet \| investGraph \| laptopCharts \| laptopVideo \| layerNetworks \| leadGraph \| learn \| learningRewardsNavigation \| lightbulbLearn \| lightningNetworkSend \| linkYourAccount \| listingFees \| locationUsa \| lowFees \| manageWeb3SignersAcct \| miningCoins \| mintedNft \| mobileCharts \| mobileError \| mobileNotifcation \| mobileSuccess \| mobileWarning \| moneyCrypto \| moneyEarn \| moneySwift \| monitoringPerformance \| moreThanBitcoin \| multiAccountsAndCards \| multiPlatform \| multipleAssets \| musicAndSounds \| myNumberCard \| newUserChecklistBuyCrypto \| newUserChecklistCompleteAccount \| newUserChecklistVerifyId \| nftAvatar \| nftLibrary \| nftNavigation \| noAnnualFee \| noNftFound \| notificationHubAnalysis \| notificationHubNews \| notificationHubPortfolio \| notificationHubSocial \| notifications \| noVisibility \| noWiFi \| orders \| outage \| partialCoins \| participateNavigation \| passwordWalletLocked \| payNavigation \| peerToPeer \| pieChart \| pieChartWithArrowBlue \| pizza \| pluginBrowser \| podium \| positiveReviews \| predictionMarkets \| premiumInvestor \| priceTracking \| primeMobileApp \| primeNavigation \| privateClientNavigation \| proNavigation \| protectionPlan \| queryTransactNavigation \| receipt \| recurringPurchases \| restaking \| reviewAndAdd \| rewardsNavigation \| riskStaking \| rosettaNavigation \| securedAssets \| security \| securityCoinShield \| seedPhrase \| selectAddNft \| selfCustodyWallet \| selfServe \| sellSendAnytime \| sendPaymentToOthers \| settled \| sideChainSide \| signInNavigation \| smsAuthenticate \| sparkleCoinbaseOne \| ssnCard \| stableCoinMetaphor \| stacking \| stakingGraph \| standWithCryptoLogoNavigation \| startToday \| strongInfo \| strongWarning \| successPhone \| supportChat \| takeQuiz \| target \| taxBeta \| taxCenterNavigation \| taxesArrangement \| taxSeason \| timingCheck \| tokenBaskets \| transferSend \| transistor \| trendingAssets \| trusted \| tryAgainLater \| twoBonus \| typeScript \| ubiKey \| usaProduct \| usdcEarn \| usdcInterest \| usdcLoan \| usdcLogo \| usdcRewards \| usdcRewardsRibbon \| usdcToken \| venturesNavigation \| videoCalendar \| videoContent \| waiting \| waitingForConsensus \| walletAsServiceNavigation \| walletDeposit \| walletError \| walletExchange \| walletLinkNavigation \| walletLogoNavigation \| walletNavigation \| walletPassword \| walletSuccess \| walletWarning \| winBTC \| worldwide \| wrapEth` | No | `-` | Illustration pictogram name for alert |
 | `preferredActionVariant` | `primary \| negative` | No | `primary` | Button variant of the preferred action |
 | `ref` | `((instance: ModalRefBaseProps \| null) => void) \| RefObject<ModalRefBaseProps> \| null` | No | `-` | - |
 | `stacked` | `boolean` | No | `-` | Indicating if Alert is stacked on top of Modal |

package/mcp-docs/web/components/Combobox.txt

@@ -10,13 +10,37 @@ import { Combobox } from '@coinbase/cds-web/alpha/combobox'
 
 ## Examples
 
-### A note on search logic
+### Basics
 
-We use [fuse.js](https://www.fusejs.io/) to power the fuzzy search logic for Combobox. You can override this search logic with your own using the `filterFunction` prop.
+To start, you can provide a label, an array of options, control state.
 
-### Multi-Select
+```tsx live
+function SingleSelect() {
+  const singleSelectOptions = [
+    { value: null, label: 'Remove selection' },
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' },
+    { value: 'cherry', label: 'Cherry' },
+    { value: 'date', label: 'Date' },
+  ];
+
+  const [value, setValue] = useState('apple');
+
+  return (
+    <Combobox
+      label="Favorite fruit"
+      onChange={setValue}
+      options={singleSelectOptions}
+      placeholder="Search fruits..."
+      value={value}
+    />
+  );
+}
+```
 
-Basic multi-selection combobox with search.
+#### Multiple Selections
+
+You can also allow users to select multiple options with `type="multi"`.
 
 ```tsx live
 function MultiSelect() {
@@ -38,7 +62,7 @@ function MultiSelect() {
     { value: 'strawberry', label: 'Strawberry' },
   ];
 
-  const { value, onChange } = useMultiSelect({ initialValue: ['apple', 'banana'] });
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
 
   return (
     <Combobox
@@ -53,67 +77,80 @@ function MultiSelect() {
 }
 ```
 
-### Single Select
+### Search
 
-Standard single-selection combobox with an option to clear the current value.
+We use [fuse.js](https://www.fusejs.io/) for fuzzy search by default. You can override with `filterFunction`.
 
-```jsx live
-function SingleSelect() {
-  const singleSelectOptions = [
-    { value: null, label: 'Remove selection' },
-    { value: 'apple', label: 'Apple' },
-    { value: 'banana', label: 'Banana' },
-    { value: 'cherry', label: 'Cherry' },
-    { value: 'date', label: 'Date' },
+```tsx live
+function CustomFilter() {
+  const cryptoOptions: SelectOption[] = [
+    { value: 'btc', label: 'Bitcoin', description: 'BTC • Digital Gold' },
+    { value: 'eth', label: 'Ethereum', description: 'ETH • Smart Contracts' },
+    { value: 'usdc', label: 'USD Coin', description: 'USDC • Stablecoin' },
+    { value: 'sol', label: 'Solana', description: 'SOL • High Performance' },
   ];
 
-  const [value, setValue] = useState('apple');
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
+
+  const filterFunction = useCallback((options: SelectOption[], searchText: string) => {
+    const search = searchText.toLowerCase().trim();
+    if (!search) return options;
+    return options.filter((option) => {
+      const label = typeof option.label === 'string' ? option.label.toLowerCase() : '';
+      const description =
+        typeof option.description === 'string' ? option.description.toLowerCase() : '';
+      return label.startsWith(search) || description.startsWith(search);
+    });
+  }, []);
 
   return (
     <Combobox
-      label="Favorite fruit"
-      onChange={setValue}
-      options={singleSelectOptions}
-      placeholder="Search fruits..."
+      filterFunction={filterFunction}
+      label="Custom filter (starts with)"
+      onChange={onChange}
+      options={cryptoOptions}
+      placeholder="Type to filter..."
+      type="multi"
       value={value}
     />
   );
 }
 ```
 
-### Helper Text
+### Grouped
 
-Communicate limits or guidance by pairing helper text with multi-select usage.
+Display options under headers using `label` and `options`. Sort options by the same dimension you group by.
 
 ```tsx live
-function HelperText() {
-  const fruitOptions: SelectOption[] = [
-    { value: 'apple', label: 'Apple' },
-    { value: 'banana', label: 'Banana' },
-    { value: 'cherry', label: 'Cherry' },
-    { value: 'date', label: 'Date' },
-    { value: 'elderberry', label: 'Elderberry' },
-    { value: 'fig', label: 'Fig' },
-    { value: 'grape', label: 'Grape' },
-    { value: 'honeydew', label: 'Honeydew' },
-    { value: 'kiwi', label: 'Kiwi' },
-    { value: 'lemon', label: 'Lemon' },
-    { value: 'mango', label: 'Mango' },
-    { value: 'orange', label: 'Orange' },
-    { value: 'papaya', label: 'Papaya' },
-    { value: 'raspberry', label: 'Raspberry' },
-    { value: 'strawberry', label: 'Strawberry' },
+function GroupedOptions() {
+  const groupedOptions = [
+    {
+      label: 'Fruits',
+      options: [
+        { value: 'apple', label: 'Apple' },
+        { value: 'banana', label: 'Banana' },
+        { value: 'cherry', label: 'Cherry' },
+        { value: 'date', label: 'Date' },
+      ],
+    },
+    {
+      label: 'Vegetables',
+      options: [
+        { value: 'carrot', label: 'Carrot' },
+        { value: 'broccoli', label: 'Broccoli' },
+        { value: 'spinach', label: 'Spinach' },
+      ],
+    },
   ];
 
-  const { value, onChange } = useMultiSelect({ initialValue: ['apple', 'banana'] });
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
 
   return (
     <Combobox
-      helperText="Choose more than one fruit"
-      label="Select fruits"
+      label="Category"
       onChange={onChange}
-      options={fruitOptions}
-      placeholder="Search and select fruits..."
+      options={groupedOptions}
+      placeholder="Search by category..."
       type="multi"
       value={value}
     />
@@ -121,13 +158,75 @@ function HelperText() {
 }
 ```
 
-### Alignment
+### Accessibility
+
+Use accessibility labels to provide clear control and dropdown context. For multi-select, add remove and hidden-selection labels so screen readers can describe chip actions and +X summaries.
+
+```tsx live
+function AccessibilityProps() {
+  const priorityOptions: SelectOption[] = [
+    { value: 'high', label: 'High Priority' },
+    { value: 'medium', label: 'Medium Priority' },
+    { value: 'low', label: 'Low Priority' },
+  ];
+
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
+
+  return (
+    <Combobox
+      accessibilityLabel="Priority options list"
+      controlAccessibilityLabel="Task priority combobox"
+      hiddenSelectedOptionsLabel="priorities"
+      label="Task Priority"
+      maxSelectedOptionsToShow={1}
+      onChange={onChange}
+      options={priorityOptions}
+      placeholder="Choose priority..."
+      removeSelectedOptionAccessibilityLabel="Remove priority"
+      type="multi"
+      value={value}
+    />
+  );
+}
+```
+
+### Styling
+
+#### Selection Display Limit
+
+Cap visible chips with `maxSelectedOptionsToShow`; the rest show as +X more. Pair with `hiddenSelectedOptionsLabel` for screen readers.
+
+```tsx live
+function LimitDisplayedSelections() {
+  const countryOptions: SelectOption[] = [
+    { value: 'us', label: 'United States', description: 'North America' },
+    { value: 'ca', label: 'Canada', description: 'North America' },
+    { value: 'mx', label: 'Mexico', description: 'North America' },
+    { value: 'uk', label: 'United Kingdom', description: 'Europe' },
+    { value: 'fr', label: 'France', description: 'Europe' },
+    { value: 'de', label: 'Germany', description: 'Europe' },
+  ];
+
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
+
+  return (
+    <Combobox
+      hiddenSelectedOptionsLabel="countries"
+      label="Countries"
+      maxSelectedOptionsToShow={2}
+      onChange={onChange}
+      options={countryOptions}
+      placeholder="Select countries..."
+      type="multi"
+      value={value}
+    />
+  );
+}
+```
 
-The alignment of the selected value(s) can be adjusted using the `align` prop.
+#### Alignment
 
-::::note
-Left / right alignment is preferred for styling.
-::::
+Align selected values with the `align` prop.
 
 ```tsx live
 function AlignmentExample() {
@@ -136,82 +235,322 @@ function AlignmentExample() {
     { value: 'banana', label: 'Banana' },
     { value: 'cherry', label: 'Cherry' },
     { value: 'date', label: 'Date' },
-    { value: 'elderberry', label: 'Elderberry' },
-    { value: 'fig', label: 'Fig' },
   ];
-  const { value: multiValue, onChange: multiOnChange } = useMultiSelect({
-    initialValue: ['apple', 'banana'],
-  });
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
 
   return (
-    <VStack gap={1}>
+    <VStack gap={2}>
       <Combobox
-        label="Default align - start"
-        onChange={multiOnChange}
+        align="start"
+        label="Align start"
+        onChange={onChange}
         options={fruitOptions}
-        placeholder="Empty value"
+        placeholder="Search..."
         type="multi"
-        value={multiValue}
+        value={value}
       />
       <Combobox
         align="end"
-        label="End align"
-        onChange={multiOnChange}
+        label="Align end"
+        onChange={onChange}
         options={fruitOptions}
-        placeholder="Empty value"
+        placeholder="Search..."
         type="multi"
-        value={multiValue}
+        value={value}
       />
     </VStack>
   );
 }
 ```
 
-### Borderless
+#### Borderless
 
-You can remove the border from the combobox control by setting `bordered` to `false`.
+Remove the border with `bordered={false}`.
 
-```jsx live
+```tsx live
 function BorderlessExample() {
-  const singleSelectOptions = [
-    { value: null, label: 'Remove selection' },
+  const fruitOptions = [
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' },
+    { value: 'cherry', label: 'Cherry' },
+  ];
+  const [value, setValue] = useState('apple');
+
+  return (
+    <Combobox
+      bordered={false}
+      label="Borderless"
+      onChange={setValue}
+      options={fruitOptions}
+      placeholder="Search..."
+      value={value}
+    />
+  );
+}
+```
+
+#### Compact
+
+Use smaller sizing with `compact`.
+
+```tsx live
+function CompactExample() {
+  const fruitOptions = [
+    { value: 'apple', label: 'Apple' },
+    { value: 'banana', label: 'Banana' },
+    { value: 'cherry', label: 'Cherry' },
+  ];
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
+
+  return (
+    <Combobox
+      compact
+      label="Compact"
+      onChange={onChange}
+      options={fruitOptions}
+      placeholder="Compact combobox..."
+      type="multi"
+      value={value}
+    />
+  );
+}
+```
+
+#### Helper Text
+
+Add guidance with `helperText`.
+
+```tsx live
+function HelperTextExample() {
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
+  const fruitOptions: SelectOption[] = [
     { value: 'apple', label: 'Apple' },
     { value: 'banana', label: 'Banana' },
     { value: 'cherry', label: 'Cherry' },
     { value: 'date', label: 'Date' },
   ];
 
+  return (
+    <Combobox
+      helperText="Choose more than one fruit"
+      label="Select fruits"
+      onChange={onChange}
+      options={fruitOptions}
+      placeholder="Search and select fruits..."
+      type="multi"
+      value={value}
+    />
+  );
+}
+```
+
+### Composed Examples
+
+#### Country Selection
+
+You can include flag emoji in labels to create a country selector.
+
+```tsx live
+function CountrySelectionExample() {
+  const getFlagEmoji = (cc) =>
+    cc
+      .toUpperCase()
+      .split('')
+      .map((c) => String.fromCodePoint(0x1f1e6 - 65 + c.charCodeAt(0)))
+      .join('');
+
+  const countryOptions = [
+    {
+      label: 'North America',
+      options: [
+        { value: 'us', label: `${getFlagEmoji('us')} United States` },
+        { value: 'ca', label: `${getFlagEmoji('ca')} Canada` },
+        { value: 'mx', label: `${getFlagEmoji('mx')} Mexico` },
+      ],
+    },
+    {
+      label: 'Europe',
+      options: [
+        { value: 'uk', label: `${getFlagEmoji('gb')} United Kingdom` },
+        { value: 'fr', label: `${getFlagEmoji('fr')} France` },
+        { value: 'de', label: `${getFlagEmoji('de')} Germany` },
+      ],
+    },
+    {
+      label: 'Asia',
+      options: [
+        { value: 'jp', label: `${getFlagEmoji('jp')} Japan` },
+        { value: 'cn', label: `${getFlagEmoji('cn')} China` },
+        { value: 'in', label: `${getFlagEmoji('in')} India` },
+      ],
+    },
+  ];
+
+  const { value, onChange } = useMultiSelect({ initialValue: [] });
+
+  return (
+    <Combobox
+      label="Country"
+      maxSelectedOptionsToShow={3}
+      onChange={onChange}
+      options={countryOptions}
+      placeholder="Select countries..."
+      type="multi"
+      value={value}
+    />
+  );
+}
+```
+
+#### Free Solo
+
+You can add a dynamic option to Combobox to enable free solo where users can provide their own value.
+
+```tsx live
+function FreeSoloExample() {
+  const CREATE_OPTION_PREFIX = '__create__';
+
+  const FreeSoloCombobox = useMemo(() => {
+    function StableFreeSoloCombobox({
+      freeSolo = false,
+      options: initialOptions,
+      value,
+      onChange,
+      placeholder = 'Search or type to add...',
+      ...comboboxProps
+    }) {
+      const [searchText, setSearchText] = useState('');
+      const [options, setOptions] = useState(initialOptions);
+
+      useEffect(() => {
+        if (!freeSolo) return;
+        const initialSet = new Set(initialOptions.map((option) => option.value));
+        const valueSet = new Set(Array.isArray(value) ? value : value != null ? [value] : []);
+        setOptions((prevOptions) => {
+          const addedStillSelected = prevOptions.filter(
+            (option) => !initialSet.has(option.value) && valueSet.has(option.value),
+          );
+          return [...initialOptions, ...addedStillSelected];
+        });
+      }, [freeSolo, initialOptions, value]);
+
+      const optionsWithCreate = useMemo(() => {
+        if (!freeSolo) return options;
+        const trimmedSearch = searchText.trim();
+        if (!trimmedSearch) return options;
+
+        const alreadyExists = options.some(
+          (option) =>
+            typeof option.label === 'string' &&
+            option.label.toLowerCase() === trimmedSearch.toLowerCase(),
+        );
+        if (alreadyExists) return options;
+
+        return [
+          ...options,
+          { value: `${CREATE_OPTION_PREFIX}${trimmedSearch}`, label: `Add "${trimmedSearch}"` },
+        ];
+      }, [freeSolo, options, searchText]);
+
+      const handleChange = useCallback(
+        (newValue) => {
+          if (!freeSolo) {
+            onChange(newValue);
+            return;
+          }
+
+          const values = Array.isArray(newValue) ? newValue : newValue ? [newValue] : [];
+          const createValue = values.find((optionValue) =>
+            String(optionValue).startsWith(CREATE_OPTION_PREFIX),
+          );
+
+          if (!createValue) {
+            onChange(newValue);
+            return;
+          }
+
+          const newLabel = String(createValue).slice(CREATE_OPTION_PREFIX.length);
+          const normalizedValue = newLabel.toLowerCase();
+          const newOption = { value: normalizedValue, label: newLabel };
+
+          setOptions((prevOptions) => [...prevOptions, newOption]);
+
+          const updatedValues = values
+            .filter((optionValue) => !String(optionValue).startsWith(CREATE_OPTION_PREFIX))
+            .concat(normalizedValue);
+
+          onChange(comboboxProps.type === 'multi' ? updatedValues : normalizedValue);
+          setSearchText('');
+        },
+        [comboboxProps.type, freeSolo, onChange],
+      );
+
+      return (
+        <Combobox
+          {...comboboxProps}
+          {...(freeSolo ? { searchText, onSearch: setSearchText } : {})}
+          onChange={handleChange}
+          options={freeSolo ? optionsWithCreate : initialOptions}
+          placeholder={placeholder}
+          value={value}
+        />
+      );
+    }
+
+    return StableFreeSoloCombobox;
+  }, [CREATE_OPTION_PREFIX]);
+
   const fruitOptions = [
     { value: 'apple', label: 'Apple' },
     { value: 'banana', label: 'Banana' },
     { value: 'cherry', label: 'Cherry' },
     { value: 'date', label: 'Date' },
     { value: 'elderberry', label: 'Elderberry' },
+    { value: 'fig', label: 'Fig' },
   ];
 
-  const [singleValue, setSingleValue] = useState('apple');
-  const { value: multiValue, onChange: multiOnChange } = useMultiSelect({
-    initialValue: ['apple'],
-  });
+  const [standardSingleValue, setStandardSingleValue] = useState(null);
+  const [freeSoloSingleValue, setFreeSoloSingleValue] = useState(null);
+  const standardMulti = useMultiSelect({ initialValue: [] });
+  const freeSoloMulti = useMultiSelect({ initialValue: [] });
 
   return (
     <VStack gap={4}>
-      <Combobox
-        bordered={false}
-        label="Borderless single select"
-        onChange={setSingleValue}
-        options={singleSelectOptions}
+      <FreeSoloCombobox
+        freeSolo={false}
+        label="Standard single"
+        onChange={setStandardSingleValue}
+        options={fruitOptions}
         placeholder="Search fruits..."
-        value={singleValue}
+        type="single"
+        value={standardSingleValue}
       />
-      <Combobox
-        bordered={false}
-        label="Borderless multi select"
-        onChange={multiOnChange}
+      <FreeSoloCombobox
+        freeSolo
+        label="FreeSolo single"
+        onChange={setFreeSoloSingleValue}
+        options={fruitOptions}
+        placeholder="Search or type to add..."
+        type="single"
+        value={freeSoloSingleValue}
+      />
+      <FreeSoloCombobox
+        freeSolo={false}
+        label="Standard multi"
+        onChange={standardMulti.onChange}
         options={fruitOptions}
         placeholder="Search fruits..."
         type="multi"
-        value={multiValue}
+        value={standardMulti.value}
+      />
+      <FreeSoloCombobox
+        freeSolo
+        label="FreeSolo multi"
+        onChange={freeSoloMulti.onChange}
+        options={fruitOptions}
+        placeholder="Search or type to add..."
+        type="multi"
+        value={freeSoloMulti.value}
       />
     </VStack>
   );