themelia-react-ui 0.0.0-stage → 1.0.0

package/dist/components/blocks/timelines/shared/timeline.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Timeline — shared base primitive for the blocks timeline family.
+ *
+ * Renders a vertical, dot-and-line list of events. Each item supports an
+ * icon (Lucide component), a status that maps to dot tone, a title row, an
+ * optional description block, an optional timestamp, and free-form content
+ * via `children`. Use this primitive directly for new timeline variants
+ * instead of reinventing the dot/line geometry — see `ChangeLogTimeline`,
+ * `MilestonesTimeline`, and the existing OrderTimeline / PaymentTimeline /
+ * ActivityStream consumers for examples.
+ */
+import type { LucideIcon } from 'lucide-react';
+import type { ReactNode } from 'react';
+import type { ComponentScale } from '../../../../lib/component-vocabulary';
+export type TimelineStatus = 'completed' | 'current' | 'pending' | 'success' | 'warning' | 'error' | 'neutral';
+export type TimelineDotSize = ComponentScale;
+export interface TimelineItem {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Surface title. */
+    title: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Formatted time for the entry. */
+    timestamp?: ReactNode;
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    status?: TimelineStatus;
+    children?: ReactNode;
+}
+export interface TimelineProps {
+    items: TimelineItem[];
+    dotSize?: TimelineDotSize;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function Timeline({ items, dotSize, className }: TimelineProps): import("react").JSX.Element;
+export declare namespace Timeline {
+    var displayName: string;
+}

package/dist/components/blocks/timelines/steps-card/index.d.ts

@@ -0,0 +1,2 @@
+export type { StepStatus, StepItem, StepsCardProps, StepsHorizontalProps } from './types';
+export { StepsCard, StepsHorizontal } from './steps-card';

package/dist/components/blocks/timelines/steps-card/steps-card.d.ts

@@ -0,0 +1,9 @@
+import { type StepsCardProps, type StepsHorizontalProps } from './types';
+export declare function StepsCard({ title, description, steps, footerText, className }: StepsCardProps): import("react").JSX.Element;
+export declare namespace StepsCard {
+    var displayName: string;
+}
+export declare function StepsHorizontal({ title, description, steps, footerText, className }: StepsHorizontalProps): import("react").JSX.Element;
+export declare namespace StepsHorizontal {
+    var displayName: string;
+}

package/dist/components/blocks/timelines/steps-card/types.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from 'react';
+import type { BadgeTone } from '../../../base/badge';
+export type StepStatus = 'completed' | 'current' | 'upcoming';
+export interface StepItem {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    status: StepStatus;
+    /** Formatted time for the entry. */
+    timestamp?: string;
+    /** Chip rendered beside the label. */
+    badge?: string;
+    badgeTone?: BadgeTone;
+    content?: ReactNode;
+}
+export interface StepsCardProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    steps: StepItem[];
+    footerText?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface StepsHorizontalProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    steps: StepItem[];
+    footerText?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+}

package/dist/components/features/activities/activities-feed.d.ts

@@ -0,0 +1,5 @@
+import type { ActivityFeedProps } from './activities.types';
+export declare function ActivityFeed<TData = unknown>(props: ActivityFeedProps<TData>): import("react").JSX.Element;
+export declare namespace ActivityFeed {
+    var displayName: string;
+}

package/dist/components/features/activities/activities.config.d.ts

@@ -0,0 +1,6 @@
+import type { ActivityEventConfig, ActivityEventConfigMap } from './activities.types';
+/** Neutral fallback used when an event has no entry in the registry. */
+export declare const defaultEventConfig: ActivityEventConfig;
+export declare const defaultActivityEventConfig: ActivityEventConfigMap;
+/** Resolve `eventConfig[event]` with override + default fallback. */
+export declare function resolveEventConfig(event: string, map: ActivityEventConfigMap): ActivityEventConfig;

