@box/activity-feed 1.15.0

package/dist/types/lib/scroll/index.d.ts

@@ -0,0 +1,4 @@
+export { createActivityFeedScroll } from './create-activity-feed-scroll';
+export type { ActivityFeedScrollHandle, InternalActivityFeedScrollHandle } from './types';
+export { isAttachableActivityFeedScrollHandle } from './types';
+export { useActivityFeedScroll } from './use-activity-feed-scroll';

package/dist/types/lib/scroll/types.d.ts

@@ -0,0 +1,10 @@
+/** Public handle: scroll a keyed list row into view (smooth). */
+export interface ActivityFeedScrollHandle {
+    /** Scroll the row for `id` into view. Returns false when the row is not mounted. */
+    scrollTo: (id: string) => boolean;
+}
+/** Internal: same API plus container registration for `ActivityFeed.Root`. */
+export interface InternalActivityFeedScrollHandle extends ActivityFeedScrollHandle {
+    attachContainer: (node: HTMLElement | null) => void;
+}
+export declare function isAttachableActivityFeedScrollHandle(value: unknown): value is InternalActivityFeedScrollHandle;

package/dist/types/lib/scroll/use-activity-feed-scroll.d.ts

@@ -0,0 +1,6 @@
+import { ActivityFeedScrollHandle } from './types';
+/**
+ * Creates a stable scroll handle for `ActivityFeed.Root` (`scrollTo={...}` prop).
+ * Rows must use React `key={item.id}` so the list can tag DOM nodes for lookup.
+ */
+export declare function useActivityFeedScroll(): ActivityFeedScrollHandle;

package/dist/types/lib/stories/map-activity-item.d.ts

@@ -0,0 +1,18 @@
+import { TextMessageTypeV2 } from '@box/threaded-annotations';
+import { AppActivityItemProps } from '../components/app-activity-item';
+import { TaskItemProps } from '../components/task-item';
+import { VersionItemProps } from '../components/version-item';
+import { AppActivityFeedItem, TaskActivityItem, ThreadedActivityItem, VersionActivityItem } from '../types';
+/** Map a server-shaped {@link ThreadedActivityItem} to a `ThreadedAnnotationsV2` message. */
+export declare const toThreadedMessage: (item: ThreadedActivityItem) => TextMessageTypeV2;
+/** Flatten a nested {@link ThreadedActivityItem} tree into a flat message list. */
+export declare const flattenThreadMessages: (item: ThreadedActivityItem) => TextMessageTypeV2[];
+/**
+ * Map a {@link TaskActivityItem} (server-shaped activity feed projection) to
+ * the full {@link TaskItemProps} shape consumed by `TaskItem`.
+ */
+export declare const toTaskItemProps: (item: TaskActivityItem) => TaskItemProps;
+/** Map a {@link VersionActivityItem} to {@link VersionItemProps} (`trash` becomes `delete`). */
+export declare const toVersionItemProps: (item: VersionActivityItem) => VersionItemProps;
+/** Map an {@link AppActivityFeedItem} to {@link AppActivityItemProps}. */
+export declare const toAppActivityItemProps: (item: AppActivityFeedItem) => AppActivityItemProps;

package/dist/types/lib/stories/shared.d.ts

@@ -0,0 +1,15 @@
+import { ActivityFeedItem } from '../types';
+export interface InteractiveActivityFeedProps {
+    /** Optional item override. */
+    items?: ActivityFeedItem[];
+    /** Initial mention-me value. */
+    initialMentionMe?: boolean;
+    /** Initial show-resolved value. */
+    initialShowResolvedComments?: boolean;
+    /** Storybook-only: when set, scroll the row with this id into view on mount/change. */
+    scrollToItemId?: string;
+    /** Close callback. */
+    onClose: () => void;
+}
+/** Full Storybook harness for ActivityFeed. */
+export declare const InteractiveActivityFeed: ({ initialMentionMe, initialShowResolvedComments, items, scrollToItemId, onClose, }: InteractiveActivityFeedProps) => import("react/jsx-runtime").JSX.Element;

package/dist/types/lib/test-utils/button-utils.d.ts

