@molecule/app-activity-feed-angular

Feature · activity-feed · App (browser) · v1.1.0 · Apache-2.0

Angular activity feed rows and date-grouped feed container

npm install @molecule/app-activity-feed-angular

npm · Source on GitHub

How it works

@molecule/app-activity-feed-angular is a ready-made activity-feed feature for the app (browser) side. It composes the core interfaces it needs, so it works with whichever providers your app has bonded.

import { Component } from '@angular/core'
import {
  ActivityFeed,
  ActivityFeedGroup,
  ActivityFeedItem,
} from '@molecule/app-activity-feed-angular'

@Component({
  selector: 'app-activity',
  standalone: true,
  imports: [ActivityFeed, ActivityFeedGroup, ActivityFeedItem],
  template: `
    <mol-activity-feed [items]="items">
      <p slot="emptyState">No activity yet.</p>
    </mol-activity-feed>

    <section mol-activity-feed-group heading="Today" [items]="items"></section>
  `,
})
export class Activity {
  items = [
    { id: '1', actor: 'Alice', verb: 'commented on', target: 'PR #42', timestamp: '2m ago' },
    { id: '2', actor: 'Bob', verb: 'closed', target: 'Issue #7', timestamp: '1h ago' },
  ]
}

Works with: @molecule/app-angular, @molecule/app-ui, @molecule/app-ui-angular

Reference

Angular activity-feed primitives — the counterpart of @molecule/app-activity-feed-react: the same props (React names) and the same DOM for the same input.

Exports:

  • <mol-activity-feed> — flat vertical list of activity rows.
  • <article mol-activity-feed-item> — single row (avatar + actor/verb/target + timestamp + body).
  • <section mol-activity-feed-group> — heading + list, compose multiple for "Today / Yesterday" feeds.
  • ActivityFeedItemData type for row data.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { Component } from '@angular/core'
import {
  ActivityFeed,
  ActivityFeedGroup,
  ActivityFeedItem,
} from '@molecule/app-activity-feed-angular'

@Component({
  selector: 'app-activity',
  standalone: true,
  imports: [ActivityFeed, ActivityFeedGroup, ActivityFeedItem],
  template: `
    <mol-activity-feed [items]="items">
      <p slot="emptyState">No activity yet.</p>
    </mol-activity-feed>

    <section mol-activity-feed-group heading="Today" [items]="items"></section>
  `,
})
export class Activity {
  items = [
    { id: '1', actor: 'Alice', verb: 'commented on', target: 'PR #42', timestamp: '2m ago' },
    { id: '2', actor: 'Bob', verb: 'closed', target: 'Issue #7', timestamp: '1h ago' },
  ]
}

Type

feature

Installation

npm install @molecule/app-activity-feed-angular @angular/common @angular/core @angular/platform-browser @molecule/app-angular @molecule/app-ui @molecule/app-ui-angular

API

Interfaces

ActivityFeedItemData

Per-row activity data.

interface ActivityFeedItemData {
  /** Row id (the render key). */
  id: string
  /** Actor avatar source URL. */
  avatarSrc?: string
  /** Actor display name. */
  actor: string | number | TemplateRef<unknown>
  /** Verb describing the action ("commented on", "assigned", "completed"). */
  verb: string | number | TemplateRef<unknown>
  /** Object of the action ("the ticket", "Project Alpha", etc.). */
  target?: string | number | TemplateRef<unknown>
  /** Optional supporting body (quote, diff, preview). */
  body?: string | number | TemplateRef<unknown>
  /** ISO timestamp or any node to render as "time ago". */
  timestamp: string | number | TemplateRef<unknown>
  /** Optional leading icon (replaces avatar when present). */
  icon?: string | number | TemplateRef<unknown>
}

ActivityFeedProps

Props accepted by ActivityFeed — the same props @molecule/app-activity-feed-react accepts. Node props (emptyState, footer) are projected content in Angular (an input cannot carry a node), or a template reference passed as an input: [slot=emptyState] / [slot=footer].

interface ActivityFeedProps {
  /** Items in display order (usually most-recent first). */
  items: ActivityFeedItemData[]
  /** Rendered when `items` is empty: `[slot=emptyState]` content or a template input. */
  emptyState?: unknown
  /** Optional footer (e.g. "Load more"): `[slot=footer]` content or a template input. */
  footer?: unknown
  /** Extra classes. */
  className?: string
}

ActivityFeedItemProps

Props accepted by ActivityFeedItem.

interface ActivityFeedItemProps {
  /** The row to render. */
  item: ActivityFeedItemData
  /** Extra classes on the row wrapper. */
  className?: string
}

