feat(mosaic): add ActionBar component

.changeset/mosaic-action-bar.md

@@ -0,0 +1,5 @@
+---
+'@clerk/mosaic': patch
+---
+
+Add an ActionBar component for contextual actions on a current selection.

packages/mosaic/src/components/action-bar/action-bar.styles.ts

@@ -0,0 +1,82 @@
+import * as stylex from '@stylexjs/stylex';
+
+import {
+  colorVars,
+  durationVars,
+  easingVars,
+  fontWeightVars,
+  radiusVars,
+  shadowVars,
+  space,
+  typeScaleVars,
+} from '../../tokens.stylex';
+
+const reduceMotion = '@media (prefers-reduced-motion: reduce)';
+
+export const styles = stylex.create({
+  positioner: {
+    display: 'flex',
+    justifyContent: 'center',
+    pointerEvents: 'none',
+    zIndex: 1,
+    bottom: space['2'],
+  },
+  // Anchored to the nearest positioned ancestor — for a bounded container.
+  positionerAbsolute: {
+    insetInline: 0,
+    position: 'absolute',
+  },
+  // Pinned to the foot of the nearest scroll container, so it stays in view while its surface
+  // scrolls. `margin-block-start: auto` drops it to the bottom when the column has room to spare.
+  positionerSticky: {
+    marginBlockStart: 'auto',
+    position: 'sticky',
+  },
+  bar: {
+    borderRadius: radiusVars['--cl-radius-lg'],
+    gap: space['1'],
+    paddingBlock: space['1'],
+    paddingInline: space['1'],
+    alignItems: 'center',
+    backgroundColor: colorVars['--cl-color-background'],
+    boxShadow: shadowVars['--cl-shadow-lg'],
+    display: 'flex',
+    opacity: {
+      default: 1,
+      ':is([data-open="false"])': 0,
+    },
+    pointerEvents: {
+      default: 'auto',
+      ':is([data-open="false"])': 'none',
+    },
+    transform: {
+      default: 'translateY(0)',
+      ':is([data-open="false"])': 'translateY(0.25rem)',
+    },
+    transitionDuration: {
+      default: `${durationVars['--cl-duration-base']}, ${durationVars['--cl-duration-base']}`,
+      [reduceMotion]: `${durationVars['--cl-duration-instant']}, ${durationVars['--cl-duration-instant']}`,
+      ':is([data-open="false"])': `${durationVars['--cl-duration-instant']}, ${durationVars['--cl-duration-instant']}`,
+    },
+    transitionProperty: 'opacity, transform',
+    transitionTimingFunction: {
+      default: `linear, ${easingVars['--cl-ease-enter']}`,
+    },
+    maxWidth: 'calc(100% - 2 * var(--cl-spacing))',
+  },
+  count: {
+    paddingInline: space['2'],
+    color: colorVars['--cl-color-foreground'],
+    fontSize: typeScaleVars['--cl-text-sm-size'],
+    fontWeight: fontWeightVars['--cl-font-medium'],
+    lineHeight: typeScaleVars['--cl-text-sm-leading'],
+    whiteSpace: 'nowrap',
+  },
+  separator: {
+    marginBlock: space['1'],
+    marginInline: space['0.5'],
+    alignSelf: 'stretch',
+    backgroundColor: colorVars['--cl-color-border'],
+    width: '1px',
+  },
+});

packages/mosaic/src/components/action-bar/action-bar.test.tsx