@@ -0,0 +1,14 @@
+import { userEvent, within } from 'storybook/test';
+export declare const waitForButtonByName: (canvas: ReturnType<typeof within>, name: string | RegExp, options?: {
+    timeout?: number;
+}) => Promise<any>;
+export declare const waitForButtonToDisappear: (canvas: ReturnType<typeof within>, name: string | RegExp) => Promise<void>;
+export declare const clickButtonByName: (user: ReturnType<typeof userEvent.setup>, canvas: ReturnType<typeof within>, name: string | RegExp) => Promise<void>;
+export declare const waitForMenuItemByName: (canvas: ReturnType<typeof within>, name: string | RegExp, options?: {
+    timeout?: number;
+}) => Promise<any>;
+export declare const clickMenuItemByName: (user: ReturnType<typeof userEvent.setup>, canvas: ReturnType<typeof within>, name: string | RegExp) => Promise<void>;
+export declare const waitForMenuItemCheckboxByName: (canvas: ReturnType<typeof within>, name: string | RegExp, options?: {
+    timeout?: number;
+}) => Promise<any>;
+export declare const clickMenuItemCheckboxByName: (user: ReturnType<typeof userEvent.setup>, canvas: ReturnType<typeof within>, name: string | RegExp) => Promise<void>;

package/dist/types/lib/test-utils/index.d.ts

@@ -0,0 +1 @@
+export * from './mocks';

package/dist/types/lib/test-utils/mocks/index.d.ts

@@ -0,0 +1,5 @@
+export * from './mock-collaboration-props';
+export * from './mock-feed-items';
+export * from './mock-mention-context';
+export * from './mock-user-selector-props';
+export * from './mock-users';

package/dist/types/lib/test-utils/mocks/mock-collaboration-props.d.ts

@@ -0,0 +1,9 @@
+import { CollaborationPopoverType } from '@box/collaboration-popover';
+export declare const createMockCollaborationPopoverProps: () => {
+    onSubmit: () => Promise<void>;
+    onUserClick: import('storybook/test').Mock<(...args: any[]) => any>;
+    onClose: import('storybook/test').Mock<(...args: any[]) => any>;
+    onInviteTypeChange: import('storybook/test').Mock<(...args: any[]) => any>;
+    loading: boolean;
+    type: CollaborationPopoverType;
+};

package/dist/types/lib/test-utils/mocks/mock-feed-items.d.ts

@@ -0,0 +1,20 @@
+import { ActivityFeedItem, AppActivityFeedItem, TaskActivityItem, ThreadedActivityItem, VersionActivityItem } from '../../types';
+/** Threaded comment with one reply and a resolved sibling thread. */
+export declare const MOCK_COMMENT_THREAD: ThreadedActivityItem;
+export declare const MOCK_RESOLVED_COMMENT_THREAD: ThreadedActivityItem;
+/** Annotation thread anchored to a page in the file. */
+export declare const MOCK_ANNOTATION_THREAD: ThreadedActivityItem;
+/** General task in progress, current user is one of the assignees. */
+export declare const MOCK_TASK_IN_PROGRESS: TaskActivityItem;
+/** Completed approval task, locked. */
+export declare const MOCK_TASK_APPROVED: TaskActivityItem;
+/** Box for Slack-style app activity. */
+export declare const MOCK_APP_ACTIVITY_SHARED: AppActivityFeedItem;
+/** Workflow-step app activity with plain text. */
+export declare const MOCK_APP_ACTIVITY_WORKFLOW: AppActivityFeedItem;
+/** Version uploaded by a user. */
+export declare const MOCK_VERSION_UPLOADED: VersionActivityItem;
+/** Version restored event. */
+export declare const MOCK_VERSION_RESTORED: VersionActivityItem;
+/** Mixed feed used by Default / Realistic stories. Ordered newest-first. */
+export declare const MOCK_FEED_ITEMS: ActivityFeedItem[];

package/dist/types/lib/test-utils/mocks/mock-mention-context.d.ts

@@ -0,0 +1,2 @@
+import { MentionContextData } from '@box/threaded-annotations';
+export declare const createMockMentionContext: () => MentionContextData;

package/dist/types/lib/test-utils/mocks/mock-user-selector-props.d.ts

@@ -0,0 +1,2 @@
+import { HeadlessUserSelectorProps } from '@box/user-selector';
+export declare const createDefaultUserSelectorProps: () => Omit<HeadlessUserSelectorProps, "inputElementRef" | "onSelectedUserChange" | "open" | "rootElement" | "value">;

package/dist/types/lib/test-utils/mocks/mock-users.d.ts

