@dxos/react-ui-card 0.8.2 → 0.11.0

package/package.json

@@ -1,54 +1,63 @@
 {
   "name": "@dxos/react-ui-card",
-  "version": "0.8.2",
-  "description": "An opinionated card component.",
+  "version": "0.11.0",
+  "description": "Shared card-composition primitives (Row, CardTile, Avatar).",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
-  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
-  "sideEffects": true,
   "type": "module",
+  "imports": {
+    "#translations": "./src/translations.ts"
+  },
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "import": "./dist/lib/index.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "import": "./dist/lib/translations.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@preact-signals/safe-react": "^0.9.0",
-    "@radix-ui/react-primitive": "2.0.2"
+    "date-fns": "^3.6.0",
+    "@dxos/echo": "0.11.0",
+    "@dxos/echo-react": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/lit-ui": "0.11.0",
+    "@dxos/react-ui": "0.11.0",
+    "@dxos/react-ui-mosaic": "0.11.0",
+    "@dxos/types": "0.11.0",
+    "@dxos/ui-theme": "0.11.0",
+    "@dxos/util": "0.11.0"
   },
   "devDependencies": {
-    "@dnd-kit/core": "^6.0.5",
-    "@dnd-kit/sortable": "^7.0.1",
-    "@dnd-kit/utilities": "^3.2.0",
-    "@phosphor-icons/react": "^2.1.5",
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "vite": "5.4.7",
-    "@dxos/random": "0.8.2",
-    "@dxos/react-ui": "0.8.2",
-    "@dxos/react-ui-theme": "0.8.2",
-    "@dxos/storybook-utils": "0.8.2",
-    "@dxos/util": "0.8.2"
+    "@types/react": "~19.2.17",
+    "@types/react-dom": "~19.2.3",
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "vite": "^8.1.4",
+    "@dxos/random": "0.11.0",
+    "@dxos/storybook-utils": "0.11.0"
   },
   "peerDependencies": {
-    "@phosphor-icons/react": "^2.1.5",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0",
-    "@dxos/react-ui-theme": "0.8.2",
-    "@dxos/react-ui": "0.8.2"
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "^0.11.0",
+    "@dxos/ui-theme": "^0.11.0"
   },
   "publishConfig": {
     "access": "public"

package/src/components/Avatar/Avatar.stories.tsx

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { Avatar } from './Avatar';
+
+const meta = {
+  title: 'ui/react-ui-card/Avatar',
+  component: Avatar,
+  decorators: [withTheme(), withLayout({ layout: 'centered' })],
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { actor: { name: 'Ada Lovelace', email: 'ada@example.com' } },
+};
+
+export const Square: Story = {
+  args: { actor: { name: 'Grace Hopper', email: 'grace@example.com' }, variant: 'square', size: 8 },
+};
+
+export const EmailOnly: Story = {
+  args: { actor: { email: 'nameless@example.com' } },
+};

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,39 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { DxAvatar, type DxAvatarProps } from '@dxos/lit-ui/react';
+import { type Actor } from '@dxos/types';
+
+import { avatarName } from './avatar-name';
+import { nameToHue } from './avatar-name';
+
+export type AvatarProps = Pick<DxAvatarProps, 'variant' | 'size' | 'onClick'> & {
+  /** Sender/participant; supplies the display name and the hue. */
+  actor?: Actor.Actor;
+  /** Label override; defaults to the actor's {@link avatarName}. */
+  name?: string;
+};
+
+/**
+ * Sender/participant avatar with one shared name→hue derivation ({@link nameToHue}) so a given
+ * person renders the same color across the mailbox list, the opened thread, and preview cards —
+ * previously each site hand-rolled `DxAvatar` off a different input.
+ */
+export const Avatar = ({ actor, name, variant = 'circle', size = 6, onClick }: AvatarProps) => {
+  const label = name ?? avatarName(actor);
+  return (
+    <DxAvatar
+      hue={nameToHue(label)}
+      hueVariant='surface'
+      variant={variant}
+      size={size}
+      fallback={label}
+      onClick={onClick}
+    />
+  );
+};
+
+Avatar.displayName = 'Avatar';

package/src/components/Avatar/avatar-name.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Actor } from '@dxos/types';
+import { toHue } from '@dxos/util';
+
+import { hashString } from '../../util';
+
+// Kept out of `Avatar.tsx`: react-refresh only fast-refreshes a module whose
+// exports are all components, so values exported beside them force a full page reload on
+// every edit.
+
+/** Canonical display name for an actor — the avatar glyph fallback and the hue key are both derived from it. */
+export const avatarName = (actor?: Actor.Actor): string =>
+  actor?.contact?.target?.fullName ?? actor?.name ?? actor?.email ?? '';
+
+/** Single source for a name→hue mapping, so the same sender is one color across every surface. */
+export const nameToHue = (name?: string): string => toHue(hashString(name));

