feat(ui): add Mosaic Item component

.changeset/mosaic-item.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -31,6 +31,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     button: dynamic(() => import('../stories/button.mdx')),
     card: dynamic(() => import('../stories/card.component.mdx')),
     input: dynamic(() => import('../stories/input.mdx')),
+    item: dynamic(() => import('../stories/item.mdx')),
     dialog: dynamic(() => import('../stories/dialog.component.mdx')),
     heading: dynamic(() => import('../stories/heading.mdx')),
     icon: dynamic(() => import('../stories/icon.mdx')),

packages/swingset/src/lib/registry.ts

@@ -33,6 +33,12 @@ import {
   meta as inputMeta,
   Sizes as InputSizes,
 } from '../stories/input.stories';
+import {
+  Default as ItemDefault,
+  Group as ItemGroup,
+  Interactive as ItemInteractive,
+  meta as itemMeta,
+} from '../stories/item.stories';
 import { meta as menuMeta } from '../stories/menu.stories';
 import {
   Default as OrganizationProfileDefault,
@@ -121,6 +127,13 @@ const inputModule: StoryModule = { meta: inputMeta, Default, Sizes: InputSizes,
 
 const dialogComponentModule: StoryModule = { meta: dialogComponentMeta, Default: DialogDefault };
 
+const itemModule: StoryModule = {
+  meta: itemMeta,
+  Default: ItemDefault,
+  Interactive: ItemInteractive,
+  Group: ItemGroup,
+};
+
 const headingModule: StoryModule = {
   meta: headingMeta,
   Default: HeadingDefault,
@@ -174,6 +187,7 @@ export const registry: StoryModule[] = [
   buttonModule,
   cardComponentModule,
   inputModule,
+  itemModule,
   dialogComponentModule,
   headingModule,
   iconModule,

packages/swingset/src/stories/item.mdx

@@ -0,0 +1,79 @@
+import * as ItemStories from './item.stories';
+
+# Item
+
+Item is a flexible row for lists of accounts, organizations, and settings in Mosaic. It's composed from parts via dot syntax (`Item.Media`, `Item.Content`, `Item.Title`, …) and renders as a `<div>` by default. Pass a `render` prop to make a row an interactive link or button, which adds hover and cursor affordances.
+
+## Example
+
+<Story
+  name='Default'
+  storyModule={ItemStories}
+/>
+
+### Interactive
+
+<Story
+  name='Interactive'
+  storyModule={ItemStories}
+/>
+
+### Group
+
+<Story
+  name='Group'
+  storyModule={ItemStories}
+/>
+
+## Usage
+
+```tsx
+import { Item } from '@clerk/ui/mosaic/components/item';
+
+<Item.Group>
+  <Item render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
+    <Item.Media>
+      <img src={org.imageUrl} alt='' width={36} height={36} />
+    </Item.Media>
+    <Item.Content>
+      <Item.Title>Test Organization</Item.Title>
+      <Item.Description>Member</Item.Description>
+    </Item.Content>
+    <Item.Actions>
+      <Button variant='outline'>Manage</Button>
+    </Item.Actions>
+  </Item>
+</Item.Group>;
+```
+
+## Parts
+
+| Part               | Class                 | Description                                                          |
+| ------------------ | --------------------- | -------------------------------------------------------------------- |
+| `Item`             | `cl-item`             | Root row. Renders a `<div>`, or a custom element via `render`.       |
+| `Item.Media`       | `cl-item-media`       | Leading (or trailing) media: icon, image, or avatar.                 |
+| `Item.Content`     | `cl-item-content`     | Vertical stack that grows to fill the row between media and actions. |
+| `Item.Title`       | `cl-item-title`       | Primary label.                                                       |
+| `Item.Description` | `cl-item-description` | Secondary text, clamped to two lines. Renders a `<p>`.               |
+| `Item.Actions`     | `cl-item-actions`     | Trailing controls (buttons, badges).                                 |
+| `Item.Group`       | `cl-item-group`       | Vertical list wrapper (`role="list"`).                               |
+| `Item.Separator`   | `cl-item-separator`   | Thin divider (`<hr>`) between rows.                                  |
+
+Every part accepts a `render` prop for element polymorphism and forwards a ref.
+
+## Styling
+
+The root reflects its state as `data-*` attributes on `.cl-item`, so consumers can scope overrides without touching StyleX's hashed atoms:
+
+| Prop     | Attribute          | Values                              | Default |
+| -------- | ------------------ | ----------------------------------- | ------- |
+| `render` | `data-interactive` | present when a `render` is provided | —       |
+
+```css
+/* Re-theme interactive rows */
+.cl-item[data-interactive] {
+  background-color: var(--cl-color-card);
+}
+```
+
+`Item.Media` sizes to its child and centers it; its height follows the row. Bring your own icon, avatar, or image at whatever dimensions you need (the examples use a 36px avatar and a 28px trailing icon), then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).

packages/swingset/src/stories/item.stories.tsx

@@ -0,0 +1,140 @@
+/** @jsxImportSource @emotion/react */
+import { Button } from '@clerk/ui/mosaic/components/button';
+import { Item } from '@clerk/ui/mosaic/components/item';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './item.stories?raw';
+
+export const meta: StoryMeta = {
+  group: 'Components',
+  title: 'Item',
+  source: 'packages/ui/src/mosaic/components/item/item.tsx',
+};
+
+// A square org/account avatar sized for the media slot (36px). Since `Item.Media`
+// fits its child, the avatar's own dimensions drive the slot width.
+function Avatar({ initial }: { initial: string }) {
+  return (
+    <span
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: '2.25rem',
+        height: '2.25rem',
+        borderRadius: 'var(--cl-radius-inner)',
+        backgroundColor: 'var(--cl-color-primary)',
+        color: 'var(--cl-color-primary-foreground)',
+        fontSize: '0.875rem',
+        fontWeight: 600,
+      }}
+    >
+      {initial}
+    </span>
+  );
+}
+
+function ArrowIcon() {
+  return (
+    <svg
+      width='16'
+      height='16'
+      viewBox='0 0 24 24'
+      fill='none'
+      stroke='currentColor'
+      strokeWidth='2'
+      strokeLinecap='round'
+      strokeLinejoin='round'
+    >
+      <path d='M5 12h14M13 5l7 7-7 7' />
+    </svg>
+  );
+}
+
+export function Default() {
+  return (
+    <Item>
+      <Item.Media>
+        <Avatar initial='T' />
+      </Item.Media>
+      <Item.Content>
+        <Item.Title>Test Organization</Item.Title>
+        <Item.Description>Member</Item.Description>
+      </Item.Content>
+      <Item.Actions>
+        <Button variant='outline'>Manage</Button>
+      </Item.Actions>
+    </Item>
+  );
+}
+
+export function Interactive() {
+  return (
+    <Item
+      render={({ children, ...props }) => (
+        <a
+          {...props}
+          href='#settings'
+        >
+          {children}
+        </a>
+      )}
+    >
+      <Item.Media>
+        <Avatar initial='T' />
+      </Item.Media>
+      <Item.Content>
+        <Item.Title>Test Organization</Item.Title>
+        <Item.Description>Member</Item.Description>
+      </Item.Content>
+      <Item.Media style={{ width: '1.75rem' }}>
+        <ArrowIcon />
+      </Item.Media>
+    </Item>
+  );
+}
+
+export function Group() {
+  return (
+    <Item.Group>
+      <Item
+        render={({ children, ...props }) => (
+          <a
+            {...props}
+            href='#one'
+          >
+            {children}
+          </a>
+        )}
+      >
+        <Item.Media>
+          <Avatar initial='C' />
+        </Item.Media>
+        <Item.Content>
+          <Item.Title>Clerk</Item.Title>
+        </Item.Content>
+      </Item>
+      <Item.Separator />
+      <Item
+        render={({ children, ...props }) => (
+          <a
+            {...props}
+            href='#two'
+          >
+            {children}
+          </a>
+        )}
+      >
+        <Item.Media>
+          <Avatar initial='C' />
+        </Item.Media>
+        <Item.Content>
+          <Item.Title>Clerk Cloud</Item.Title>
+        </Item.Content>
+      </Item>
+    </Item.Group>
+  );
+}

packages/ui/src/mosaic/components/item/index.ts

@@ -0,0 +1,2 @@
+export { Item } from './item';
+export type { ItemProps } from './item';

packages/ui/src/mosaic/components/item/item.styles.ts

@@ -0,0 +1,116 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+export const item = stylex.create({
+  base: {
+    padding: space['2'],
+    borderRadius: radiusVars['--cl-radius-element'],
+    gap: space['3'],
+    outline: {
+      default: 'none',
+      ':focus-visible': `2px solid color-mix(in oklab, ${colorVars['--cl-color-primary']} 50%, transparent)`,
+    },
+    alignItems: 'center',
+    boxSizing: 'border-box',
+    color: colorVars['--cl-color-card-foreground'],
+    display: 'flex',
+    flexWrap: 'wrap',
+    fontFamily: 'inherit',
+    fontSize: typeScaleVars['--cl-text-label-size'],
+    lineHeight: typeScaleVars['--cl-text-label-leading'],
+    outlineOffset: '2px',
+    textAlign: 'start',
+    transitionDuration: '150ms',
+    transitionProperty: 'background-color, color',
+    width: '100%',
+  },
+
+  // interactive rows (rendered as a link/button via `render`) gain hover + cursor
+  interactive: {
+    backgroundColor: {
+      default: null,
+      ':active': `color-mix(in oklab, ${colorVars['--cl-color-muted']} 70%, transparent)`,
+      '@media (hover: hover)': {
+        ':hover': `color-mix(in oklab, ${colorVars['--cl-color-muted']} 50%, transparent)`,
+      },
+    },
+    cursor: 'pointer',
+  },
+});
+
+export const media = stylex.create({
+  // sizes to its child; height follows the row (taller on a 2-line item, shorter on a button).
+  base: {
+    gap: space['2'],
+    alignItems: 'center',
+    display: 'flex',
+    flexShrink: 0,
+    justifyContent: 'center',
+    width: 'fit-content',
+  },
+});
+
+export const content = stylex.create({
+  base: {
+    display: 'flex',
+    flexDirection: 'column',
+    flexGrow: 1,
+    justifyContent: 'center',
+    minWidth: 0,
+  },
+});
+
+export const title = stylex.create({
+  base: {
+    gap: space['2'],
+    alignItems: 'center',
+    color: colorVars['--cl-color-card-foreground'],
+    display: 'flex',
+    fontSize: typeScaleVars['--cl-text-label-size'],
+    fontWeight: typeScaleVars['--cl-text-label-weight'],
+    lineHeight: typeScaleVars['--cl-text-label-leading'],
+    width: 'fit-content',
+  },
+});
+
+export const description = stylex.create({
+  base: {
+    overflow: 'hidden',
+    WebkitBoxOrient: 'vertical',
+    WebkitLineClamp: 2,
+    color: colorVars['--cl-color-muted-foreground'],
+    fontSize: typeScaleVars['--cl-text-label-sm-size'],
+    fontWeight: 400,
+    lineHeight: typeScaleVars['--cl-text-label-sm-leading'],
+  },
+});
+
+export const actions = stylex.create({
+  base: {
+    gap: space['2'],
+    alignItems: 'center',
+    display: 'flex',
+    flexShrink: 0,
+  },
+});
+
+export const group = stylex.create({
+  base: {
+    display: 'flex',
+    flexDirection: 'column',
+    width: '100%',
+  },
+});
+
+export const separator = stylex.create({
+  base: {
+    borderStyle: 'none',
+    marginBlock: space['2'],
+    marginInline: 0,
+    backgroundColor: colorVars['--cl-color-border'],
+    flexShrink: 0,
+    height: '1px',
+    width: '100%',
+  },
+});