package/dist/components/features/activities/activities.strings.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Strings for the Activities feature. Consumers override via the `strings`
+ * prop on `<ActivityFeed>` / `<ActivityLog>`. Values are deep-merged
+ * over these defaults — `sources` and `events` merge one level deep so a
+ * consumer can override a single source/event label without rewriting the
+ * whole map.
+ */
+export interface ActivitiesStrings {
+    /** Activity surface title — usually "Activity". */
+    title: string;
+    /** Empty-state copy. */
+    empty: string;
+    /** Loading-state copy. */
+    loading: string;
+    /** Date-group label for today. */
+    today: string;
+    /** Date-group label for yesterday. */
+    yesterday: string;
+    /** Fallback label for activities without a timestamp. */
+    undated: string;
+    /** Replacement for actor name when `actorId === currentUserId`. */
+    you: string;
+    /** Detail toggle label — collapsed state. */
+    showChanges: string;
+    /** Detail toggle label — expanded state. */
+    hideChanges: string;
+    /** aria-label for the actions menu trigger. */
+    actionsLabel: string;
+    /** Generic "more" affordance label. */
+    moreLabel: string;
+    /** Map of `source` → display label. */
+    sources: Record<string, string>;
+    /** Map of `event` → display label. Used as a fallback for headlines. */
+    events: Record<string, string>;
+}
+export declare const defaultActivitiesStrings: ActivitiesStrings;
+/** Replace `{{key}}` tokens with values from `params`. */
+export declare function interpolate(template: string, params: Record<string, string | number>): string;

package/dist/components/features/activities/activities.types.d.ts

