feat(ui): Let a Mosaic Item set its own outline variant

`variant` moves onto `Item.Root` as well as `Item.Group`, so a row standing on
its own can border itself. A row that sets one wins over its group, which also
lets a single row opt out of an outlined group with `default`.

Author: alexcarpenter

packages/swingset/src/stories/item.mdx

@@ -4,7 +4,7 @@ import * as ItemStories from './item.stories';
 
 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.Label`, …). `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.
 
-Set `variant='outline'` once on `Item.Group` and every row inside it gains a border, with the group spacing them apart rather than seating them on one surface.
+Set `variant='outline'` on a row to border it, or once on `Item.Group` to border every row inside it — the group then spaces them apart rather than seating them on one surface.
 
 Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's height and gap, and `Item.Media` picks the matching column width up from context rather than taking a size of its own.
 
@@ -36,11 +36,20 @@ Set `size` once on `Item.Root` and the row scales as a unit: it fixes the row's
   storyModule={ItemStories}
 />
 
+### Outline
+
+`variant='outline'` borders a row so it reads as its own card.
+
+<Story
+  name='Outline'
+  storyModule={ItemStories}
+/>
+
 ### Outline group
 
-`Item.Group` takes a `variant`. `outline` borders each row and reads the set as separate cards, so
-the group drops its own gutter and spaces the rows 8px apart instead. Rows pick the variant up from
-the group through context — they take no `variant` prop of their own.
+Set the same `variant` on `Item.Group` to border a whole set at once: the group drops its own gutter
+and spaces the rows 8px apart instead. Rows pick it up from the group through context, so only a row
+that disagrees needs a `variant` of its own.
 
 <Story
   name='OutlineGroup'
@@ -122,7 +131,7 @@ Media sizes itself from the row, so give it a child that fills its column — an
 | `Item.Label`       | `cl-item-label`       | The row's label. Truncates to a single line.                               |
 | `Item.Description` | `cl-item-description` | Secondary text beneath the label. Truncates to a single line.              |
 | `Item.Actions`     | `cl-item-actions`     | Trailing controls (buttons, badges).                                       |
-| `Item.Group`       | `cl-item-group`       | Vertical wrapper around a set of rows. Takes the `variant` its rows read.  |
+| `Item.Group`       | `cl-item-group`       | Vertical wrapper around a set of rows. Sets the `variant` its rows take.   |
 | `Item.Separator`   | `cl-item-separator`   | Thin divider (`<hr>`) between rows.                                        |
 
 Every part accepts a `render` prop for element polymorphism and forwards a ref.
@@ -137,21 +146,20 @@ The row carries the text color and, through `--_cl-icon-color`, the strength of
 | --------- | -------------- | ------------------------ | --------- |
 | `variant` | `data-variant` | `primary` \| `secondary` | `primary` |
 
-`Item.Group` chooses how its rows read as a set. `outline` borders each row and separates them; the
-group drops its gutter and spaces the rows by 8px. Rows read it from the group rather than taking it
-themselves, and reflect it as `data-variant` on `.cl-item`:
-
-| Prop      | Attribute      | Values                 | Default   |
-| --------- | -------------- | ---------------------- | --------- |
-| `variant` | `data-variant` | `default` \| `outline` | `default` |
+`variant` decides whether a row is bordered. It sits on both `Item.Root` and `Item.Group`: set it on
+the group and every row inside it takes it through context, with the group dropping its gutter and
+spacing the rows by 8px. A row that sets its own wins over its group, in either direction — so one
+row can opt out of an outlined group with `variant='default'`.
 
 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   |
-| --------- | ------------------ | ----------------------------------- | --------- |
-| `size`    | `data-size`        | `xs` \| `md`                        | `md`      |
-| `render`  | `data-interactive` | present when a `render` is provided | —         |
-| _(group)_ | `data-variant`     | `default` \| `outline`              | `default` |
+| Prop      | Attribute          | Values                              | Default     |
+| --------- | ------------------ | ----------------------------------- | ----------- |
+| `size`    | `data-size`        | `xs` \| `md`                        | `md`        |
+| `variant` | `data-variant`     | `default` \| `outline`              | its group's |
+| `render`  | `data-interactive` | present when a `render` is provided | —           |
+
+`Item.Group` reflects its own `variant` as `data-variant` on `.cl-item-group`.
 
 `size` fixes the row's height and gap. `Item.Media` reflects the same value as `data-size` and takes its width from it, so the two stay in step without being set twice:
 

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

@@ -269,6 +269,33 @@ export function Group() {
   );
 }
 
