fix(ui,sdk)!: give NavButton real state axes and tighten the trigger contracts

Author: librowski

apps/docs/src/components/ui-examples/nav-button.tsx

@@ -14,9 +14,7 @@ export function NavButtonExample() {
           <NavButton variant="round" prefixIcon={<House />}>
             Round
           </NavButton>
-          <NavButton variant="plain" prefixIcon={<House />}>
-            Plain
-          </NavButton>
+          <NavButton aria-label="Plain" variant="plain" prefixIcon={<House />} />
           <NavButton isSelected prefixIcon={<House />} suffixIcon={<ArrowRight />}>
             Selected
           </NavButton>

apps/docs/src/content/docs/ui-library/ui-components/menu-trigger-button.mdx

@@ -7,7 +7,7 @@ import CssVariablesTable from '../../../../components/api/css-variables-table.as
 import PropsTable from '../../../../components/api/props-table.astro';
 import { MenuTriggerButtonExample } from '../../../../components/ui-examples/menu-trigger-button';
 
-`MenuTriggerButton` is a fixed-size NavButton composition for menu trigger icons.
+`MenuTriggerButton` is an icon-only NavButton composition for menu triggers.
 Set `isOpen` from the menu state to render the persistent Pressed state.
 
 <MenuTriggerButtonExample client:visible />
@@ -39,6 +39,6 @@ function Example() {
 ## CSS variables
 
 It renders a `NavButton`, so its appearance is customized through the
-[NavButton variables](/docs/ui-library/ui-components/nav-button/#css-variables).
+[NavButton variables](/ui-library/ui-components/nav-button/#css-variables).
 
 <CssVariablesTable slug="menu-trigger-button" />

apps/docs/src/content/docs/ui-library/ui-components/nav-button.mdx

@@ -8,9 +8,9 @@ import PropsTable from '../../../../components/api/props-table.astro';
 import { NavButtonExample } from '../../../../components/ui-examples/nav-button';
 
 `NavButton` renders its label from `children` and accepts optional `prefixIcon`
-and `suffixIcon` props. Leave `children` empty and provide `prefixIcon` for a
-square icon-only button, and use `variant` to select square, round, or
-no-background styling.
+and `suffixIcon` props. Omit `children` and provide `prefixIcon` for an icon-only
+button. Use `variant` to select square or round styling; icon-only buttons also
+support the no-background `plain` variant.
 
 The `isSelected` prop renders the persistent Pressed state, including while the
 button is hovered. The mouse-down `:active` state uses a separate Active token.

packages/sdk/src/features/app-bar/components/controls/controls.tsx

@@ -1,6 +1,6 @@
 import { DotsThreeVertical } from '@phosphor-icons/react';
-import { Menu, type MenuItemProps, NavButton } from '@workflowbuilder/ui';
-import { useMemo } from 'react';
+import { Menu, type MenuItemProps, MenuTriggerButton } from '@workflowbuilder/ui';
+import { useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
 import styles from '../../app-bar.module.css';
@@ -12,6 +12,7 @@ import { ToggleReadyOnlyMode } from '../toggle-read-only-mode/toggle-read-only-m
 
 export function Controls() {
   const { t } = useTranslation();
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
 
   // eslint-disable-next-line react-hooks/exhaustive-deps
   const items: MenuItemProps[] = useMemo(() => getControlsDotsItems(), [t]);
@@ -24,12 +25,10 @@ export function Controls() {
       </OptionalAppBarControls>
       {items.length > 0 && (
         <div className={styles['menu-container']}>
-          <Menu items={items}>
-            <NavButton
-              aria-label={t('tooltips.menu')}
-              tooltip={t('tooltips.menu')}
-              prefixIcon={<DotsThreeVertical />}
-            />
+          <Menu items={items} open={isMenuOpen} onOpenChange={setIsMenuOpen}>
+            <MenuTriggerButton aria-label={t('tooltips.menu')} isOpen={isMenuOpen} tooltip={t('tooltips.menu')}>
+              <DotsThreeVertical />
+            </MenuTriggerButton>
           </Menu>
         </div>
       )}

packages/sdk/src/features/app-bar/components/project-selection/project-selection.spec.tsx

@@ -3,7 +3,7 @@ import type { MenuItemProps } from '@workflowbuilder/ui';
 import { describe, expect, it, vi } from 'vitest';
 
 // Render the menu's `items` inline so we can assert on them without driving the
-// real menu popover. The component also imports Input/NavButton, so the
+// real menu popover. The component also imports Input/MenuTriggerButton, so the
 // mock must expose them too.
 vi.mock('@workflowbuilder/ui', () => ({
   Menu: ({ items }: { items: MenuItemProps[] }) => (
@@ -15,7 +15,7 @@ vi.mock('@workflowbuilder/ui', () => ({
       ))}
     </ul>
   ),
-  NavButton: () => null,
+  MenuTriggerButton: () => null,
   Input: () => null,
 }));
 

packages/sdk/src/features/app-bar/components/project-selection/project-selection.tsx

@@ -1,5 +1,5 @@
 import { CaretDown } from '@phosphor-icons/react';
-import { Input, Menu, NavButton } from '@workflowbuilder/ui';
+import { Input, Menu, MenuTriggerButton } from '@workflowbuilder/ui';
 import { useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
@@ -39,6 +39,7 @@ function ProjectSelectionComponent({ onDuplicateClick }: ProjectSelectionProps)
   const isReadOnlyMode = useStore((store) => store.isReadOnlyMode);
   const setDocumentName = useStore((state) => state.setDocumentName);
   const [editName, setEditName] = useState<boolean>(false);
+  const [isMenuOpen, setIsMenuOpen] = useState(false);
 
   const { t } = useTranslation();
 
@@ -88,12 +89,14 @@ function ProjectSelectionComponent({ onDuplicateClick }: ProjectSelectionProps)
         </span>
       )}
       <div className={styles['menu-container']}>
-        <Menu items={items}>
-          <NavButton
+        <Menu items={items} open={isMenuOpen} onOpenChange={setIsMenuOpen}>
+          <MenuTriggerButton
             aria-label={t('tooltips.pickTheProject')}
+            isOpen={isMenuOpen}
             tooltip={t('tooltips.pickTheProject')}
-            prefixIcon={<CaretDown />}
-          />
+          >
+            <CaretDown />
+          </MenuTriggerButton>
         </Menu>
       </div>
     </div>

packages/sdk/src/features/i18n/components/language-selector/language-selector.spec.tsx

@@ -8,7 +8,11 @@ const i18nState = { language: 'en', resolvedLanguage: 'en', changeLanguage: vi.f
 // Render the Menu's trigger (children) so the displayed language code is queryable.
 vi.mock('@workflowbuilder/ui', () => ({
   Menu: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
-  NavButton: ({ children }: { children?: ReactNode }) => <button type="button">{children}</button>,
+  NavButton: ({ 'aria-label': ariaLabel, children }: { 'aria-label'?: string; children?: ReactNode }) => (
+    <button type="button" aria-label={ariaLabel}>
+      {children}
+    </button>
+  ),
 }));
 
 vi.mock('@workflow-builder/icons', () => ({
@@ -29,6 +33,7 @@ describe('LanguageSelector — label reflects the resolved language', () => {
     render(<LanguageSelector />);
 
     expect(screen.getByText('PL')).toBeTruthy();
+    expect(screen.getByRole('button', { name: 'PL - tooltips.changeLanguage' })).toBeTruthy();
     expect(screen.queryByText('EN')).toBeNull();
   });
 

packages/sdk/src/features/i18n/components/language-selector/language-selector.tsx

@@ -20,6 +20,7 @@ export function LanguageSelector() {
 
   const resolvedCode = i18n.resolvedLanguage ?? i18n.language?.split('-')[0];
   const currentLanguage = languages.find((lang) => lang.code === resolvedCode) || languages[0];
+  const visibleCode = currentLanguage.code.toUpperCase();
 
   const languageItems: MenuItemProps[] = useMemo(
     () =>
@@ -35,11 +36,11 @@ export function LanguageSelector() {
     <>
       <Menu items={languageItems} size="small">
         <NavButton
-          aria-label={t('tooltips.changeLanguage')}
+          aria-label={`${visibleCode} - ${t('tooltips.changeLanguage')}`}
           suffixIcon={<CaretDown />}
           tooltip={t('tooltips.changeLanguage')}
         >
-          {currentLanguage.code.toUpperCase()}
+          {visibleCode}
         </NavButton>
       </Menu>
     </>

packages/sdk/src/features/variables/components/variable-text/variable-text.tsx

@@ -105,6 +105,7 @@ function SuggestionsContainer({
   renderGroupHeader: (group: VariableSuggestionGroup) => ReactNode;
   children: ReactElement;
 }) {
+  const { t } = useTranslation();
   const ul = children as ReactElement<{ children?: ReactElement[]; className?: string }>;
   const items = ul.props.children;
 
@@ -149,7 +150,7 @@ function SuggestionsContainer({
       <div className={styles['suggestionsHeader']}>
         <span className={styles['suggestionsTitle']}>{title}</span>
         <NavButton
-          aria-label="Close"
+          aria-label={t('common.close')}
           onMouseDown={(event: React.MouseEvent) => {
             event.stopPropagation();
             handleClose();

packages/ui/src/components/button/menu-trigger-button/menu-trigger-button.tsx

@@ -1,12 +1,17 @@
 import { forwardRef } from 'react';
-import type { ButtonHTMLAttributes, ReactNode } from 'react';
 
 import { NavButton } from '../nav-button/nav-button';
+import type { NavButtonSize, NavButtonVariant } from '../nav-button/types';
+import type { BaseButtonProps, IconNode } from '../types';
 
-export type MenuTriggerButtonProps = {
-  children: ReactNode;
+export type MenuTriggerButtonProps = BaseButtonProps & {
+  children: IconNode;
   isOpen?: boolean;
-} & ButtonHTMLAttributes<HTMLButtonElement>;
+  /** @default 'm' */
+  size?: NavButtonSize;
+  /** @default 'square' */
+  variant?: NavButtonVariant;
+};
 
 export const MenuTriggerButton = forwardRef<HTMLButtonElement, MenuTriggerButtonProps>(
   ({ children, isOpen = false, ...props }, ref) => (