@@ -0,0 +1,73 @@
+import * as stylex from '@stylexjs/stylex';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ActionBar } from './action-bar';
+
+const testStyles = stylex.create({
+  positioner: {
+    bottom: '20px',
+  },
+});
+
+describe('Mosaic ActionBar', () => {
+  it('renders a toolbar with its count and reflects data-open', () => {
+    render(
+      <ActionBar.Root
+        open
+        aria-label='Bulk actions'
+      >
+        <ActionBar.Count>3 selected</ActionBar.Count>
+      </ActionBar.Root>,
+    );
+    const bar = screen.getByRole('toolbar', { name: 'Bulk actions' });
+    expect(bar).toHaveClass('cl-action-bar');
+    expect(bar).toHaveAttribute('data-open', 'true');
+    const count = screen.getByText('3 selected');
+    expect(count).toHaveClass('cl-action-bar-count');
+    expect(count.querySelector('.cl-icon')).not.toBeInTheDocument();
+  });
+
+  it('marks the bar inert while closed', () => {
+    render(
+      <ActionBar.Root
+        open={false}
+        aria-label='Bulk actions'
+      >
+        <ActionBar.Count>0 selected</ActionBar.Count>
+      </ActionBar.Root>,
+    );
+    const bar = screen.getByRole('toolbar', { name: 'Bulk actions', hidden: true });
+    expect(bar).toHaveAttribute('data-open', 'false');
+    expect(bar.inert).toBe(true);
+  });
+
+  it('styles the positioner independently from the bar', () => {
+    render(
+      <ActionBar.Root
+        open
+        aria-label='Bulk actions'
+        positionerXstyle={testStyles.positioner}
+      />,
+    );
+    expect(screen.getByRole('toolbar', { name: 'Bulk actions' }).parentElement).toHaveClass(
+      ...(stylex.props(testStyles.positioner).className as string).split(' '),
+    );
+  });
+
+  it('dismisses with a labelled button', async () => {
+    const onDismiss = vi.fn();
+    render(
+      <ActionBar.Root
+        open
+        aria-label='Bulk actions'
+      >
+        <ActionBar.Dismiss onClick={onDismiss} />
+      </ActionBar.Root>,
+    );
+    await userEvent.click(screen.getByRole('button', { name: 'Clear selection' }));
+    expect(onDismiss).toHaveBeenCalledOnce();
+  });
+});

packages/mosaic/src/components/action-bar/action-bar.tsx

@@ -0,0 +1,148 @@
+import * as stylex from '@stylexjs/stylex';
+import React from 'react';
+
+import { useRender } from '../../primitives/utils';
+import type { MosaicComponentProps, MosaicElementProps, XStyle } from '../../props';
+import { mergeStyleProps, themeProps } from '../../props';
+import { reset } from '../../utils/reset.styles';
+import { Button } from '../button';
+import { Icon } from '../icon';
+import { styles } from './action-bar.styles';
+
+export interface ActionBarRootProps extends MosaicComponentProps<'div'> {
+  /** Whether the bar is shown. Toggling it animates the bar in and out. */
+  open: boolean;
+  /**
+   * Pins the bar to the foot of the nearest scroll container instead of a positioned ancestor, so
+   * it stays in view while a long surface scrolls (a `Profile` page, a modal). Place `ActionBar.Root`
+   * as the last child of that scrolling column. Off, the bar is absolute within the nearest
+   * positioned ancestor — give that ancestor `position: relative`.
+   *
+   * @default false
+   */
+  sticky?: boolean;
+  positionerXstyle?: XStyle;
+}
+
+/**
+ * A floating bar of actions for a selection. It sits at the foot of its container — the nearest
+ * positioned ancestor, or the nearest scroll container with `sticky` — and animates in and out with
+ * `open`. While `open` is false it is inert and click-through, so the surface underneath stays
+ * usable. Compose a count, a separator, the actions, and a dismiss:
+ *
+ * @example
+ * <ActionBar.Root open={count > 0}>
+ *   <ActionBar.Count>{count} selected</ActionBar.Count>
+ *   <ActionBar.Separator />
+ *   <Menu.Root>…</Menu.Root>
+ *   <Button color='negative' variant='ghost' shape='square' aria-label='Remove'>
+ *     <Icon name='trash' />
+ *   </Button>
+ *   <ActionBar.Separator />
+ *   <ActionBar.Dismiss onClick={clearSelection} />
+ * </ActionBar.Root>
+ */
+const Root = React.forwardRef<HTMLDivElement, ActionBarRootProps>(function ActionBarRoot(
+  { open, sticky = false, render, xstyle, positionerXstyle, children, ...rest },
+  ref,
+) {
+  const barRef = React.useRef<HTMLDivElement>(null);
+  React.useEffect(() => {
+    if (barRef.current) {
+      barRef.current.inert = !open;
+    }
+  }, [open]);
+
+  const bar = useRender({
+    defaultTagName: 'div',
+    render,
+    ref: barRef,
+    props: {
+      ...mergeStyleProps(themeProps('action-bar', { open }), stylex.props(reset.base, styles.bar, xstyle), rest),
+      'data-open': open,
+      role: 'toolbar',
+      children,
+    },
+  });
+
+  return (
+    <div
+      ref={ref}
+      {...mergeStyleProps(
+        themeProps('action-bar-positioner', { sticky }),
+        stylex.props(
+          reset.base,
+          styles.positioner,
+          sticky ? styles.positionerSticky : styles.positionerAbsolute,
+          positionerXstyle,
+        ),
+      )}
+    >
+      {bar}
+    </div>
+  );
+});
+
+export type ActionBarCountProps = MosaicComponentProps<'div'>;
+
+/** The leading count of what is selected, e.g. `3 selected`. */
+const Count = React.forwardRef<HTMLDivElement, ActionBarCountProps>(function ActionBarCount(
+  { render, xstyle, children, ...rest },
+  ref,
+) {
+  return useRender({
+    defaultTagName: 'div',
+    render,
+    ref,
+    props: {
+      ...mergeStyleProps(themeProps('action-bar-count'), stylex.props(reset.base, styles.count, xstyle), rest),
+      children,
+    },
+  });
+});
+
+export type ActionBarSeparatorProps = MosaicComponentProps<'div'>;
+
+/** A vertical divider between groups of the bar. */
+const Separator = React.forwardRef<HTMLDivElement, ActionBarSeparatorProps>(function ActionBarSeparator(
+  { render, xstyle, ...rest },
+  ref,
+) {
+  return useRender({
+    defaultTagName: 'div',
+    render,
+    ref,
+    props: {
+      ...mergeStyleProps(themeProps('action-bar-separator'), stylex.props(reset.base, styles.separator), rest),
+      'aria-hidden': true,
+    },
+  });
+});
+
+export type ActionBarDismissProps = MosaicElementProps<'button'>;
+
+/** Dismisses the bar. A ghost icon button; defaults its label to "Clear selection". */
+const Dismiss = React.forwardRef<HTMLButtonElement, ActionBarDismissProps>(function ActionBarDismiss(
+  { xstyle, 'aria-label': ariaLabel, ...rest },
+  ref,
+) {
+  return (
+    <Button
+      ref={ref}
+      variant='ghost'
+      shape='square'
+      size='md'
+      aria-label={ariaLabel ?? 'Clear selection'}
+      {...mergeStyleProps(themeProps('action-bar-dismiss'), stylex.props(xstyle), rest)}
+    >
+      <Icon name='x' />
+    </Button>
+  );
+});
+
+/**
+ * A floating bar of actions for a current selection, composed through `ActionBar.Root`,
+ * `ActionBar.Count`, `ActionBar.Separator`, and `ActionBar.Dismiss`. The actions themselves
+ * (a `Menu`, a `Button`) are whatever children you place between them.
+ */
+export const ActionBar = { Root, Count, Separator, Dismiss };