+export function Outline() {
+  return (
+    <Item.Root variant='outline'>
+      <Item.Media>
+        <Avatar.Root
+          shape='square'
+          size='fit'
+        >
+          <Avatar.Fallback>T</Avatar.Fallback>
+        </Avatar.Root>
+      </Item.Media>
+      <Item.Content>
+        <Item.Label>Test Organization</Item.Label>
+        <Item.Description>Member</Item.Description>
+      </Item.Content>
+      <Item.Actions>
+        <Button
+          variant='outline'
+          size='sm'
+        >
+          Manage
+        </Button>
+      </Item.Actions>
+    </Item.Root>
+  );
+}
+
 export function OutlineGroup() {
   return (
     <div className='w-full'>

packages/ui/src/mosaic/components/item/item.test.tsx

@@ -190,6 +190,26 @@ describe('Mosaic Item', () => {
     expect(atoms('Outlined').filter(atom => !atoms('Plain').includes(atom))).not.toHaveLength(0);
   });
 
+  it('takes a variant of its own, outside any group', () => {
+    render(<Item.Root variant='outline'>Hi</Item.Root>);
+    expect(screen.getByText('Hi')).toHaveAttribute('data-variant', 'outline');
+  });
+
+  it('lets a row override the variant its group provides, in both directions', () => {
+    render(
+      <>
+        <Item.Group variant='outline'>
+          <Item.Root variant='default'>Opted out</Item.Root>
+        </Item.Group>
+        <Item.Group>
+          <Item.Root variant='outline'>Opted in</Item.Root>
+        </Item.Group>
+      </>,
+    );
+    expect(screen.getByText('Opted out')).toHaveAttribute('data-variant', 'default');
+    expect(screen.getByText('Opted in')).toHaveAttribute('data-variant', 'outline');
+  });
+
   it('forwards the ref to the root element', () => {
     const ref = React.createRef<HTMLDivElement>();
     render(<Item.Root ref={ref}>Hi</Item.Root>);

packages/ui/src/mosaic/components/item/item.tsx

@@ -10,20 +10,20 @@ import { truncationStyles } from '../../utils/typography.styles';
 import * as slots from './item.styles';
 
 /** The row's height and gap, and the width of the media column inside it. */
-type Size = 'xs' | 'md';
+type Size = 'xs' | 'md' | 'lg';
 
 const DEFAULT_SIZE: Size = 'md';
 
 /** Carries `Item.Root`'s size down to the parts it scales (`Item.Media`). */
 const ItemContext = React.createContext<Size>(DEFAULT_SIZE);
 
-/** How a group presents its rows: as one continuous list, or as separated bordered rows. */
-type GroupVariant = 'default' | 'outline';
+/** How a row presents itself: seated on a shared surface, or bordered as its own card. */
+type Variant = 'default' | 'outline';
 
-const DEFAULT_GROUP_VARIANT: GroupVariant = 'default';
+const DEFAULT_VARIANT: Variant = 'default';
 
 /** Carries `Item.Group`'s variant down to the rows it borders (`Item.Root`). */
-const ItemGroupContext = React.createContext<GroupVariant>(DEFAULT_GROUP_VARIANT);
+const ItemGroupContext = React.createContext<Variant>(DEFAULT_VARIANT);
 
 export type ItemProps = MosaicComponentProps<'div'> & {
   /**
@@ -33,13 +33,22 @@ export type ItemProps = MosaicComponentProps<'div'> & {
    * @default 'md'
    */
   size?: Size;
+  /**
+   * `outline` borders the row so it reads as its own card. Set it here for a row
+   * standing on its own, or on `Item.Group` to border a whole set at once — a
+   * row set here wins over the group either way, so a row can opt out of an
+   * outlined group with `default`.
+   *
+   * @default the enclosing `Item.Group`'s variant, or `'default'`
+   */
+  variant?: Variant;
 };
 
 /**
  * Root row. Renders a `<div>`, or a custom element (link/button) via `render`,
  * which also opts the row into hover and cursor affordances. Provides its `size`
- * to the parts nested within it, and takes its border from the `variant` of the
- * enclosing `Item.Group`.
+ * to the parts nested within it, and takes its `variant` from the enclosing
+ * `Item.Group` unless it sets one of its own.
  *
  * @example
  * <Item.Root size='xs' render={({ children, ...props }) => <a {...props} href='/org'>{children}</a>}>
@@ -48,12 +57,15 @@ export type ItemProps = MosaicComponentProps<'div'> & {
  * </Item.Root>
  */
 const Root = React.forwardRef<HTMLDivElement, ItemProps>(function MosaicItem(
-  { size = DEFAULT_SIZE, render, className, style, ...rest },
+  { size = DEFAULT_SIZE, variant: variantProp, render, className, style, ...rest },
   ref,
 ) {
   // A custom render (link/button row) opts into hover + cursor affordances.
   const interactive = Boolean(render);
-  const variant = React.useContext(ItemGroupContext);
+  // The group is the default, not the authority: a row that names a variant keeps it, which is what
+  // lets one row opt out of an outlined group.
+  const groupVariant = React.useContext(ItemGroupContext);
+  const variant = variantProp ?? groupVariant;
   const element = useRender({
     defaultTagName: 'div',
     render,
@@ -202,19 +214,20 @@ export type ItemGroupProps = MosaicComponentProps<'div'> & {
    * `default` keeps the rows on one continuous surface, inset by the group's own
    * gutter. `outline` gives each row a border and reads them as separate cards,
    * so the group drops its gutter and spaces the rows apart instead. Reaches the
-   * rows through context rather than a prop on each one.
+   * rows through context, so a row only needs its own `variant` to disagree with
+   * the group.
    *
    * @default 'default'
    */
-  variant?: GroupVariant;
+  variant?: Variant;
 };
 
 /**
  * Vertical wrapper around a set of rows. Layout only; the rows carry their own
  * semantics. Provides its `variant` to the rows nested within it.
  */
 const Group = React.forwardRef<HTMLDivElement, ItemGroupProps>(function MosaicItemGroup(
-  { variant = DEFAULT_GROUP_VARIANT, render, className, style, ...rest },
+  { variant = DEFAULT_VARIANT, render, className, style, ...rest },
   ref,
 ) {
   const element = useRender({
@@ -263,8 +276,8 @@ const Separator = React.forwardRef<HTMLHRElement, MosaicComponentProps<'hr'>>(fu
  * `Item.Separator`. Every part takes a `render` prop and forwards a ref.
  *
  * `size` is set once on `Item.Root` and reaches `Item.Media` through context, so
- * a row scales as a unit rather than per part. `variant` is set once on
- * `Item.Group` and reaches its rows the same way.
+ * a row scales as a unit rather than per part. `variant` is set on a row, or
+ * once on `Item.Group` to reach every row in it.
  */
 export const Item = {
   Root,