@@ -0,0 +1,431 @@
+/**
+ * Activities feature types. Decoupled from any framework module so the feature
+ * ships standalone — consumers map their domain types into `ActivityItem<TData>`
+ * at the call site via accessors / callbacks.
+ */
+import type { LucideIcon } from 'lucide-react';
+import type { Locale } from 'date-fns';
+import type { ComponentType, ReactNode } from 'react';
+import type { CommentData, CommentSubmitHelpers, CommentFormValues, CommentUser, CommentsAccessors, CommentsConfig, CommentsStrings } from '../comments';
+import type { Mention, MentionsConfig } from '../mentions';
+import type { StringsProp } from '../../../lib/strings';
+import type { SemanticTone } from '../../../lib/component-vocabulary';
+import type { ActivitiesStrings } from './activities.strings';
+/** Semantic tone shared by the marker, status badges, and resource chips. */
+export type ActivityTone = SemanticTone;
+/** Density preset: dot-only / standard icon row / full rich row with extras. */
+export type ActivityDensity = 'compact' | 'default' | 'rich';
+/** Vertical rhythm between activity rows. */
+export type ActivityItemSpacing = 'compact' | 'default' | 'relaxed';
+/** Person who caused the activity. */
+export interface ActivityActor {
+    /** Stable id used to detect "current user" → "You" rendering. */
+    id?: string;
+    /** Display name. */
+    name: string;
+    avatarUrl?: string;
+    /** Initials fallback when avatar is missing. */
+    initials?: string;
+    /** Anchor href when the consumer wants the actor name to be a link. */
+    href?: string;
+}
+/** Lightweight pointer to a resource — looked up against the registry. */
+export interface ActivityResourceRef {
+    /** Stable key — domain-scoped (e.g. `order:1234`, `user:42`). */
+    key: string;
+    /** Domain hint — `order`, `product`, `user`, `task`, … */
+    type?: string;
+    /** Display label fallback when the registry has no entry. */
+    label?: string;
+}
+/**
+ * Persisted, rich resource configuration. The registry maps `key → config`,
+ * and consumers can save/restore the whole map via `onResourcesChange`.
+ */
+export interface ActivityResourceConfig {
+    /** Display label. */
+    label: string;
+    /** Destination for the entry, when it navigates. */
+    href?: string;
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ActivityTone;
+    /** Inline status badge alongside the chip. */
+    badge?: {
+        label: string;
+        tone?: ActivityTone;
+    };
+    /** Free-form tags rendered after the label. */
+    tags?: readonly string[];
+    /** Free-form note exposed via tooltip. */
+    note?: string;
+}
+/** A single piece of the headline — blocks inline by the renderer. */
+export type ActivityHeadlineSegment = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'actor';
+    text: string;
+    actorId?: string;
+    href?: string;
+} | {
+    type: 'field';
+    text: string;
+} | {
+    type: 'value';
+    text: string;
+} | {
+    type: 'status';
+    text: string;
+    tone?: ActivityTone;
+} | {
+    type: 'resource';
+    text?: string;
+    resource: ActivityResourceRef;
+};
+/** A single before / after pair — feeds the collapsible detail block. */
+export interface ActivityChange {
+    /** Attribute key — used as React key. */
+    key: string;
+    /** Display label of the attribute. */
+    label: string;
+    /** Before value. `null` means there was no prior value. */
+    old?: ReactNode | null;
+    /** After value. `null` means the value was cleared. */
+    new?: ReactNode | null;
+    /** Free-form description fallback when neither old/new is set. */
+    description?: ReactNode;
+}
+/** A single activity entry. Generic over `TData` for domain payload. */
+export interface ActivityItem<TData = unknown> {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Domain event key (e.g. `created`, `status_changed`, `mail_sent`). */
+    event: string;
+    /** Optional source bucket — drives the source-badge label. */
+    source?: string;
+    actor?: ActivityActor;
+    /** Pre-built segments — preferred over `headline`. */
+    segments?: readonly ActivityHeadlineSegment[];
+    /** Plain-text fallback when no segments are provided. */
+    headline?: string;
+    /** Secondary description rendered beneath the headline. */
+    description?: ReactNode;
+    /** ISO timestamp — drives date grouping and relative time. */
+    createdAt?: string;
+    /** Pre-formatted timestamp override — bypasses accessors. */
+    timestamp?: string;
+    /** Inline chip-row metadata (rich density). */
+    metadata?: ReadonlyArray<{
+        label: string;
+        value: ReactNode;
+    }>;
+    /** Per-attribute change details. */
+    changes?: readonly ActivityChange[];
+    /** Additional detail content rendered in the rich detail panel. */
+    details?: ReactNode;
+    /** Opt this row into collapsible details. Defaults to feature behavior. */
+    collapsible?: boolean;
+    /** Initial expanded state for this row in uncontrolled mode. */
+    defaultExpanded?: boolean;
+    /** Resources referenced — looked up against the registry for rich chips. */
+    resources?: readonly ActivityResourceRef[];
+    /** Free-form payload threaded through callbacks. */
+    data?: TData;
+    /** Override the visual marker for this row only. */
+    iconOverride?: LucideIcon;
+    toneOverride?: ActivityTone;
+}
+/** Per-event mass configuration entry. */
+export interface ActivityEventConfig {
+    /** Leading glyph. */
+    icon: LucideIcon;
+    /** Semantic tone driving the entry's colour. */
+    tone: ActivityTone;
+    /** Display label for the event. Defaults to `strings.events[event] || event`. */
+    label?: string;
+    /** Per-event source-badge override. */
+    sourceLabel?: string;
+}
+/** Mass-configurable event map. Merged on top of `defaultActivityEventConfig`. */
+export type ActivityEventConfigMap = Readonly<Record<string, ActivityEventConfig>>;
+/** Per-row action — renders into the inline action menu (rich density). */
+export interface ActivityAction<TData = unknown> {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ActivityTone;
+    onClick?: (activity: ActivityItem<TData>) => void;
+    /** Destination for the entry, when it navigates. */
+    href?: string;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /** Inline actions render under the row body; menu actions stay in the overflow menu. */
+    presentation?: 'inline' | 'menu';
+}
+/** Render-prop context handed to consumer-provided row renderers. */
+export interface ActivityRenderRowContext<TData = unknown> {
+    density: ActivityDensity;
+    isLast: boolean;
+    isFirstInGroup: boolean;
+    activity: ActivityItem<TData>;
+    eventConfig: ActivityEventConfig;
+    /** Semantic tone driving the entry's colour. */
+    tone: ActivityTone;
+    relativeTime: string | null;
+    absoluteTime: string | null;
+    sourceLabel: string | null;
+    expanded: boolean;
+    itemSpacing: ActivityItemSpacing;
+    setExpanded: (expanded: boolean) => void;
+    toggleExpanded: () => void;
+}
+/** Slot map — every consumer-overridable surface. */
+export interface ActivityFeedSlots<TData = unknown> {
+    /** Replace the whole row. */
+    renderRow?: (activity: ActivityItem<TData>, ctx: ActivityRenderRowContext<TData>) => ReactNode;
+    /** Replace the headline only. */
+    renderHeadline?: (activity: ActivityItem<TData>, ctx: ActivityRenderRowContext<TData>) => ReactNode;
+    /** Replace the marker (dot / icon). */
+    renderMarker?: (activity: ActivityItem<TData>, ctx: ActivityRenderRowContext<TData>) => ReactNode;
+    /** Add/replace row-specific detail content in the rich detail panel. */
+    renderDetails?: (activity: ActivityItem<TData>, ctx: ActivityRenderRowContext<TData>) => ReactNode;
+    /** Replace the date-group label. */
+    renderDateLabel?: (label: string, isFirst: boolean) => ReactNode;
+    /** Replace the empty state. */
+    empty?: ReactNode;
+    /** Replace the loading state. */
+    loading?: ReactNode;
+    /** Rendered above the first row (e.g. composer). */
+    header?: ReactNode;
+    /** Rendered below the last row. */
+    footer?: ReactNode;
+}
+/** Stable class composition seams for the canonical marker-rail row regions. */
+export type ActivityRowClassNameValue<TData = unknown> = string | ((activity: ActivityItem<TData>) => string | undefined);
+export interface ActivityRowClassNames<TData = unknown> {
+    row?: ActivityRowClassNameValue<TData>;
+    marker?: ActivityRowClassNameValue<TData>;
+    content?: ActivityRowClassNameValue<TData>;
+    details?: ActivityRowClassNameValue<TData>;
+}
+/** Accessor functions — consumer maps domain ↔ feature. */
+export interface ActivityFeedAccessors<TData = unknown> {
+    /** Format ISO → relative ("2 hours ago"). Defaults to `date-fns`. */
+    formatRelativeTime?: (iso: string) => string;
+    /** Format ISO → absolute. Defaults to date-fns with the configured locale. */
+    formatAbsoluteTime?: (iso: string) => string;
+    /** Format the date-group label. Defaults to today/yesterday/date-fns. */
+    formatDateGroupLabel?: (iso: string | null, strings: ActivitiesStrings) => string;
+    /** Resolve `event` → display label. Defaults to event-config / strings / event. */
+    getEventLabel?: (event: string) => string | undefined;
+    /** Resolve `source` → display label. Defaults to `strings.sources[source]`. */
+    getSourceLabel?: (source: string) => string | undefined;
+    /** Per-row action list. */
+    actionsForActivity?: (activity: ActivityItem<TData>) => readonly ActivityAction<TData>[] | undefined;
+}
+/** Callbacks fired by interactive surfaces. */
+export interface ActivityFeedCallbacks<TData = unknown> {
+    onActivityClick?: (activity: ActivityItem<TData>) => void;
+    onActorClick?: (actor: ActivityActor, activity: ActivityItem<TData>) => void;
+    onResourceClick?: (resource: ActivityResourceRef, config: ActivityResourceConfig | undefined, activity: ActivityItem<TData>) => void;
+    onAction?: (actionId: string, activity: ActivityItem<TData>) => void;
+    onActivityExpandedChange?: (activity: ActivityItem<TData>, expanded: boolean) => void;
+}
+/** Resource-registry inputs — wires save/restore. */
+export interface ActivityResourcesProps {
+    /** Initial registry contents. Treated as the seed each time identity changes. */
+    resources?: Readonly<Record<string, ActivityResourceConfig>>;
+    /** Fires whenever the registry changes — wire to localStorage / API. */
+    onResourcesChange?: (registry: Readonly<Record<string, ActivityResourceConfig>>) => void;
+}
+/** Top-level props. */
+export interface ActivityFeedProps<TData = unknown> extends ActivityFeedAccessors<TData>, ActivityFeedCallbacks<TData>, ActivityResourcesProps {
+    activities?: ReadonlyArray<ActivityItem<TData>>;
+    /** Density preset. Default `default`. */
+    density?: ActivityDensity;
+    /** Vertical row rhythm. Default `relaxed` for readable mixed comments/events. */
+    itemSpacing?: ActivityItemSpacing;
+    /** Group rows by date (Today / Yesterday / formatted). Default `true`. */
+    groupByDate?: boolean;
+    /** Auto-expand all change-detail blocks. Default `false`. */
+    expandedByDefault?: boolean;
+    /** Opt rich rows with detail panels into collapsible mode. */
+    detailsCollapsible?: boolean;
+    /** Initial expanded row ids for uncontrolled mode. */
+    defaultExpandedIds?: ReadonlyArray<string>;
+    /** Controlled expanded row ids. */
+    expandedIds?: ReadonlyArray<string>;
+    /** Controlled/uncontrolled expanded-id change callback. */
+    onExpandedIdsChange?: (ids: string[]) => void;
+    /** Authenticated user — enables "You" rendering on actor segments. */
+    currentUserId?: string;
+    /** Loading flag — switches to `slots.loading`. */
+    loading?: boolean;
+    /** Mass event configuration. Merged with `defaultActivityEventConfig`. */
+    eventConfig?: ActivityEventConfigMap;
+    /** String overrides (deep-partial). */
+    strings?: StringsProp<ActivitiesStrings>;
+    /** Slot overrides. */
+    slots?: ActivityFeedSlots<TData>;
+    /** Stable class composition seams for row, marker, content, and details regions. */
+    rowClassNames?: ActivityRowClassNames<TData>;
+    className?: string;
+    /** date-fns locale override. Falls back to `UIProvider.dates.locale`. */
+    locale?: Locale;
+}
+export interface ActivityLogCommentEntry<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> {
+    id: string;
+    kind: 'comment';
+    timestamp: string;
+    comment: CommentData<TUser, TMeta, TResource>;
+}
+export interface ActivityLogEventAction<TResource extends string = string> {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ActivityTone | 'destructive';
+    /** Destination for the entry, when it navigates. */
+    href?: string;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /** Inline actions render under the row body; menu actions stay in the overflow menu. */
+    presentation?: 'inline' | 'menu';
+    /** Fired when an entry is activated. */
+    onSelect?: (entry: ActivityLogActivityEntry<TResource>) => void;
+}
+export interface ActivityLogActivityEntry<TResource extends string = string> {
+    /** Stable identity for this entry. */
+    id: string;
+    kind: 'event' | 'system' | 'audit' | string;
+    /** Formatted time for the entry. */
+    timestamp: string;
+    event?: string;
+    /** Leading glyph. */
+    icon?: LucideIcon;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ActivityTone;
+    actor?: string | ActivityActor;
+    /** The action this surface performs. */
+    action?: string;
+    target?: ReactNode;
+    /** Display label. */
+    label?: ReactNode;
+    headline?: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    descriptionHtml?: string;
+    mentions?: ReadonlyArray<Mention<TResource>>;
+    /** Label/value facts rendered as a metadata list. */
+    metadata?: ReadonlyArray<{
+        label: string;
+        value: ReactNode;
+    }>;
+    changes?: ReadonlyArray<ActivityChange>;
+    details?: ReactNode;
+    collapsible?: boolean;
+    defaultExpanded?: boolean;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ReadonlyArray<ActivityLogEventAction<TResource>>;
+    /** Records to render. */
+    data?: unknown;
+}
+export type ActivityLogEntry<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> = ActivityLogCommentEntry<TUser, TMeta, TResource> | ActivityLogActivityEntry<TResource>;
+export interface ActivityLogEventRenderContext<TResource extends string = string> {
+    expanded: boolean;
+    setExpanded: (expanded: boolean) => void;
+    relativeTime: string | null;
+    isLast: boolean;
+    /** Mentionable resources offered in the composer. */
+    resources?: MentionsConfig<TResource>['resources'];
+}
+export type ActivityLogRenderer<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> = (entry: ActivityLogEntry<TUser, TMeta, TResource>, ctx: {
+    resources?: MentionsConfig<TResource>['resources'];
+    accessors?: CommentsAccessors;
+    strings?: StringsProp<CommentsStrings>;
+}) => ReactNode;
+export interface ActivityLogComposerConfig<TResource extends string = string> {
+    enabled: boolean;
+    position?: 'top' | 'bottom';
+    context: {
+        id: string;
+        type: string;
+        moduleKey?: string;
+    };
+    /** Fired when an entry is submitted. */
+    onSubmit?: NonNullable<CommentsConfig<CommentUser, unknown, TResource>['onSubmit']>;
+    /** Fires after the comment mutation settles successfully. */
+    onAfterMutate?: CommentsConfig<CommentUser, unknown, TResource>['onAfterMutate'];
+    /** Receives rejected composer mutations. */
+    onError?: CommentsConfig<CommentUser, unknown, TResource>['onError'];
+    placeholder?: string;
+    autoFocus?: boolean;
+    /** Render submit in the editor toolbar (`true`) or below the editor (`false`). ActivityLog defaults to `false`. */
+    inlineSubmit?: boolean;
+}
+export type ActivityLogClassNameValue<TResource extends string = string> = string | ((entry: ActivityLogActivityEntry<TResource>) => string | undefined);
+export interface ActivityLogClassNames<TResource extends string = string> {
+    list?: string;
+    eventRow?: ActivityLogClassNameValue<TResource>;
+    eventMarker?: ActivityLogClassNameValue<TResource>;
+    eventContent?: ActivityLogClassNameValue<TResource>;
+    eventDetails?: ActivityLogClassNameValue<TResource>;
+}
+export interface ActivityLogProps<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> extends CommentsAccessors {
+    /** Feed entries — activities and comments — to render. */
+    entries: ReadonlyArray<ActivityLogEntry<TUser, TMeta, TResource>>;
+    /** Chronological direction. `desc` puts the newest first. */
+    order?: 'asc' | 'desc';
+    /** Vertical row rhythm passed to the underlying activity feed. */
+    itemSpacing?: ActivityItemSpacing;
+    /** Mentionable resources offered in the composer. */
+    resources?: MentionsConfig<TResource>['resources'];
+    onResourceSearch?: MentionsConfig<TResource>['onResourceSearch'];
+    /** Whether the viewer may edit, delete, or pin others' comments. */
+    canModerate?: boolean;
+    onCommentDelete?: (commentId: string) => void;
+    onCommentReact?: (commentId: string, emoji: string) => void;
+    onCommentReply?: (commentId: string) => void;
+    onCommentPinToggle?: (comment: CommentData<TUser, TMeta, TResource>) => void;
+    strings?: StringsProp<CommentsStrings>;
+    /** Copy overrides for the activity entries, separate from the comment copy. */
+    activityStrings?: StringsProp<ActivitiesStrings>;
+    /** Custom renderers keyed by activity type, replacing the built-in ones. */
+    renderers?: Partial<Record<string, ActivityLogRenderer<TUser, TMeta, TResource>>>;
+    /** Replaces the expanded detail body of an activity entry. */
+    renderEventDetails?: (entry: ActivityLogActivityEntry<TResource>, ctx: ActivityLogEventRenderContext<TResource>) => ReactNode;
+    /** Lets activity entries expand to show their details. */
+    eventDetailsCollapsible?: boolean;
+    /** Entries expanded on first render. */
+    defaultExpandedIds?: ReadonlyArray<string>;
+    /** Ids of the expanded entries. Controlled. */
+    expandedIds?: ReadonlyArray<string>;
+    onExpandedIdsChange?: (ids: string[]) => void;
+    onEventExpandedChange?: (entry: ActivityLogActivityEntry<TResource>, expanded: boolean) => void;
+    onEventAction?: (actionId: string, entry: ActivityLogActivityEntry<TResource>) => void;
+    /** Class overrides for individual regions of the feed. */
+    classNames?: ActivityLogClassNames<TResource>;
+    /** Comment composer configuration. Omit to render the feed read-only. */
+    composer?: ActivityLogComposerConfig<TResource>;
+    /** Drops the card chrome so the feed sits directly on the page. */
+    bare?: boolean;
+    /** Surface title. */
+    title?: ReactNode;
+    /** Renders user avatars, letting the consumer supply its own component. */
+    avatarComponent?: ComponentType<{
+        user: TUser | undefined;
+        size: 'sm' | 'md' | 'lg';
+    }>;
+    className?: string;
+}
+export type ActivityLogSubmit<TResource extends string = string> = (values: CommentFormValues<TResource>, helpers: CommentSubmitHelpers) => void | Promise<void>;