@@ -0,0 +1,55 @@
+import { UserContactType } from '@box/user-selector';
+export declare const MOCK_USERS: {
+    readonly LIAM_FOSTER: {
+        readonly avatarUrl: "/img/avatar.svg";
+        readonly email: "liam.foster@example.com";
+        readonly id: 1;
+        readonly name: "Liam Foster";
+        readonly value: "Liam Foster";
+        readonly isExternalUser: false;
+    };
+    readonly SARAH_CHEN: {
+        readonly email: "sarah.chen@example.com";
+        readonly id: 2;
+        readonly name: "Sarah Chen";
+        readonly value: "Sarah Chen";
+        readonly isExternalUser: true;
+    };
+    readonly ALEX_RODRIGUEZ: {
+        readonly email: "alex.rodriguez@example.com";
+        readonly id: 3;
+        readonly name: "Alex Rodriguez";
+        readonly value: "Alex Rodriguez";
+        readonly isExternalUser: false;
+    };
+    readonly EMMA_WILSON: {
+        readonly avatarUrl: "/img/avatar.svg";
+        readonly email: "emma.wilson@external.com";
+        readonly id: 4;
+        readonly name: "Emma Wilson";
+        readonly value: "Emma Wilson";
+        readonly isExternalUser: true;
+    };
+    readonly DAVID_THOMPSON: {
+        readonly email: "david.thompson@example.com";
+        readonly id: 12312312;
+        readonly name: "David Thompson";
+        readonly value: "David Thompson";
+        readonly isExternalUser: false;
+    };
+    readonly TEST_USER: {
+        readonly id: 1213123;
+        readonly name: "Test User";
+        readonly email: "test@box.com";
+        readonly isExternalUser: false;
+        readonly value: "Test User";
+    };
+    readonly CURRENT_USER: {
+        readonly email: "you@example.com";
+        readonly id: 999;
+        readonly name: "Test User";
+        readonly value: "Test User";
+        readonly isExternalUser: false;
+    };
+};
+export declare const MOCK_USER_SELECTOR_USERS: UserContactType[];

package/dist/types/lib/test-utils/text-utils.d.ts

@@ -0,0 +1,3 @@
+import { within } from 'storybook/test';
+export declare const waitForTextToAppear: (canvas: ReturnType<typeof within>, text: string, exact?: boolean, timeout?: number) => Promise<any>;
+export declare const waitForTextToDisappear: (canvas: ReturnType<typeof within>, text: string) => Promise<void>;

package/dist/types/lib/types/ActivityItem.d.ts

