Merge pull request #443 from GetStream/date-separator

feat: Add date separator component

Author: szuperaz

docusaurus/docs/Angular/components/MessageComponent.mdx

@@ -20,6 +20,8 @@ The `Message` component displays a message with additional information such as s
 
 The message list uses the `Message` component to display messages, if you want to replace that with your own custom component, you can do that by providing it to the [`CustomTemplatesService`](../services/CustomTemplatesService.mdx/#messagetemplate). It's also possible to just override parts of the message component.
 
+The `Message` component uses the [`DateParserService`](../services/DateParserService.mdx) to create user-friendly dates, you can override the date-parsing methods with your own functions.
+
 :::note
 
 If you want to build your own `Message` component, you might find the following building blocks useful:
@@ -40,10 +42,6 @@ The `Message` component uses the [`MessageReactions`](./MessageReactionsComponen
 
 The `Message` component uses the [`AttachmentList`](./AttachmentListComponent.mdx) component to display the attachments of the message.
 
-### User friendly dates
-
-The `Message` component uses the [`parseDate`](https://github.com/GetStream/stream-chat-angular/tree/master/projects/stream-chat-angular/src/lib/message/parse-date.ts) utility function to create user-friendly dates (for example _Yesterday at 8:15 AM_).
-
 ### Read by
 
 The `Message` component uses the [`listUsers`](https://github.com/GetStream/stream-chat-angular/tree/master/projects/stream-chat-angular/src/lib/list-users.ts) utility function to display the list of people who have read a particular message in a user friendly way (for example _Bob, Sophie, Jack, Rose, John and 1 more_).

docusaurus/docs/Angular/components/MessageListComponent.mdx

@@ -7,7 +7,19 @@ The `MessageList` displays messages using pagination, new messages are loaded wh
 
 ## Customization
 
-See [our customization guide](../concepts/customization.mdx) on how to provide your own message list component.
+### Custom message component
+
+If you want to customize how messages are displayed in the list, head over to the [`Message` component's page](../../components/MessageComponent/#customization).
+
+### Date separator
+
+- The component provides the [`displayDateSeparator`](#displaydateseparator) and [`dateSeparatorTextPos`](#dateseparatortextpos) inputs for configuring the date separator's behavior.
+- You can customize the displayed date format by providing your own [date parser](../../services/DateParserService/#customdateparser).
+- If you want to provide your own date separator UI, provide that to the [`CustomTemplatesService`](../../services/CustomTemplatesService/#dateseparatortemplate).
+
+### Custom message list
+
+The message list contains a lot of low-level logic related to scrolling, we don't advise to create your own message list component, however it's possible: see [our customization guide](../concepts/customization.mdx) on how to provide your own message list component.
 
 :::note
 If you want to create your own message list, you can use the [`ChannelService`](../services/ChannelService.mdx) to receive the necessary messages and interact with the Stream API.

package-lock.json

@@ -117,7 +117,7 @@
     "@ngx-translate/core": "^13.0.0",
     "@ngx-translate/http-loader": "^6.0.0",
     "@popperjs/core": "^2.11.5",
-    "@stream-io/stream-chat-css": "3.9.0",
+    "@stream-io/stream-chat-css": "3.10.1",
     "@stream-io/transliterate": "^1.5.2",
     "angular-mentions": "^1.4.0",
     "dayjs": "^1.10.7",

package.json

@@ -255,3 +255,7 @@
   />
   <button (click)="addRandomImage(attachmentService)">Random image</button>
 </ng-template>
+
+<ng-template #dateSeparator let-date="date" let-parsedDate="parsedDate">
+  {{ date }} - {{ parsedDate }}
+</ng-template>

projects/customizations-example/src/app/app.component.html

@@ -35,6 +35,7 @@ import {
   NotificationContext,
   ThreadHeaderContext,
   CustomAttachmentUploadContext,
+  DateSeparatorContext,
 } from 'stream-chat-angular';
 import { environment } from '../environments/environment';
 
@@ -88,6 +89,8 @@ export class AppComponent implements AfterViewInit {
   private chstomChannelInfoTemplate!: TemplateRef<ChannelHeaderInfoContext>;
   @ViewChild('customAttachmentUpload')
   private customAttachmentUploadTemplate!: TemplateRef<CustomAttachmentUploadContext>;
+  @ViewChild('dateSeparator')
+  private dateSeparatorTemplate!: TemplateRef<DateSeparatorContext>;
 
   constructor(
     private chatService: ChatClientService,
@@ -164,6 +167,9 @@ export class AppComponent implements AfterViewInit {
     this.customTemplatesService.customAttachmentUploadTemplate$.next(
       this.customAttachmentUploadTemplate
     );
+    this.customTemplatesService.dateSeparatorTemplate$.next(
+      this.dateSeparatorTemplate
+    );
   }
 
   inviteClicked(channel: Channel) {

projects/customizations-example/src/app/app.component.ts

@@ -10,6 +10,7 @@ import {
   ChannelPreviewContext,
   CommandAutocompleteListItemContext,
   CustomAttachmentUploadContext,
+  DateSeparatorContext,
   DeliveredStatusContext,
   EmojiPickerContext,
   IconContext,
@@ -279,6 +280,12 @@ export class CustomTemplatesService {
   systemMessageTemplate$ = new BehaviorSubject<
     TemplateRef<SystemMessageContext> | undefined
   >(undefined);
+  /**
+   * The template used to display the date separator inside the [message list](../components/MessageListComponent.mdx)
+   */
+  dateSeparatorTemplate$ = new BehaviorSubject<
+    TemplateRef<DateSeparatorContext> | undefined
+  >(undefined);
 
   constructor() {}
 }

projects/stream-chat-angular/src/lib/custom-templates.service.ts

@@ -0,0 +1,48 @@
+import { TestBed } from '@angular/core/testing';
+
+import { DateParserService } from './date-parser.service';
+
+describe('DateParserService', () => {
+  let service: DateParserService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({});
+    service = TestBed.inject(DateParserService);
+  });
+
+  it('should be created', () => {
+    expect(service).toBeTruthy();
+  });
+
+  it('should parse date', () => {
+    const date = new Date(2023, 7, 2);
+
+    expect(service.parseDate(date)).toEqual('02/08/2023');
+  });
+
+  it('should parse date-time', () => {
+    const date = new Date();
+
+    expect(service.parseDateTime(date)).toContain('Today at');
+  });
+
+  it('should call custom date parser', () => {
+    const date = new Date(2023, 7, 2);
+    const spy = jasmine.createSpy();
+    service.customDateParser = spy;
+
+    service.parseDate(date);
+
+    expect(spy).toHaveBeenCalledWith(date);
+  });
+
+  it('should call custom date-time', () => {
+    const date = new Date(2023, 7, 2);
+    const spy = jasmine.createSpy();
+    service.customDateTimeParser = spy;
+
+    service.parseDateTime(date);
+
+    expect(spy).toHaveBeenCalledWith(date);
+  });
+});

projects/stream-chat-angular/src/lib/date-parser.service.spec.ts

@@ -0,0 +1,45 @@
+import { Injectable } from '@angular/core';
+import { parseDate } from './parse-date';
+
+/**
+ * The `DateParserService` parses dates into user-friendly string representations.
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class DateParserService {
+  /**
+   * Custom parser to override `parseDate`
+   */
+  customDateParser?: (date: Date) => string;
+  /**
+   * Custom parser to override `parseDateTime`
+   */
+  customDateTimeParser?: (date: Date) => string;
+
+  constructor() {}
+
+  /**
+   * Return a user-friendly string representation of the date (year, month and date)
+   * @param date
+   * @returns
+   */
+  parseDate(date: Date) {
+    if (this.customDateParser) {
+      return this.customDateParser(date);
+    }
+    return parseDate(date, 'date');
+  }
+
+  /**
+   * Return a user-friendly string representation of the date and time
+   * @param date
+   * @returns
+   */
+  parseDateTime(date: Date) {
+    if (this.customDateTimeParser) {
+      return this.customDateTimeParser(date);
+    }
+    return parseDate(date, 'date-time');
+  }
+}

projects/stream-chat-angular/src/lib/date-parser.service.ts

@@ -32,24 +32,52 @@
         data-testid="top-loading-indicator"
         *ngIf="isLoading && direction === 'bottom-to-top'"
       ></stream-loading-indicator>
-      <li
-        tabindex="0"
-        data-testclass="message"
-        *ngFor="
-          let message of messages$ | async;
-          let i = index;
-          trackBy: trackByMessageId
-        "
-        class="str-chat__li str-chat__li--{{ groupStyles[i] }}"
-        id="{{ message.id }}"
-      >
+      <ng-container *ngIf="messages$ | async as messages">
         <ng-container
-          *ngTemplateOutlet="
-            messageTemplateContainer;
-            context: { message: message, index: i }
+          *ngFor="
+            let message of messages;
+            let i = index;
+            let isFirst = first;
+            trackBy: trackByMessageId
           "
-        ></ng-container>
-      </li>
+        >
+          <ng-container *ngIf="isFirst">
+            <ng-container
+              *ngTemplateOutlet="
+                dateSeparator;
+                context: {
+                  date: message.created_at,
+                  parsedDate: parseDate(message.created_at)
+                }
+              "
+            ></ng-container>
+          </ng-container>
+          <li
+            tabindex="0"
+            data-testclass="message"
+            class="str-chat__li str-chat__li--{{ groupStyles[i] }}"
+            id="{{ message.id }}"
+          >
+            <ng-container
+              *ngTemplateOutlet="
+                messageTemplateContainer;
+                context: { message: message, index: i }
+              "
+            ></ng-container>
+          </li>
+          <ng-container *ngIf="areOnSeparateDates(message, messages[i + 1])">
+            <ng-container
+              *ngTemplateOutlet="
+                dateSeparator;
+                context: {
+                  date: messages[i + 1].created_at,
+                  parsedDate: parseDate(messages[i + 1].created_at)
+                }
+              "
+            ></ng-container>
+          </ng-container>
+        </ng-container>
+      </ng-container>
       <stream-loading-indicator
         data-testid="bottom-loading-indicator"
         *ngIf="isLoading && direction === 'top-to-bottom'"
@@ -158,3 +186,38 @@
     "
   ></ng-container>
 </ng-template>
+
+<ng-template #dateSeparator let-date="date" let-parsedDate="parsedDate">
+  <ng-container *ngIf="displayDateSeparator">
+    <ng-container
+      *ngTemplateOutlet="
+        customDateSeparatorTemplate || defaultDateSeparator;
+        context: { date: date, parsedDate: parsedDate }
+      "
+    ></ng-container>
+  </ng-container>
+
+  <ng-template
+    #defaultDateSeparator
+    let-date="date"
+    let-parsedDate="parsedDate"
+  >
+    <div data-testid="date-separator" class="str-chat__date-separator">
+      <hr
+        *ngIf="
+          dateSeparatorTextPos === 'right' || dateSeparatorTextPos === 'center'
+        "
+        class="str-chat__date-separator-line"
+      />
+      <div class="str-chat__date-separator-date">
+        {{ parsedDate }}
+      </div>
+      <hr
+        *ngIf="
+          dateSeparatorTextPos === 'left' || dateSeparatorTextPos === 'center'
+        "
+        class="str-chat__date-separator-line"
+      />
+    </div>
+  </ng-template>
+</ng-template>