feat(ui): add Mosaic Item component (#9234)

Author: alexcarpenter

.changeset/mosaic-item.md

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

packages/swingset/src/components/DocsViewer.tsx

@@ -33,6 +33,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

@@ -46,6 +46,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,
@@ -149,6 +155,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,
@@ -204,6 +217,7 @@ export const registry: StoryModule[] = [
   buttonModule,
   cardComponentModule,
   inputModule,
+  itemModule,
   dialogComponentModule,
   headingModule,
   iconModule,

packages/swingset/src/stories/item.mdx

@@ -0,0 +1,89 @@
+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.Root`, `Item.Media`, `Item.Content`, `Item.Title`, …). `Item.Root` renders as a `<div>` by default; pass it 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 { Avatar } from '@clerk/ui/mosaic/components/avatar';
+import { Item } from '@clerk/ui/mosaic/components/item';
+
+<Item.Group>
+  <Item.Root render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
+    <Item.Media>
+      <Avatar.Root shape='square' size='md'>
+        <Avatar.Image src={org.imageUrl} alt='' />
+        <Avatar.Fallback>{org.name[0]}</Avatar.Fallback>
+      </Avatar.Root>
+    </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.Root>
+</Item.Group>;
+```
+
+## Parts
+
+| Part                 | Class                    | Description                                                          |
+| -------------------- | ------------------------ | -------------------------------------------------------------------- |
+| `Item.Root`          | `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. Renders a `<p>`.                                     |
+| `Item.Actions`       | `cl-item-actions`        | Trailing controls (buttons, badges).                                 |
+| `Item.Header`        | `cl-item-header`         | Header row above a group: a label with optional actions.             |
+| `Item.HeaderTitle`   | `cl-item-header-title`   | Label text within an `Item.Header`.                                  |
+| `Item.HeaderActions` | `cl-item-header-actions` | Trailing controls within an `Item.Header`.                           |
+| `Item.Group`         | `cl-item-group`          | Vertical wrapper around a set of rows (layout only, no role).        |
+| `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  |
+| --------- | ------------------ | ----------------------------------- | -------- |
+| `variant` | `data-variant`     | `entity` \| `action`                | `entity` |
+| `render`  | `data-interactive` | present when a `render` is provided | —        |
+
+`variant` sets the row's vertical density (`entity` is standard, `action` is denser) and, on interactive rows, promotes the title color.
+
+```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, then size the slot by sizing that child. Colors, radii, and spacing all resolve from the Mosaic tokens (`--cl-color-*`, `--cl-radius-*`, `--cl-spacing`).