package/src/components/Avatar/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './avatar-name';
+
+export * from './Avatar';

package/src/components/CardTile/CardTile.stories.tsx

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { Card } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { CardTile } from './CardTile';
+
+// CardTile.Header standalone inside Card chrome; CardTile.Root's mosaic shell is exercised by the
+// EventStack / InboxStack stories (it requires a Mosaic.Container ancestor).
+const DefaultStory = ({ menu, starred }: { menu?: boolean; starred?: boolean }) => (
+  <Card.Root fullWidth border={false} classNames='p-1'>
+    <CardTile.Header
+      menu={menu}
+      starred={starred}
+      onToggleStar={() => {}}
+      title={
+        <>
+          <span className='grow truncate font-medium'>Project kickoff — agenda and notes</span>
+          <span className='text-xs text-description whitespace-nowrap shrink-0'>2:30 PM</span>
+        </>
+      }
+    />
+    <Card.Body>
+      <Card.Row>
+        <Card.Text variant='description'>Body content rendered beneath the tile header.</Card.Text>
+      </Card.Row>
+    </Card.Body>
+  </Card.Root>
+);
+
+const meta = {
+  title: 'ui/react-ui-card/CardTile',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = { args: { starred: true, menu: true } };
+
+export const NoStar: Story = {};

package/src/components/CardTile/CardTile.tsx

@@ -0,0 +1,103 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type MouseEvent, PropsWithChildren, type ReactNode, forwardRef } from 'react';
+
+import { Card, type ThemedClassName } from '@dxos/react-ui';
+import { Focus, Mosaic, type MosaicTileProps } from '@dxos/react-ui-mosaic';
+
+import { Row } from '../Row';
+
+//
+// Root
+//
+
+type CardTileRootProps = ThemedClassName<
+  PropsWithChildren<
+    Pick<MosaicTileProps<unknown>, 'data' | 'location' | 'current'> & {
+      'id': string;
+      'onCurrentChange': () => void;
+      'onClick'?: (event: MouseEvent) => void;
+      'data-testid'?: string;
+    }
+  >
+>;
+
+/**
+ * Shared mosaic tile shell: `Mosaic.Tile` → `Focus.Item` → `Card.Root`.
+ * Callers supply the inner `Card.Header`/`Card.Body` (typically via {@link CardTileHeader} + rows).
+ * Activation is committed by the caller's `onCurrentChange` (Mosaic `current`/selection), so click/Enter light the tile up.
+ */
+const CardTileRoot = forwardRef<HTMLDivElement, CardTileRootProps>(
+  (
+    { id, data, location, current, onCurrentChange, onClick, classNames, children, 'data-testid': testId },
+    forwardedRef,
+  ) => (
+    <Mosaic.Tile
+      asChild
+      id={id}
+      data={data}
+      location={location}
+      classNames={classNames ?? 'dx-hover dx-current dx-selected p-1 rounded-md border border-subdued-separator'}
+    >
+      <Focus.Item asChild current={current} onCurrentChange={onCurrentChange}>
+        <Card.Root fullWidth border={false} onClick={onClick} ref={forwardedRef} data-testid={testId}>
+          {children}
+        </Card.Root>
+      </Focus.Item>
+    </Mosaic.Tile>
+  ),
+);
+
+CardTileRoot.displayName = 'CardTile.Root';
+
+//
+// Header
+//
+
+/** A single `Card.Menu` dropdown item. */
+export type CardTileMenuItem = {
+  label: string;
+  icon?: string;
+  onClick: () => void;
+};
+
+type CardTileHeaderProps = {
+  /** Header title content (rendered in a flex row). */
+  title: ReactNode;
+  /** Whether the tile is starred. `Row.Star` renders the button only when `onToggleStar` is set. */
+  starred?: boolean;
+  /** Render the trailing `Card.Menu` action slot. */
+  menu?: boolean;
+  /** Items for the `Card.Menu` dropdown (the trigger is disabled when empty). */
+  menuItems?: CardTileMenuItem[];
+  onToggleStar?: () => void;
+};
+
+/**
+ * Tile header row: leading `Row.Star` · title · optional `Card.Menu`. Shared by message/conversation
+ * tiles (with menu) and event tiles (star + title only).
+ */
+const CardTileHeader = ({ title, starred, menu = false, menuItems, onToggleStar }: CardTileHeaderProps) => (
+  <Card.Header>
+    <Card.Block>
+      <Row.Star starred={starred} onToggle={onToggleStar} />
+    </Card.Block>
+    <Card.Title classNames='flex items-center gap-3'>{title}</Card.Title>
+    {menu && <Card.Menu items={menuItems} />}
+  </Card.Header>
+);
+
+CardTileHeader.displayName = 'CardTile.Header';
+
+//
+// Tile
+//
+
+export const CardTile = {
+  Root: CardTileRoot,
+  Header: CardTileHeader,
+};
+
+export type { CardTileHeaderProps, CardTileRootProps };

