fix(docs): polish responsive controls and keep search indexing current

Author: waleedlatif1

.github/workflows/ci.yml

@@ -1150,6 +1150,8 @@ jobs:
           filters: |
             docs:
               - 'apps/docs/content/**'
+              - 'apps/docs/components/workflow-preview/examples.ts'
+              - 'apps/docs/components/workflow-preview/block-display-workflows.ts'
               - 'apps/docs/scripts/compile-content.ts'
               - 'apps/docs/scripts/index-search.ts'
               - 'apps/docs/lib/content/**'

apps/docs/EDITORIAL_GUIDE.md

@@ -63,7 +63,7 @@ A link replaces repeated detail only after the owner contains it. Keep a concise
 - On large integration references, keep action and trigger descriptions visible and fold their field tables into `ReferenceDetails`. Preserve headings inside each disclosure so direct links and browser search can reveal them. Setup requirements and consequential warnings stay outside the folded tables.
 - Integration logos belong beside the page title, using the generated `integration` frontmatter. Keep the regular docs header actions and do not repeat the logo in the article body.
 - Match inline code to Sim Chat: normal-weight monospace text, tight padding, and the existing borderless filled surface tokens. Scope the treatment to prose code; preserve fenced examples, API route bars, schema controls, and selector labels.
-- Use shared `ChipSelect` controls for API response and request-example pickers, with accessible names that include the current value, checked radio semantics for single choices, and menus aligned to their triggers. Keep docs pickers nonmodal so they do not hide lazily hydrating siblings. Keep response headings free of inherited extra margins. Scope dependency filter styling to `data-object-search-input`, including schema popovers portaled to the body; focus stays inside the field, and touch fields retain the shared target and text sizes.
+- Use the shared `TabsSelect` control for API response and request-example pickers, with accessible names that include the current value, checked radio semantics for single choices, and menus aligned to their triggers. Keep docs pickers nonmodal so they do not hide lazily hydrating siblings. Keep response headings free of inherited extra margins. Scope dependency filter styling to `data-object-search-input`, including schema popovers portaled to the body; focus stays inside the field, and touch fields retain the shared target and text sizes.
 - Import authored tabs from `@/components/ui/tabs`. Mixed panels retain a content inset; only a single code fence fills the frame. Keep long tab lists horizontally scrollable and long prose references wrapped. For bookmarked panels, use explicit native `TabsList`/`TabsTrigger` controls with `aria-controls` matching each panel ID; changing a panel ID alone leaves the generated control pointing at a nonexistent element.
 - Keep a screenshot when it locates a difficult control or shows a meaningful result. Keep a video when motion explains behavior that text or a static example cannot. Remove decorative, redundant, misleading, or non-rendering media.
 - Capture the current product with a small, neutral example. Use the shared `Image` component: `overview` for a workspace or full settings panel, `detail` for a complete dialog or focused control, and `result` for an output. Keep the branded background in both the page and media viewer. Overview and result images extend to the frame's bottom edge, with scenery above and beside the window. Crop empty canvas at the source; never cut off a control or result needed by the instructions. Keep complete dialogs inset so their actions remain visible.

apps/docs/components/docs/sample-panels.tsx

@@ -1,7 +1,6 @@
 'use client'
 
 import { type ReactNode, useId, useState } from 'react'
-import { ChevronDown } from '@sim/emcn/icons'
 import { cn } from '@/components/docs/classnames'
 import { CodeContent } from '@/components/ui/code-block'
 import { CopyButton } from '@/components/ui/copy-button'