@@ -0,0 +1,145 @@
+import { DocumentNode } from '@box/threaded-annotations';
+import { ActivityAuthor, ActivityItemError, ActivityPermissions, ActivityStatus, AnnotationTarget } from './common';
+/**
+ * Annotation or comment thread, rendered by `@box/threaded-annotations`.
+ *
+ * This is the canonical data contract for activity-feed consumers and is
+ * intentionally kept separate from `threaded-annotations`' `TextMessageType`
+ * so the two packages can evolve independently.
+ *
+ * Threads include their replies inline so consumers can pass the full tree
+ * directly to `ActivityFeed.List`.
+ */
+export type ThreadedActivityItem = {
+    /** Discriminator. `comment` for top-level comments, `annotation` for in-file pins. */
+    activityType: 'annotation' | 'comment';
+    /** Pointer to the in-file location for annotation threads. */
+    annotationTarget?: AnnotationTarget;
+    /** Author of the root message in the thread. */
+    author: ActivityAuthor;
+    /** TipTap document node for the message body. */
+    body: DocumentNode;
+    /** Unix timestamp (ms) when the root message was posted. */
+    createdAt: number;
+    /** Error attached to this item (e.g. failed post). */
+    error?: ActivityItemError;
+    /** File version id this thread is anchored to (when applicable). */
+    fileVersionId?: string;
+    /** Stable id for the root message of the thread. */
+    id: string;
+    /** When `true`, the message has been edited at least once. */
+    isEdited?: boolean;
+    /** When `true`, the message is optimistic and not yet acknowledged by the server. */
+    isPending?: boolean;
+    /** Unix timestamp (ms) of the last modification (edit or resolve). */
+    modifiedAt?: number;
+    /** Action permissions for the root message. */
+    permissions: ActivityPermissions;
+    /** Replies in posting order. */
+    replies: ThreadedActivityItem[];
+    /** Open / resolved lifecycle status. */
+    status?: ActivityStatus;
+    /** Total reply count from the server (may exceed `replies.length` when paginated). */
+    totalReplyCount?: number;
+};
+/**
+ * Box task item, rendered by `TaskItem`.
+ *
+ * Simplified server-shaped task projection. Project to `TaskItemProps`
+ * (mapping assignee status, completion rule, permissions, etc.) before
+ * rendering as a child of `ActivityFeed.List.Task`.
+ */
+export type TaskActivityItem = {
+    /** Discriminator. */
+    activityType: 'task';
+    /** People assigned to the task. */
+    assignees: TaskAssignee[];
+    /** Task creator. */
+    author: ActivityAuthor;
+    /** Completion rule (e.g. `ALL_ASSIGNEES`, `ANY_ASSIGNEE`). */
+    completionRule: string;
+    /** Unix timestamp (ms) when the task was created. */
+    createdAt: number;
+    /** Free-text description displayed in the card body. */
+    description?: string;
+    /** Unix timestamp (ms) of the due date, when set. */
+    dueAt?: number;
+    /** Stable task id. */
+    id: string;
+    /** When `true`, the task is optimistic and not yet acknowledged by the server. */
+    isPending?: boolean;
+    /** Display name for the task. */
+    name: string;
+    /** API permissions on the task resource. */
+    permissions: {
+        canDelete?: boolean;
+        canUpdate?: boolean;
+    };
+    /** Aggregate task status (e.g. `IN_PROGRESS`, `COMPLETED`). */
+    status: string;
+};
+/** Assignee row used by {@link TaskActivityItem}. */
+export type TaskAssignee = {
+    /** Optional avatar URL for the assignee. */
+    avatarUrl?: string;
+    /** Unix timestamp (ms) when the assignee completed the task. */
+    completedAt?: number;
+    /** Assignee user id. */
+    id: string;
+    /** When `true`, applies external collaborator treatment. */
+    isExternal?: boolean;
+    /** Assignee display name. */
+    name: string;
+    /** Per-assignee status (e.g. `NOT_STARTED`, `APPROVED`). */
+    status: string;
+};
+/**
+ * App-generated activity entry, rendered by `AppActivityItem`.
+ *
+ * Used for system-style messages such as "Box for Slack shared this file in #channel".
+ */
+export type AppActivityFeedItem = {
+    /** Discriminator. */
+    activityType: 'app_activity';
+    /** URL of the app icon shown in the avatar slot. */
+    appIconUrl: string;
+    /** App display name (e.g. "Box for Slack"). */
+    appName: string;
+    /** Author principal that performed the action. */
+    author: ActivityAuthor;
+    /** Unix timestamp (ms) of the activity. */
+    createdAt: number;
+    /** Stable id for the activity entry. */
+    id: string;
+    /** API-provided pre-sanitized HTML; renderer turns `<a>` into Blueprint links. */
+    renderedText: string;
+};
+/**
+ * Version marker, rendered by `VersionItem`.
+ *
+ * Used to show file lifecycle events (upload, restore, promote, trash) inside
+ * the feed timeline.
+ */
+export type VersionActivityItem = {
+    /** Action that produced this version event. `trash` is rendered as the delete variant. */
+    actionType: 'promote' | 'restore' | 'trash' | 'upload';
+    /** Discriminator. */
+    activityType: 'version';
+    /** User or app that performed the version action. */
+    author: ActivityAuthor;
+    /** Unix timestamp (ms) when the version event occurred. */
+    createdAt: number;
+    /** Stable id for the version entry. */
+    id: string;
+    /** Primary version number shown on the badge. */
+    versionNumber: number;
+};
+/**
+ * Discriminated union of every built-in activity item shape.
+ *
+ * Useful when iterating over a heterogeneous server payload and dispatching
+ * to the matching `ActivityFeed.List.*` row. Each row is the underlying
+ * primitive component re-exported as-is, so consumers project this shape
+ * into the row's prop signature at the call site.
+ */
+export type ActivityFeedItem = AppActivityFeedItem | TaskActivityItem | ThreadedActivityItem | VersionActivityItem;

package/dist/types/lib/types/common.d.ts