ActivityFeedGroupProps

Props accepted by ActivityFeedGroup — the same props @molecule/app-activity-feed-react accepts. The heading is text, a template reference, or [slot=heading] projected content.

interface ActivityFeedGroupProps {
  /** Group heading — typically a formatted date ("Today", "Yesterday", "Mar 12"). */
  heading?: string | number | TemplateRef<unknown>
  /** Items in this group. */
  items: ActivityFeedItemData[]
  /** Extra classes. */
  className?: string
}

Classes

ActivityFeedGroup

ActivityFeedGroup component.

Date-grouped activity section — a heading followed by a stack of items. Compose multiple groups together for an organized "Today / Yesterday / Last week" feed. The host IS the root <section> (section[mol-activity-feed-group]), matching React's root exactly. The heading is plain text, a template reference, or [slot=heading] projected content.

@Component({
  selector: 'section[mol-activity-feed-group]',
  standalone: true,
  imports: [NgTemplateOutlet, ActivityFeedItem],
  inputs: ['heading', 'items', 'className'],
  host: {
    '[class]': 'classes()',
  },
  // prettier-ignore
  template: `<h3 [class]="headingClasses()">@if (headingTemplate(); as headingTpl) {<ng-container [ngTemplateOutlet]="headingTpl"></ng-container>}@else if (hasTextHeading()) {<ng-container>{{ heading }}</ng-container>}<ng-content select="[slot=heading]"></ng-content></h3><div [class]="listClasses()">@for (item of items; track item.id) {<article mol-activity-feed-item [item]="item"></article>}</div>`,
})
export class ActivityFeedGroup {
  /** Group heading — typically a formatted date ("Today", "Yesterday", "Mar 12"). */
  heading?: string | number | TemplateRef<unknown>
  /** Items in this group. */
  items: ActivityFeedItemData[] = []
  /** Extra classes. */
  className?: string

  /**
   * The current class map.
   * @returns The UIClassMap.
   */
  cm(): UIClassMap {
    return getClassMap()
  }

  /**
   * Computes the section's class list (`cm.stack(3)` + `className`).
   * @returns The class string.
   */
  classes(): string {
    return this.cm().cn(this.cm().stack(3), this.className)
  }

  /**
   * Computes the heading's class list (`cm.textSize('xs')` +
   * `cm.fontWeight('semibold')`).
   * @returns The class string.
   */
  headingClasses(): string {
    return this.cm().cn(this.cm().textSize('xs'), this.cm().fontWeight('semibold'))
  }

  /**
   * Computes the rows wrapper's class (`cm.stack(4)`).
   * @returns The class string.
   */
  listClasses(): string {
    return this.cm().cn(this.cm().stack(4))
  }

  /**
   * The heading as an input template (a node passed as a prop rather than
   * projected as `[slot=heading]`), when there is one.
   * @returns The heading template, or null.
   */
  headingTemplate(): TemplateRef<unknown> | null {
    return this.heading instanceof TemplateRef ? this.heading : null
  }

  /**
   * Whether the heading input itself carries text (React's `{heading}` for a
   * string child; a node arrives as `[slot=heading]` content instead).
   * @returns True for a string or number heading.
   */
  hasTextHeading(): boolean {
    return typeof this.heading === 'string' || typeof this.heading === 'number'
  }
}

ActivityFeedItem

ActivityFeedItem component.

One entry in an activity feed. Shape: [avatar|icon] [actor verb target · timestamp] [body]. The host IS the row <article> (article[mol-activity-feed-item]), matching React's root exactly. The leading column renders the item's icon when supplied, otherwise a <div mol-avatar> for avatarSrc, otherwise nothing — React's icon ?? (avatarSrc ? … : null). Node-valued fields are ng-template references rendered through NgTemplateOutlet; string / number fields render as text.