package/dist/components/features/activities/activity-event-adapter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ActivityEventAdapter — map raw event-like records into ActivityLog entries.
+ *
+ * This is intentionally pure and framework-agnostic. Consumers pass accessors
+ * for their domain shape; the package returns the canonical ActivityLogEntry
+ * shape used by the timeline.
+ */
+import type { ActivityActor, ActivityChange, ActivityLogEntry, ActivityLogEventAction, ActivityTone } from './activities.types';
+import type { CommentData, CommentUser } from '../comments';
+import type { Mention } from '../mentions';
+import type { ReactNode } from 'react';
+export interface ActivityEventAdapterAccessors<TRaw, TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string> {
+    id: (record: TRaw) => string;
+    timestamp: (record: TRaw) => string;
+    kind?: (record: TRaw) => ActivityLogEntry<TUser, TMeta, TResource>['kind'];
+    event?: (record: TRaw) => string | undefined;
+    actor?: (record: TRaw) => string | ActivityActor | undefined;
+    title?: (record: TRaw) => ReactNode;
+    action?: (record: TRaw) => string | undefined;
+    target?: (record: TRaw) => ReactNode;
+    description?: (record: TRaw) => ReactNode;
+    descriptionHtml?: (record: TRaw) => string | undefined;
+    mentions?: (record: TRaw) => ReadonlyArray<Mention<TResource>> | undefined;
+    source?: (record: TRaw) => ReactNode;
+    status?: (record: TRaw) => ReactNode;
+    tone?: (record: TRaw) => ActivityTone | undefined;
+    metadata?: (record: TRaw) => ReadonlyArray<{
+        label: string;
+        value: ReactNode;
+    }> | undefined;
+    changes?: (record: TRaw) => readonly ActivityChange[] | undefined;
+    details?: (record: TRaw) => ReactNode;
+    rowActions?: (record: TRaw) => ReadonlyArray<ActivityLogEventAction<TResource>> | undefined;
+    comment?: (record: TRaw) => CommentData<TUser, TMeta, TResource> | undefined;
+    data?: (record: TRaw) => unknown;
+}
+export declare function toActivityLogEntry<TRaw, TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>(record: TRaw, accessors: ActivityEventAdapterAccessors<TRaw, TUser, TMeta, TResource>): ActivityLogEntry<TUser, TMeta, TResource>;
+export declare function createActivityEventAdapter<TRaw, TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>(accessors: ActivityEventAdapterAccessors<TRaw, TUser, TMeta, TResource>): (record: TRaw) => ActivityLogEntry<TUser, TMeta, TResource>;

package/dist/components/features/activities/activity-log.d.ts

@@ -0,0 +1,6 @@
+import { type CommentUser } from '../comments';
+import type { ActivityLogProps } from './activities.types';
+export declare function ActivityLog<TUser extends CommentUser = CommentUser, TMeta = unknown, TResource extends string = string>(props: ActivityLogProps<TUser, TMeta, TResource>): import("react").JSX.Element;
+export declare namespace ActivityLog {
+    var displayName: string;
+}

package/dist/components/features/activities/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useActivityFeed, type ActivityDateGroup, type ActivityKeyedItem, type UseActivityFeedOptions, type UseActivityFeedReturn, } from './use-activity-feed';
+export { useActivityResources, type ActivityResourceRegistry, type UseActivityResourcesOptions, type UseActivityResourcesReturn, } from './use-activity-resources';