@@ -0,0 +1,82 @@
+/**
+ * String discriminator for every activity feed item kind that the feed can render.
+ *
+ * Used by `ActivityFeedItem.activityType` to drive the renderer mapping inside
+ * `ActivityFeed.List`. New types must be added to this union together with a
+ * matching variant in `ActivityFeedItem` and a renderer in `ActivityFeed.List`.
+ */
+export type ActivityItemType = 'annotation' | 'app_activity' | 'comment' | 'task' | 'version';
+/**
+ * Lifecycle status for threaded items (annotations and comments).
+ *
+ * - `open` — the thread is active and accepts replies / resolution actions.
+ * - `resolved` — the thread is resolved; UI shows the resolved banner.
+ */
+export type ActivityStatus = 'open' | 'resolved';
+/**
+ * Minimal author shape used across every activity item type.
+ *
+ * Activity feed items intentionally use a stringly-typed `id` so the same
+ * shape can describe Box users, app-bot principals, and external collaborators.
+ */
+export type ActivityAuthor = {
+    /** Optional avatar URL. When omitted, the renderer falls back to initials. */
+    avatarUrl?: string;
+    /** Stable identifier for the author (Box user id, app id, or principal id). */
+    id: string;
+    /** When `true`, the renderer can apply "you" treatments (e.g. highlight). */
+    isCurrentUser?: boolean;
+    /** When `true`, the renderer applies external collaborator treatment (badge). */
+    isExternalUser?: boolean;
+    /** Display name shown in the UI. */
+    name: string;
+};
+/**
+ * Per-item action permissions.
+ *
+ * Only the actions that are `true` are shown in the UI; missing fields are
+ * treated as `false` so consumers can omit them safely.
+ */
+export type ActivityPermissions = {
+    /** Allows the delete action on the item. */
+    canDelete?: boolean;
+    /** Allows the edit action on the item. */
+    canEdit?: boolean;
+    /** Allows posting replies into the thread. */
+    canReply?: boolean;
+    /** Allows resolving / unresolving the thread. */
+    canResolve?: boolean;
+};
+/**
+ * Pointer to where an annotation lives in the underlying file.
+ *
+ * Used by `ThreadedActivityItem.annotationTarget` to render the badge for
+ * annotation threads (page number, highlighted excerpt, or timestamp).
+ */
+export type AnnotationTarget = {
+    page: number;
+    type: 'drawing' | 'point' | 'region';
+} | {
+    highlightedText: string;
+    type: 'highlight';
+} | {
+    timestamp: string;
+    type: 'frame';
+};
+/**
+ * Error attached to a single activity item (e.g. a failed post / sync error).
+ *
+ * Renderers display the `title` and `message` as a banner and, when `action`
+ * is provided, a button that triggers `onAction` (e.g. retry).
+ */
+export type ActivityItemError = {
+    /** Optional retry / call-to-action button. */
+    action?: {
+        onAction: () => void;
+        text: string;
+    };
+    /** Body copy explaining the error. */
+    message: string;
+    /** Short error title shown above the message. */
+    title: string;
+};

package/dist/types/lib/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { DocumentNode } from '@box/threaded-annotations';
+export type { ActivityFeedItem, AppActivityFeedItem, TaskActivityItem, TaskAssignee, ThreadedActivityItem, VersionActivityItem, } from './ActivityItem';
+export type { ActivityAuthor, ActivityItemError, ActivityItemType, ActivityPermissions, ActivityStatus, AnnotationTarget, } from './common';

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@box/activity-feed",
+    "version": "1.15.0",
+    "license": "SEE LICENSE IN LICENSE",
+    "peerDependencies": {
+        "@box/blueprint-web": "^14.16.2",
+        "@box/blueprint-web-assets": "^4.115.2",
+        "@box/collaboration-popover": "^1.61.3",
+        "@box/readable-time": "^1.40.3",
+        "@box/threaded-annotations": "^1.83.3",
+        "@box/user-selector": "^1.75.3",
+        "clsx": "^1.2.1",
+        "react": "^18.0.0",
+        "react-dom": "^18.0.0",
+        "react-intl": "^6.4.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "devDependencies": {
+        "@box/blueprint-web": "^14.16.2",
+        "@box/blueprint-web-assets": "^4.115.2",
+        "@box/collaboration-popover": "^1.61.3",
+        "@box/eslint-plugin-blueprint": "1.1.18",
+        "@box/readable-time": "^1.40.3",
+        "@box/storybook-utils": "0.18.2",
+        "@box/threaded-annotations": "^1.83.3",
+        "@box/user-selector": "^1.75.3",
+        "react-intl": "^6.4.2"
+    },
+    "files": [
+        "dist"
+    ],
+    "main": "./dist/esm/index.js",
+    "module": "./dist/esm/index.js",
+    "types": "./dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "require": "./dist/esm/index.js",
+            "import": "./dist/esm/index.js",
+            "types": "./dist/types/index.d.ts"
+        },
+        "./*": {
+            "require": "./dist/esm/*",
+            "import": "./dist/esm/*",
+            "types": "./dist/types/*"
+        },
+        "./i18n/*": {
+            "require": "./dist/i18n/*",
+            "import": "./dist/i18n/*"
+        }
+    },
+    "sideEffects": [
+        "**/*.css"
+    ]
+}