packages/mosaic/src/components/action-bar/index.ts

@@ -0,0 +1,7 @@
+export { ActionBar } from './action-bar';
+export type {
+  ActionBarCountProps,
+  ActionBarDismissProps,
+  ActionBarRootProps,
+  ActionBarSeparatorProps,
+} from './action-bar';

packages/swingset/src/components/DocsViewer.tsx

@@ -47,6 +47,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     destructive: dynamic(() => import('../stories/destructive.mdx')),
   },
   components: {
+    'action-bar': dynamic(() => import('../stories/action-bar.mdx')),
     avatar: dynamic(() => import('../stories/avatar.mdx')),
     badge: dynamic(() => import('../stories/badge.mdx')),
     banner: dynamic(() => import('../stories/banner.mdx')),

packages/swingset/src/lib/registry.ts

@@ -1,5 +1,6 @@
 // Import stories explicitly to control order and avoid type casting through unknown.
 import { meta as accordionMeta } from '../stories/accordion.stories';
+import { Default as ActionBarDefault, meta as actionBarMeta } from '../stories/action-bar.stories';
 import { meta as autocompleteMeta } from '../stories/autocomplete.stories';
 import {
   Fallback as AvatarFallbackStory,
@@ -397,6 +398,11 @@ const comboboxModule: StoryModule = {
   Scrolling: ComboboxScrolling,
 };
 
+const actionBarModule: StoryModule = {
+  meta: actionBarMeta,
+  Default: ActionBarDefault,
+};
+
 const avatarModule: StoryModule = {
   meta: avatarMeta,
   Primary: AvatarPrimary,
@@ -791,6 +797,7 @@ export const registry: StoryModule[] = [
   confirmationModule,
   destructiveModule,
   // Components
+  actionBarModule,
   avatarModule,
   badgeModule,
   bannerModule,