@Component({
  selector: 'article[mol-activity-feed-item]',
  standalone: true,
  imports: [NgTemplateOutlet, Avatar],
  inputs: ['item', 'className'],
  host: {
    '[class]': 'classes()',
  },
  // The template's whitespace is semantic: Angular keeps whitespace-only text
  // nodes between inline elements, so the line's content is glued and the
  // single spaces React renders around the verb are explicit interpolations.
  // prettier-ignore
  template: `<div [class]="leadingClasses()">@if (item.icon != null) {@if (isNode(item.icon)) {<ng-container [ngTemplateOutlet]="templateOf(item.icon)"></ng-container>}@else {{{ textOf(item.icon) }}}}@else if (item.avatarSrc) {<div mol-avatar [src]="item.avatarSrc" [size]="avatarSize()"></div>}</div><div [class]="bodyClasses()"><div [class]="lineClasses()"><span [class]="cm().fontWeight('semibold')">@if (isNode(item.actor)) {<ng-container [ngTemplateOutlet]="templateOf(item.actor)"></ng-container>}@else {{{ textOf(item.actor) }}}</span>@if (isNode(item.verb)) {{{ ' ' }}<ng-container [ngTemplateOutlet]="templateOf(item.verb)"></ng-container>{{ ' ' }}}@else {{{ ' ' + textOf(item.verb) + ' ' }}}@if (item.target) {<span [class]="cm().fontWeight('medium')">@if (isNode(item.target)) {<ng-container [ngTemplateOutlet]="templateOf(item.target)"></ng-container>}@else {{{ textOf(item.target) }}}</span>}<span [class]="timeClasses()">@if (isNode(item.timestamp)) {{{ ' · ' }}<ng-container [ngTemplateOutlet]="templateOf(item.timestamp)"></ng-container>}@else {{{ ' · ' + textOf(item.timestamp) }}}</span></div>@if (item.body) {<div [class]="bodyTextClasses()">@if (isNode(item.body)) {<ng-container [ngTemplateOutlet]="templateOf(item.body)"></ng-container>}@else {{{ textOf(item.body) }}}</div>}</div>`,
})
export class ActivityFeedItem {
  /** The row to render (required, as in React's props). */
  item!: ActivityFeedItemProps['item']
  /** Extra classes on the row wrapper. */
  className?: string

  /**
   * The current class map.
   * @returns The UIClassMap.
   */
  cm(): UIClassMap {
    return getClassMap()
  }

  /**
   * Computes the row's class list (`cm.flex({ align: 'start', gap: 'sm' })` +
   * `className`).
   * @returns The class string.
   */
  classes(): string {
    return this.cm().cn(this.cm().flex({ align: 'start', gap: 'sm' }), this.className)
  }

  /**
   * Computes the leading column's class (`cm.shrink0`).
   * @returns The class string.
   */
  leadingClasses(): string {
    return this.cm().cn(this.cm().shrink0)
  }

  /**
   * Computes the body block's class (`cm.textSize('sm')`).
   * @returns The class string.
   */
  bodyTextClasses(): string {
    return this.cm().cn(this.cm().textSize('sm'))
  }

  /**
   * Computes the actor/body column's class list (`cm.flex1` + `cm.stack(1)`).
   * @returns The class string.
   */
  bodyClasses(): string {
    return this.cm().cn(this.cm().flex1, this.cm().stack(1))
  }

  /**
   * Computes the first line's class (`cm.textSize('sm')`).
   * @returns The class string.
   */
  lineClasses(): string {
    return this.cm().cn(this.cm().textSize('sm'))
  }

  /**
   * The timestamp span's class (`cm.sp('ml', 2)` + `cm.textSize('xs')`).
   * @returns The class string.
   */
  timeClasses(): string {
    return this.cm().cn(this.cm().sp('ml', 2), this.cm().textSize('xs'))
  }

  /**
   * The avatar size passed to `<div mol-avatar>` (React's `size="sm"`).
   * @returns The size preset.
   */
  avatarSize(): 'sm' {
    return 'sm'
  }

  /**
   * Whether a field holds a node (an `ng-template` reference) rather than text.
   * @param value - The row field.
   * @returns True when it renders through a template outlet.
   */
  isNode(value: unknown): value is TemplateRef<unknown> {
    return value instanceof TemplateRef
  }

  /**
   * Narrows a value to an embedded template.
   * @param value - A row field.
   * @returns The template, or null.
   */
  templateOf(value: unknown): TemplateRef<unknown> | null {
    return value instanceof TemplateRef ? value : null
  }

  /**
   * The text a field renders (React renders strings and numbers as text).
   * @param value - The row field.
   * @returns The text, or `''` for a node field.
   */
  textOf(value: unknown): string {
    return typeof value === 'string' || typeof value === 'number' ? String(value) : ''
  }
}

ActivityFeed

ActivityFeed component.

Simple activity feed — renders each item via <ActivityFeedItem> and stacks them. React's root is the <div> when it has something to render and the bare emptyState when the list is empty, so the host is unwrapped (data-parity-unwrap, display: contents) and the <div> is rendered inside it. The empty state and the footer are projected content ([slot=emptyState] / [slot=footer]) or template inputs, reconciled by ActivityFeed.ngAfterViewInit / ActivityFeed.ngAfterViewChecked / ActivityFeed.ngDoCheck against React's branch.

For date-grouped feeds use ActivityFeedGroup.