@@ -51,7 +50,9 @@ export function SamplePanels({
       className={cn('my-0 overflow-hidden rounded-lg bg-[var(--docs-surface)]', className)}
     >
       <div className='flex min-h-11 items-center gap-2 px-3'>
-        <span className='shrink-0 font-medium text-docs-control'>{label}</span>
+        <span id={selectorId} className='shrink-0 font-medium text-docs-control'>
+          {label}
+        </span>
         {presentation === 'tabs' ? (
           <TabsList aria-label={`${label} language`}>
             {items.map((item) => (
@@ -61,21 +62,7 @@ export function SamplePanels({
             ))}
           </TabsList>
         ) : (
-          <div className='relative min-w-0'>
-            <TabsSelect
-              id={selectorId}
-              aria-label={`${label} status`}
-              aria-controls={current.id ?? `${selectorId}-${current.value}`}
-              className='h-7 pointer-coarse:min-h-11 w-full cursor-pointer appearance-none rounded-lg bg-transparent py-1 pr-6 pl-2 text-docs-control hover:bg-[var(--docs-hover)] focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2'
-            >
-              {items.map((item) => (
-                <option key={item.value} value={item.value}>
-                  {item.label}
-                </option>
-              ))}
-            </TabsSelect>
-            <ChevronDown className='-translate-y-1/2 pointer-events-none absolute top-1/2 right-1 size-4 text-[var(--docs-muted)]' />
-          </div>
+          <TabsSelect label={`${label} example`} items={items} />
         )}
         <div className='ml-auto shrink-0'>
           <CopyButton text={current.copyText} label={`Copy ${label.toLowerCase()}`} />

apps/docs/components/docs/search.tsx

@@ -104,10 +104,10 @@ export function DocsSearchTrigger({ compact = false }: DocsSearchTriggerProps) {
       aria-haspopup='dialog'
       onClick={(event) => show?.(event.currentTarget)}
       className={cn(
-        'flex items-center gap-1.5 rounded-lg text-[var(--docs-muted)] text-docs-nav transition-colors hover:bg-[var(--docs-hover)] focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2 active:bg-[var(--docs-pressed)]',
+        'flex items-center gap-1.5 rounded-lg text-[var(--docs-muted)] text-docs-nav focus-visible:outline-2 focus-visible:outline-[var(--docs-link)] focus-visible:outline-offset-2',
         compact
-          ? 'size-11 justify-center'
-          : 'h-[30px] w-full border border-[var(--docs-border)] bg-[var(--docs-reading)] px-[7px]'
+          ? 'before:-z-10 relative isolate size-11 justify-center before:absolute before:inset-1.5 before:rounded-lg before:transition-colors hover:before:bg-[var(--docs-hover)] active:before:bg-[var(--docs-pressed)] motion-reduce:before:transition-none'
+          : 'h-[30px] w-full border border-[var(--docs-border)] bg-[var(--docs-reading)] px-[7px] transition-colors hover:bg-[var(--docs-hover)] active:bg-[var(--docs-pressed)] motion-reduce:transition-none'
       )}
     >
       <Search className='size-4 shrink-0' aria-hidden />
@@ -193,6 +193,7 @@ function SearchContents({ close, navigation, sectionLabel }: SearchContentsProps
             setSelected(0)
           }}
           onKeyDown={(event) => {
+            if (event.nativeEvent.isComposing) return
             if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
               event.preventDefault()
               if (results.length)

apps/docs/components/docs/table-of-contents.tsx

@@ -56,7 +56,7 @@ export function TableOfContents({ headings, active, compact = false }: TableOfCo
       </nav>
     </details>
   ) : (
-    <nav aria-label='On this page' className='pl-2'>
+    <nav aria-label='On this page' className='px-2'>
       <h2 className='mb-4 font-medium text-[var(--docs-heading)] text-docs-control leading-5'>
         On this page
       </h2>

apps/docs/components/ui/tabs.tsx

@@ -13,8 +13,11 @@ import {
   useRef,
   useState,
 } from 'react'
+import * as Dropdown from '@radix-ui/react-dropdown-menu'
 import * as RadixTabs from '@radix-ui/react-tabs'
+import { Check, ChevronDown } from '@sim/emcn/icons'
 import { cn } from '@/components/docs/classnames'
+import { docsControlClass, docsMenuClass, docsMenuItemClass } from '@/components/docs/primitives'
 
 interface TabContextValue {
   baseId: string
@@ -195,20 +198,55 @@ export function Tabs({
 
 interface TabsListProps extends ComponentPropsWithoutRef<typeof RadixTabs.List> {}
 
-interface TabsSelectProps extends ComponentPropsWithoutRef<'select'> {}
+interface TabsSelectProps
+  extends Omit<ComponentPropsWithoutRef<typeof Dropdown.Trigger>, 'children'> {
+  items: { value: string; label: string }[]
+  label: string
+}
 
-export function TabsSelect({ onChange, ...props }: TabsSelectProps) {
+export function TabsSelect({ items, label, className, ...props }: TabsSelectProps) {
   const context = useContext(TabContext)
   if (!context) throw new Error('TabsSelect must be inside Tabs')
+  const selected = items.find((item) => item.value === context.value)
   return (
-    <select
-      {...props}
-      value={context.value}
-      onChange={(event) => {
-        context.select(event.target.value)
-        onChange?.(event)
-      }}
-    />
+    <Dropdown.Root modal={false}>
+      <Dropdown.Trigger
+        {...props}
+        aria-label={`${label}: ${selected?.label ?? ''}`}
+        className={cn(docsControlClass, 'min-w-0 max-w-full shrink px-2', className)}
+      >
+        <span className='truncate'>{selected?.label}</span>
+        <ChevronDown className='size-4 shrink-0 text-[var(--docs-muted)]' aria-hidden />
+      </Dropdown.Trigger>
+      <Dropdown.Portal>
+        <Dropdown.Content
+          align='start'
+          sideOffset={6}
+          collisionPadding={12}
+          className={cn(
+            'docs-root z-[100] max-h-[var(--radix-dropdown-menu-content-available-height)] min-w-[var(--radix-dropdown-menu-trigger-width)] max-w-[min(28rem,var(--radix-dropdown-menu-content-available-width))] overflow-y-auto overscroll-contain',
+            docsMenuClass
+          )}
+        >
+          <Dropdown.RadioGroup value={context.value} onValueChange={context.select}>
+            {items.map((item) => (
+              <Dropdown.RadioItem
+                key={item.value}
+                value={item.value}
+                className={cn(docsMenuItemClass, 'pointer-coarse:min-h-11')}
+              >
+                <span className='size-4 shrink-0'>
+                  <Dropdown.ItemIndicator>
+                    <Check className='size-4' aria-hidden />
+                  </Dropdown.ItemIndicator>
+                </span>
+                <span className='min-w-0 break-words'>{item.label}</span>
+              </Dropdown.RadioItem>
+            ))}
+          </Dropdown.RadioGroup>
+        </Dropdown.Content>
+      </Dropdown.Portal>
+    </Dropdown.Root>
   )
 }
 

apps/docs/scripts/test-navigation-e2e.ts

@@ -743,6 +743,66 @@ try {
     }
   }
 
+  for (const colorScheme of ['light', 'dark'] as const) {
+    for (const width of [320, 768, 1440]) {
+      const context = await browser.newContext({ viewport: { width, height: 900 }, colorScheme })
+      try {
+        await check(`API example menu: ${colorScheme} at ${width}px`, async () => {
+          const page = await context.newPage()
+          await open(page, '/api-reference/workflows/listWorkflows')
+          const trigger = page.getByRole('button', { name: /^Response example:/ })
+          await trigger.scrollIntoViewIfNeeded()
+          const selectedRegion = page.getByRole('region', { name: 'Response', exact: true })
+          const initialPanel = await selectedRegion.getAttribute('id')
+          await trigger.focus()
+          await page.keyboard.press('Enter')
+          const menu = page.getByRole('menu')
+          await expect(menu).toBeVisible()
+          await expect(menu).toHaveAttribute(
+            'aria-labelledby',
+            (await trigger.getAttribute('id')) ?? ''
+          )
+          await expect(trigger).toHaveAttribute(
+            'aria-controls',
+            (await menu.getAttribute('id')) ?? ''
+          )
+          await expect(page.getByRole('menuitemradio', { name: /^200/ })).toHaveAttribute(
+            'aria-checked',
+            'true'
+          )
+          const bounds = await menu.boundingBox()
+          if (!bounds) throw new Error('API example menu has no bounds')
+          expect(bounds.x).toBeGreaterThanOrEqual(0)
+          expect(bounds.x + bounds.width).toBeLessThanOrEqual(width)
+          expect(bounds.y + bounds.height).toBeLessThanOrEqual(900)
+          await page.getByRole('menuitemradio', { name: '400', exact: true }).focus()
+          await page.keyboard.press('Enter')
+          await expect(menu).toHaveCount(0)
+          await expect(trigger).toBeFocused()
+          await expect(trigger).toHaveAccessibleName('Response example: 400')
+          const selectedPanel = await selectedRegion.getAttribute('id')
+          if (!initialPanel || !selectedPanel) throw new Error('API examples have no panel IDs')
+          await expect(page.locator(`[id="${initialPanel}"]`)).toBeHidden()
+          await expect(page.locator(`[id="${selectedPanel}"]`)).toBeVisible()
+          await trigger.click()
+          await expect(
+            page.getByRole('menuitemradio', { name: '400', exact: true })
+          ).toHaveAttribute('aria-checked', 'true')
+          await page.screenshot({
+            path: join(directory, `api-example-menu-${colorScheme}-${width}.png`),
+          })
+          await page.keyboard.press('Escape')
+          await expect(trigger).toBeFocused()
+          expect(
+            await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth)
+          ).toBe(true)
+        })
+      } finally {
+        await context.close()
+      }
+    }
+  }
+
   const languageContext = await browser.newContext({ viewport: { width: 1440, height: 1000 } })
   try {
     await check('API language preference survives navigation and reload', async () => {
@@ -792,17 +852,14 @@ try {
         const page = await languageContext.newPage()
         try {
           await open(page, '/api-reference/workflows/executeWorkflowV2')
-          const language = page.getByRole('combobox', { name: 'Request status', exact: true })
-          const python = await language
-            .getByRole('option', { name: /^Python/ })
+          const language = page.getByRole('button', { name: /^Request example:/ })
+          await language.click()
+          await page
+            .getByRole('menuitemradio', { name: /^Python/ })
             .first()
-            .getAttribute('value')
-          if (!python) throw new Error('Execute workflow has no Python request example')
-          await language.selectOption(python)
-          await expect(language).toHaveValue(python)
-          const requestId = await language.getAttribute('aria-controls')
-          if (!requestId) throw new Error('Selected request has no sample panel')
-          const request = page.locator(`[id="${requestId}"] code`)
+            .click()
+          await expect(language).toHaveAccessibleName(/^Request example: Python/)
+          const request = page.getByRole('region', { name: 'Request', exact: true }).locator('code')
           const originalSample = await request.textContent()
           const formats = page.getByRole('tablist', {
             name: '200 response content type',
@@ -822,7 +879,7 @@ try {
             if (!panelId) throw new Error(`Response format ${format} has no panel`)
             const panel = page.locator(`[id="${panelId}"]`)
             await expect(panel).toBeVisible()
-            await expect(language).toHaveValue(python)
+            await expect(language).toHaveAccessibleName(/^Request example: Python/)
             await expect(request).toHaveText(originalSample ?? '')
             const stringTypeVisible = await panel
               .getByText('string', { exact: true })
@@ -989,6 +1046,14 @@ try {
             await expect(page.getByRole('button', { name: 'Menu', exact: true })).toBeFocused()
           }
           if (width >= 1280) {
+            const outlineContainer = page.getByRole('complementary').filter({
+              has: page.getByRole('navigation', { name: 'On this page', exact: true }),
+            })
+            expect(
+              await outlineContainer.evaluate(
+                (element) => element.scrollWidth <= element.clientWidth
+              )
+            ).toBe(true)
             const outline = await page
               .getByRole('navigation', { name: 'On this page', exact: true })
               .filter({ visible: true })
@@ -1175,6 +1240,12 @@ try {
         await search.fill('Slack')
         await expect(page.getByRole('option').first()).toBeVisible()
         await page.screenshot({ path: join(directory, 'search-results.png') })
+        const activeResult = await search.getAttribute('aria-activedescendant')
+        await search.dispatchEvent('keydown', { key: 'ArrowDown', isComposing: true })
+        await expect(search).toHaveAttribute('aria-activedescendant', activeResult ?? '')
+        await search.dispatchEvent('keydown', { key: 'Enter', isComposing: true })
+        await expect(page.getByRole('dialog')).toBeVisible()
+        await expect(page).toHaveURL(new URL('/introduction', target).href)
         await search.press('ArrowDown')
         await search.press('Enter')
         await expect(page).not.toHaveURL(new URL('/introduction', target).href)