@duro-app/ui 5.1.0 → 5.3.0

package/src/components/ButtonGroup/ButtonGroup.meta.ts

@@ -2,11 +2,12 @@ import type {ComponentMeta} from '../component-meta'
 
 export const meta: ComponentMeta = {
   description:
-    'Groups related buttons together with consistent spacing and layout. Supports horizontal and vertical orientation with alignment control.',
+    'Groups related buttons together with consistent spacing and layout. Supports horizontal and vertical orientation with alignment control. With `attached`, the group renders one joined control (shared borders, square inner corners) from any mix of Button, Toggle and Select/Menu/Popover triggers.',
   whenToUse: [
     'Dialog footers with Save/Cancel actions',
     'Toolbar-style groupings of related actions',
     'Form submission areas with multiple actions',
+    '`attached`: a segmented control of mixed controls — [Normal | Arial | 15px] as three Selects, [B | I | U | link] as Toggles and a Popover trigger',
   ],
   whenNotToUse: [
     'Single button — just use Button directly',
@@ -14,6 +15,18 @@ export const meta: ComponentMeta = {
     'Navigation items — use Inline or SideNav',
   ],
   relatedTo: [
+    {
+      component: 'Toolbar',
+      kind: 'composition',
+      relationship:
+        'Put attached groups in a Toolbar for one tab stop and arrow keys across them; a ButtonGroup alone leaves every control its own tab stop',
+    },
+    {
+      component: 'ToggleGroup',
+      kind: 'contrast',
+      relationship:
+        'ToggleGroup owns a selection (single or multiple) across Toggles; ButtonGroup attached only joins controls visually, each keeps its own state',
+    },
     {
       component: 'Inline',
       kind: 'contrast',

package/src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -1,8 +1,15 @@
+import {useState} from 'react'
 import type {Meta, StoryObj} from '@storybook/react'
-import {expect} from 'storybook/test'
+import {expect, userEvent, within} from 'storybook/test'
+import {BORDERS_PX, LAYERS, RADII_PX} from '@duro-app/tokens/keys'
 import {ButtonGroup} from './ButtonGroup'
 import {Button} from '../Button/Button'
+import {Popover} from '../Popover/Popover'
+import {Select} from '../Select/Select'
 import {Stack} from '../Stack/Stack'
+import {Text} from '../Text/Text'
+import {ThemeProvider, type ThemeName} from '../ThemeProvider/ThemeProvider'
+import {Toggle} from '../Toggle/Toggle'
 
 const meta: Meta<typeof ButtonGroup> = {
   title: 'Components/ButtonGroup',
@@ -102,3 +109,266 @@ export const WithGaps: Story = {
     await expect(groups.length).toBe(3)
   },
 }
+
+// --- Attached (5.3) ---
+
+const R = `${RADII_PX.sm}px`
+
+/** The four computed corner radii, clockwise from top-left. */
+function corners(el: Element) {
+  const cs = getComputedStyle(el)
+  return [
+    cs.borderTopLeftRadius,
+    cs.borderTopRightRadius,
+    cs.borderBottomRightRadius,
+    cs.borderBottomLeftRadius,
+  ]
+}
+
+const EXPECTED_CORNERS = {
+  first: [R, '0px', '0px', R],
+  middle: ['0px', '0px', '0px', '0px'],
+  last: ['0px', R, R, '0px'],
+}
+
+/** Each control's corners match its place: outer radii.sm, inner 0. */
+async function expectJoined(controls: Element[]) {
+  await expect(controls.length).toBeGreaterThan(1)
+  for (const [i, el] of controls.entries()) {
+    const place = i === 0 ? 'first' : i === controls.length - 1 ? 'last' : 'middle'
+    await expect(corners(el)).toEqual(EXPECTED_CORNERS[place])
+  }
+  // No gaps: each control's left border sits on its neighbour's right one.
+  for (let i = 1; i < controls.length; i++) {
+    const before = controls[i - 1].getBoundingClientRect()
+    const after = controls[i].getBoundingClientRect()
+    await expect(Math.round(before.right - after.left)).toBe(BORDERS_PX.hairline)
+  }
+}
+
+function TextStyleSelects({named = false}: {named?: boolean}) {
+  return (
+    <ButtonGroup attached aria-label="Text style">
+      <Select.Root name={named ? 'block' : undefined} defaultValue="normal">
+        <Select.Trigger aria-label="Block type">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="normal">Normal</Select.Item>
+          <Select.Item value="h1">Heading 1</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+      <Select.Root name={named ? 'font' : undefined} defaultValue="arial">
+        <Select.Trigger aria-label="Font">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="arial">Arial</Select.Item>
+          <Select.Item value="georgia">Georgia</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+      <Select.Root name={named ? 'size' : undefined} defaultValue="15">
+        <Select.Trigger aria-label="Font size">
+          <Select.Value />
+          <Select.Icon />
+        </Select.Trigger>
+        <Select.Popup>
+          <Select.Item value="13">13px</Select.Item>
+          <Select.Item value="15">15px</Select.Item>
+        </Select.Popup>
+      </Select.Root>
+    </ButtonGroup>
+  )
+}
+
+/** [Normal | Arial | 15px]: three Selects joined into one control. */
+export const AttachedSelects: Story = {
+  render: () => <TextStyleSelects />,
+  play: async ({canvas}) => {
+    await expectJoined(canvas.getAllByRole('combobox'))
+  },
+}
+
+/** Named Selects render a hidden input before each trigger; position comes
+ *  from DOM order, so the trigger buttons still join. */
+export const AttachedNamedSelects: Story = {
+  render: () => <TextStyleSelects named />,
+  play: async ({canvas, canvasElement}) => {
+    await expect(canvasElement.querySelectorAll('input[type="hidden"]').length).toBe(3)
+    await expectJoined(canvas.getAllByRole('combobox'))
+  },
+}
+
+const THEMES: ThemeName[] = ['dark', 'light', 'high-contrast']
+
+export const AttachedSelectsThemes: Story = {
+  render: () => (
+    <Stack gap="md">
+      {THEMES.map((theme) => (
+        <ThemeProvider key={theme} theme={theme}>
+          <Stack gap="xs">
+            <Text variant="label">{theme}</Text>
+            <TextStyleSelects />
+          </Stack>
+        </ThemeProvider>
+      ))}
+    </Stack>
+  ),
+  play: async ({canvas}) => {
+    const groups = canvas.getAllByRole('group', {name: 'Text style'})
+    await expect(groups.length).toBe(3)
+    for (const group of groups) await expectJoined(within(group).getAllByRole('combobox'))
+  },
+}
+
+/** Keyboard focus on the middle Select: it rises above both neighbours. */
+export const AttachedFocusMiddle: Story = {
+  render: () => <TextStyleSelects />,
+  play: async ({canvas}) => {
+    const [first, middle, last] = canvas.getAllByRole('combobox')
+    first.focus()
+    await userEvent.tab()
+    await expect(middle).toHaveFocus()
+    await expect(getComputedStyle(middle).zIndex).toBe(String(LAYERS.raised))
+    await expect(getComputedStyle(first).zIndex).toBe('auto')
+    await expect(getComputedStyle(last).zIndex).toBe('auto')
+    // The shared edges are drawn by the focused trigger, not its neighbours.
+    const r = middle.getBoundingClientRect()
+    const y = r.top + r.height / 2
+    await expect(middle.contains(document.elementFromPoint(r.left + 0.5, y))).toBe(true)
+    await expect(middle.contains(document.elementFromPoint(r.right - 0.5, y))).toBe(true)
+  },
+}
+
+function FormatGroup() {
+  const [pressed, setPressed] = useState<Record<string, boolean>>({u: true})
+  const toggle = (key: string) => (next: boolean) => setPressed((p) => ({...p, [key]: next}))
+  return (
+    <ButtonGroup attached aria-label="Format">
+      <Toggle aria-label="Bold" pressed={!!pressed.b} onPressedChange={toggle('b')}>
+        B
+      </Toggle>
+      <Toggle aria-label="Italic" pressed={!!pressed.i} onPressedChange={toggle('i')}>
+        I
+      </Toggle>
+      <Toggle aria-label="Underline" pressed={!!pressed.u} onPressedChange={toggle('u')}>
+        U
+      </Toggle>
+      <Toggle aria-label="Code" pressed={!!pressed.code} onPressedChange={toggle('code')}>
+        {'<>'}
+      </Toggle>
+      <Popover.Root>
+        <Popover.Trigger aria-label="Link">↗</Popover.Trigger>
+        <Popover.Popup label="Link">
+          <Stack gap="sm">
+            <Text>Paste a URL.</Text>
+            <Button size="small">Apply</Button>
+          </Stack>
+        </Popover.Popup>
+      </Popover.Root>
+      <Button variant="secondary" aria-label="Clear formatting">
+        T
+      </Button>
+      <Button variant="secondary" aria-label="Highlight">
+        H
+      </Button>
+    </ButtonGroup>
+  )
+}
+
+/** [B | I | U | <> | link | T | highlight]: four Toggles, a Popover trigger
+ *  and two icon Buttons, joined. */
+export const AttachedMixed: Story = {
+  render: () => <FormatGroup />,
+  play: async ({canvas}) => {
+    const group = canvas.getByRole('group', {name: 'Format'})
+    await expectJoined(within(group).getAllByRole('button'))
+  },
+}
+
+/** A pressed Toggle in an attached group keeps aria-pressed, its pressed
+ *  fill and its joined corners. */
+export const AttachedPressedToggle: Story = {
+  render: () => <FormatGroup />,
+  play: async ({canvas}) => {
+    const underline = canvas.getByRole('button', {name: 'Underline'})
+    await expect(underline).toHaveAttribute('aria-pressed', 'true')
+    await expect(corners(underline)).toEqual(EXPECTED_CORNERS.middle)
+    const bold = canvas.getByRole('button', {name: 'Bold'})
+    await expect(getComputedStyle(underline).backgroundColor).not.toBe(
+      getComputedStyle(bold).backgroundColor,
+    )
+  },
+}
+
+/** True when `el` is what is drawn at (x, y). */
+const drawnAt = (el: Element, x: number, y: number) => el.contains(document.elementFromPoint(x, y))
+
+/** The centre of the first whole pixel inside the border on each side: where
+ *  the inset accent ring is drawn, after pixel snapping. */
+function ringPixels(r: DOMRect) {
+  const h = BORDERS_PX.hairline
+  return {
+    left: Math.ceil(r.left + h) + 0.5,
+    right: Math.floor(r.right - h) - 0.5,
+    top: Math.ceil(r.top + h) + 0.5,
+    bottom: Math.floor(r.bottom - h) - 0.5,
+  }
+}
+
+/** U pressed between I and <>: its accent edge shows on all four sides. */
+export const PressedBetweenNeighbours: Story = {
+  render: () => <FormatGroup />,
+  play: async ({canvas}) => {
+    const underline = canvas.getByRole('button', {name: 'Underline'})
+    await expect(getComputedStyle(underline).boxShadow).toMatch(/inset/)
+    const r = underline.getBoundingClientRect()
+    const ring = ringPixels(r)
+    const cx = r.left + r.width / 2
+    const cy = r.top + r.height / 2
+    // Top and bottom: nothing overlaps, so a hit test inside the border lands on U.
+    await expect(drawnAt(underline, cx, ring.top)).toBe(true)
+    await expect(drawnAt(underline, cx, ring.bottom)).toBe(true)
+    await expect(drawnAt(underline, cx, cy)).toBe(true)
+    // Left and right: the neighbours' negative margins cover U's border and no
+    // more, so the inset ring (inside the border) stays clear on both sides.
+    // Measured, not hit-tested: a 1px band does not survive pixel snapping in
+    // a scaled test frame.
+    const h = BORDERS_PX.hairline
+    const left = canvas.getByRole('button', {name: 'Italic'}).getBoundingClientRect()
+    const right = canvas.getByRole('button', {name: 'Code'}).getBoundingClientRect()
+    await expect(left.right).toBeLessThanOrEqual(r.left + h + 0.01)
+    await expect(right.left).toBeGreaterThanOrEqual(r.right - h - 0.01)
+    await expect(getComputedStyle(underline).boxShadow).toContain(`${h}px inset`)
+  },
+}
+
+/** B and I both pressed, then I focused: both accent edges show, and I is
+ *  drawn over the shared border, so its focus ring is not covered. */
+export const BothPressedFocusSecond: Story = {
+  render: () => <FormatGroup />,
+  play: async ({canvas}) => {
+    const bold = canvas.getByRole('button', {name: 'Bold'})
+    const italic = canvas.getByRole('button', {name: 'Italic'})
+    await userEvent.click(bold)
+    await userEvent.click(italic)
+    await expect(bold).toHaveAttribute('aria-pressed', 'true')
+    await expect(italic).toHaveAttribute('aria-pressed', 'true')
+    bold.focus()
+    await userEvent.tab()
+    await expect(italic).toHaveFocus()
+    await expect(getComputedStyle(italic).zIndex).toBe(String(LAYERS.raised))
+    const b = bold.getBoundingClientRect()
+    const i = italic.getBoundingClientRect()
+    // Sampled down the shared edge: I is on top all along it.
+    for (const t of [0.25, 0.5, 0.75]) {
+      const y = i.top + i.height * t
+      await expect(drawnAt(italic, i.left + 0.5, y)).toBe(true)
+    }
+    for (const el of [bold, italic]) await expect(getComputedStyle(el).boxShadow).toMatch(/inset/)
+    await expect(drawnAt(bold, b.left + b.width / 2, ringPixels(b).top)).toBe(true)
+    await expect(drawnAt(bold, b.left + b.width / 2, ringPixels(b).bottom)).toBe(true)
+  },
+}

package/src/components/ButtonGroup/ButtonGroup.tsx

@@ -1,6 +1,8 @@
-import type {ReactNode} from 'react'
+import {type ReactNode, useCallback, useMemo} from 'react'
 import {html} from 'react-strict-dom'
 import type {SpacingToken} from '@duro-app/tokens/keys'
+import {useOrderedRegistry} from '../../shared/useOrderedRegistry'
+import {ButtonGroupContext, type ButtonGroupContextValue} from './ButtonGroupContext'
 import {styles} from './styles.css'
 
 export type ButtonGroupGap = Extract<SpacingToken, 'xs' | 'sm' | 'md'>
@@ -13,8 +15,15 @@ export interface ButtonGroupProps {
   align?: 'start' | 'end' | 'center'
   /** Disable all buttons in group */
   disabled?: boolean
-  /** Gap between buttons. Default: 'sm' */
+  /** Gap between buttons. Default: 'sm' (ignored when `attached`) */
   gap?: ButtonGroupGap
+  /**
+   * One joined control: no gap, shared borders, square inner corners. Holds
+   * Buttons, Toggles and the Select, Menu and Popover triggers, in any mix.
+   */
+  attached?: boolean
+  /** Names the group for assistive tech (a toolbar segment: "Text style"). */
+  'aria-label'?: string
 }
 
 const gapMap = {
@@ -41,22 +50,45 @@ export function ButtonGroup({
   align = 'start',
   disabled = false,
   gap = 'sm',
+  attached = false,
+  'aria-label': ariaLabel,
 }: ButtonGroupProps) {
   const isVertical = orientation === 'vertical'
   const alignStyle = isVertical ? verticalAlignMap[align] : horizontalAlignMap[align]
+  const {order, register} = useOrderedRegistry()
+
+  const positionOf = useCallback<ButtonGroupContextValue['positionOf']>(
+    (id) => {
+      const i = order.findIndex((entry) => entry.id === id)
+      if (i < 0) return 'middle'
+      if (order.length === 1) return 'only'
+      if (i === 0) return 'first'
+      return i === order.length - 1 ? 'last' : 'middle'
+    },
+    [order],
+  )
+  const ctx = useMemo<ButtonGroupContextValue>(
+    () => ({orientation, register, positionOf}),
+    [orientation, register, positionOf],
+  )
 
   return (
-    <html.div
-      role="group"
-      style={[
-        styles.base,
-        isVertical ? styles.vertical : styles.horizontal,
-        gapMap[gap],
-        alignStyle,
-        disabled && styles.disabled,
-      ]}
-    >
-      {children}
-    </html.div>
+    // A non-attached group still resets the context, so a plain group nested
+    // in an attached one lays out on its own.
+    <ButtonGroupContext.Provider value={attached ? ctx : null}>
+      <html.div
+        role="group"
+        aria-label={ariaLabel}
+        style={[
+          styles.base,
+          isVertical ? styles.vertical : styles.horizontal,
+          alignStyle,
+          attached ? (isVertical ? styles.attachedVertical : styles.attached) : gapMap[gap],
+          disabled && styles.disabled,
+        ]}
+      >
+        {children}
+      </html.div>
+    </ButtonGroupContext.Provider>
   )
 }

package/src/components/ButtonGroup/ButtonGroupContext.ts

@@ -0,0 +1,19 @@
+import {createContext, useContext} from 'react'
+import type {Orientation} from '../../shared/types'
+
+/** Where a control sits in an attached group. */
+export type GroupPosition = 'first' | 'middle' | 'last' | 'only'
+
+export interface ButtonGroupContextValue {
+  orientation: Orientation
+  register: (id: string, el: HTMLElement, disabled: boolean) => () => void
+  /** `middle` until the control has registered (server render, first paint). */
+  positionOf: (id: string) => GroupPosition
+}
+
+/** Provided by an `attached` ButtonGroup only; null everywhere else. */
+export const ButtonGroupContext = createContext<ButtonGroupContextValue | null>(null)
+
+export function useButtonGroup() {
+  return useContext(ButtonGroupContext)
+}

package/src/components/ButtonGroup/attached.css.ts

@@ -0,0 +1,44 @@
+import {css} from 'react-strict-dom'
+import {borders} from '@duro-app/tokens/tokens/borders.css'
+import {layers} from '@duro-app/tokens/tokens/layers.css'
+
+// The styles a control takes in an attached ButtonGroup, by its position.
+// Borders collapse into the neighbour's with a negative hairline margin; only
+// the outer corners keep the control's own radius.
+const overlap = `calc(-1 * ${borders.hairline})`
+
+export const attached = css.create({
+  // A focused control rises above its neighbours, so their borders never
+  // cover its focus ring. Position makes the z-index apply to a trigger that
+  // is not itself the flex item (Select and Menu triggers sit in a Root).
+  item: {
+    position: 'relative',
+    zIndex: {default: null, ':focus-visible': layers.raised},
+  },
+  horizontalFirst: {
+    borderTopRightRadius: 0,
+    borderBottomRightRadius: 0,
+  },
+  horizontalMiddle: {
+    borderRadius: 0,
+    marginLeft: overlap,
+  },
+  horizontalLast: {
+    borderTopLeftRadius: 0,
+    borderBottomLeftRadius: 0,
+    marginLeft: overlap,
+  },
+  verticalFirst: {
+    borderBottomLeftRadius: 0,
+    borderBottomRightRadius: 0,
+  },
+  verticalMiddle: {
+    borderRadius: 0,
+    marginTop: overlap,
+  },
+  verticalLast: {
+    borderTopLeftRadius: 0,
+    borderTopRightRadius: 0,
+    marginTop: overlap,
+  },
+})

package/src/components/ButtonGroup/styles.css.ts

@@ -21,6 +21,14 @@ export const styles = css.create({
   gapXs: {gap: spacing.xs},
   gapSm: {gap: spacing.sm},
   gapMd: {gap: spacing.md},
+  // One joined control: no gap, one row, every control as tall as the row.
+  attached: {
+    flexWrap: 'nowrap',
+    alignItems: 'stretch',
+  },
+  attachedVertical: {
+    alignItems: 'stretch',
+  },
   disabled: {
     opacity: 0.5,
     pointerEvents: 'none',

package/src/components/ButtonGroup/useGroupedControl.ts

@@ -0,0 +1,75 @@
+import {type RefObject, useId, useLayoutEffect, useRef} from 'react'
+import type {html} from 'react-strict-dom'
+import {isNative} from '../../platform'
+import {useToolbar} from '../Toolbar/ToolbarContext'
+import {useButtonGroup, type GroupPosition} from './ButtonGroupContext'
+import {attached} from './attached.css'
+
+const positionStyles = {
+  horizontal: {
+    first: attached.horizontalFirst,
+    middle: attached.horizontalMiddle,
+    last: attached.horizontalLast,
+    only: null,
+  },
+  vertical: {
+    first: attached.verticalFirst,
+    middle: attached.verticalMiddle,
+    last: attached.verticalLast,
+    only: null,
+  },
+} as const
+
+type ButtonStyle = Parameters<typeof html.button>[0]['style']
+
+export interface GroupedControl<T extends HTMLElement> {
+  ref: RefObject<T | null>
+  /** In an attached ButtonGroup. */
+  attached: boolean
+  position: GroupPosition | null
+  /** The joined style for its position; spread after the control's own. */
+  style: ButtonStyle | null
+  /** The Toolbar's roving tabindex, when in one. */
+  tabIndex: 0 | -1 | undefined
+  onFocus: (() => void) | undefined
+}
+
+/**
+ * What a control (Button, Toggle, the Select, Menu and Popover triggers) takes
+ * from an attached ButtonGroup and a Toolbar around it: its joined style by
+ * position, and its roving tabindex. Outside both, every field is inert.
+ */
+export function useGroupedControl<T extends HTMLElement>({
+  disabled = false,
+}: {disabled?: boolean} = {}): GroupedControl<T> {
+  const id = useId()
+  const ref = useRef<T | null>(null)
+  const group = useButtonGroup()
+  const toolbar = useToolbar()
+
+  const groupRegister = group?.register
+  const toolbarRegister = toolbar?.register
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (isNative || !el) return
+    const unregisterGroup = groupRegister?.(id, el, disabled)
+    const unregisterToolbar = toolbarRegister?.(id, el, disabled)
+    return () => {
+      unregisterGroup?.()
+      unregisterToolbar?.()
+    }
+  }, [id, disabled, groupRegister, toolbarRegister])
+
+  const position: GroupPosition | null = group ? group.positionOf(id) : null
+  const style: ButtonStyle | null =
+    group && position ? [attached.item, positionStyles[group.orientation][position]] : null
+
+  return {
+    ref,
+    attached: group !== null,
+    position,
+    style,
+    tabIndex: toolbar?.tabIndexOf(id),
+    onFocus: toolbar ? () => toolbar.onItemFocus(id) : undefined,
+  }
+}