package/src/components/CardTile/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './CardTile';

package/src/components/Row/Row.stories.tsx

@@ -0,0 +1,65 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+
+import { Obj, Ref } from '@dxos/echo';
+import { Card } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type Actor, Person } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { Row } from './Row';
+
+const SENDER: Actor.Actor = { name: 'Alice Avery', email: 'alice@example.com' };
+
+// Exercises each shared Card-row primitive inside the borderless Card chrome the tiles/headers use.
+const DefaultStory = () => {
+  const object = useMemo(() => Obj.make(Person.Person, { fullName: 'Casey Contact' }), []);
+  // A second stand-in object so the two attachment refs below have distinct URIs (and React keys).
+  const secondObject = useMemo(() => Obj.make(Person.Person, { fullName: 'Dana Reference' }), []);
+
+  return (
+    <Card.Root border={false} fullWidth classNames='p-1'>
+      <Card.Body>
+        <Row.Star starred onToggle={() => {}} />
+        <Row.Person actor={SENDER} role='from' avatar />
+        <Row.Person actor={SENDER} role='from' onContactCreate={() => {}} />
+        <Row.Date start={new Date('2025-11-19T12:00:00')} end={new Date('2025-11-19T13:30:00')} />
+        <Row.Ref object={object} />
+        <Row.Attachments
+          attachments={[
+            { name: 'invoice.pdf', ref: Ref.make(object) },
+            { name: 'photo.png', ref: Ref.make(secondObject) },
+          ]}
+        />
+        <Row.Tags
+          tags={[
+            { id: 'a', label: 'travel', hue: 'cyan' },
+            { id: 'b', label: 'urgent', hue: 'rose' },
+          ]}
+          onTagClick={() => {}}
+        />
+      </Card.Body>
+    </Card.Root>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-card/Row',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};