@Component({
  selector: 'mol-activity-feed',
  standalone: true,
  imports: [NgTemplateOutlet, ActivityFeedItem],
  inputs: ['items', 'emptyState', 'footer', 'className'],
  host: {
    'data-parity-unwrap': '',
    style: 'display: contents',
  },
  // prettier-ignore
  template: `<span #empty data-parity-unwrap style="display: contents">@if (emptyTemplate(); as emptyTpl) {<ng-container [ngTemplateOutlet]="emptyTpl"></ng-container>}<ng-content select="[slot=emptyState]"></ng-content></span><div #list [class]="listClasses()">@for (item of items; track item.id) {<article mol-activity-feed-item [item]="item"></article>}@if (footerTemplate(); as footerTpl) {<ng-container [ngTemplateOutlet]="footerTpl"></ng-container>}<ng-content select="[slot=footer]"></ng-content></div>`,
})
export class ActivityFeed implements AfterViewInit, AfterViewChecked, DoCheck {
  /** Items in display order (usually most-recent first). */
  items: ActivityFeedItemData[] = []

  /** Empty-state content, as an input (a template reference from a props change). */
  emptyState?: unknown

  /** Footer content, as an input (a template reference from a props change). */
  footer?: unknown

  /** Extra classes on the outer wrapper. */
  className?: string

  /** The projected empty-state capture point (unwrapped, so React's bare slot). */
  @ViewChild('empty') private empty?: ElementRef<HTMLElement>

  /** The feed wrapper (detached when the empty state renders instead). */
  @ViewChild('list') private list?: ElementRef<HTMLElement>

  private readonly guard = new SlotGuard(inject(ElementRef), inject(Renderer2))

  /**
   * The current class map.
   * @returns The UIClassMap.
   */
  cm(): UIClassMap {
    return getClassMap()
  }

  /**
   * Computes the wrapper class list (`cm.stack(4)` + `className`).
   * @returns The class string.
   */
  listClasses(): string {
    return this.cm().cn(this.cm().stack(4), this.className)
  }

  /**
   * The empty state as an input template (a node passed as a prop rather than
   * projected as `[slot=emptyState]`), when there is one.
   * @returns The empty-state template, or null.
   */
  emptyTemplate(): TemplateRef<unknown> | null {
    return this.emptyState instanceof TemplateRef ? this.emptyState : null
  }

  /**
   * The footer as an input template (a node passed as a prop rather than
   * projected as `[slot=footer]`), when there is one.
   * @returns The footer template, or null.
   */
  footerTemplate(): TemplateRef<unknown> | null {
    return this.footer instanceof TemplateRef ? this.footer : null
  }

  /**
   * Reconciles the projected empty state and the feed wrapper against React's
   * branch once the view queries resolve.
   */
  ngAfterViewInit(): void {
    this.reconcile()
  }

  /**
   * Re-reconciles on later passes, so a props step that empties or refills the
   * list swaps the branch the way React does.
   */
  ngDoCheck(): void {
    this.reconcile()
  }

  /**
   * Re-reconciles after each view update: a node-valued empty state that arrives
   * through an input renders into its outlet only during the update, so the
   * branch decision must be read afterwards.
   */
  ngAfterViewChecked(): void {
    this.reconcile()
  }

  /**
   * Applies React's condition: with no items and an empty state, the empty state
   * renders bare and the feed wrapper disappears; otherwise the wrapper renders
   * and the empty state is dropped.
   */
  private reconcile(): void {
    const empty = this.empty?.nativeElement
    const list = this.list?.nativeElement
    const hasEmpty = (this.items?.length ?? 0) === 0 && hasNodes(empty)
    this.guard.toggle(empty, hasEmpty)
    this.guard.toggle(list, !hasEmpty)
  }
}

Injection Notes

Requirements

Peer dependencies:

  • @angular/common ^22.0.0
  • @angular/core ^22.0.0
  • @angular/platform-browser ^22.0.0
  • @molecule/app-angular ^3.5.0
  • @molecule/app-ui ^1.0.1
  • @molecule/app-ui-angular ^1.1.0

Runtime Dependencies

  • @angular/common

  • @angular/core

  • @angular/platform-browser

  • @molecule/app-angular

  • @molecule/app-ui

  • @molecule/app-ui-angular

  • Requires a bonded ClassMap (getClassMap()); rendering throws otherwise.

  • ActivityFeed's root is the wrapper <div> — or the bare empty state when the list is empty — so its host is display: contents.

  • Node props are projected content: [slot=emptyState], [slot=footer], [slot=heading]; a row's node fields are template references.