@stack-spot/portal-components 2.0.3 → 2.1.0

package/src/components/{Notifications → notification}/NotificationItem.tsx

@@ -24,6 +24,7 @@ const statusToColor: Record<string, OneOfColorSchemesWithVariants> = {
 interface Props {
   notification: StackspotNotification,
   isSummary: boolean,
+  // @deprecated this property currently does nothing. Remove in next major.
   id?: string,
 }
 
@@ -38,12 +39,12 @@ const style: Styles = {
 /**
  * NotificationHeader component that renders the header of a notification.
  *
- * @param props the component's props {@link NotificationItemProps}.
+ * @param props the component's props.
  */
-const NotificationHeader = ({ notification, isSummary }: NotificationItemProps) => (
+const NotificationHeader = ({ title, isSummary }: { title: string, isSummary: boolean }) => (
   <Flex justifyContent="space-between" mb={2} sx={{ maxWidth: isSummary ? '330px' : '100%' }} flexWrap="nowrap">
     <Text appearance={isSummary ? 'body2' : 'body1'} nowrapEllipsis>
-      {notification.title}
+      {title}
     </Text>
   </Flex>
 )
@@ -99,9 +100,15 @@ const NotificationContent = ({ notification, isSummary }: Props) => {
   )
 }
 
-interface NotificationFooterProps  { 
-  call_to_action: string, 
-  onClickMarkReadUnread: (type: 'callToAction' | 'icon') => void,
+interface NotificationFooterProps  {
+  /**
+   * The URL to open when the action button is clicked.
+   */
+  actionURL: string,
+  /**
+   * Function to call when the user clicks the action button.
+   */
+  onClickAction: () => void,
 }
 
 /**
@@ -109,7 +116,7 @@ interface NotificationFooterProps  {
  *
  * @param props the component's props {@link NotificationFooterProps}.
  */
-const NotificationFooter = ({ call_to_action, onClickMarkReadUnread }: NotificationFooterProps) => {
+const NotificationFooter = ({ actionURL, onClickAction }: NotificationFooterProps) => {
   const t = useTranslate(dictionary)
   const Link = useAnchorTag()
   
@@ -118,9 +125,9 @@ const NotificationFooter = ({ call_to_action, onClickMarkReadUnread }: Notificat
       <Button
         size="sm"
         colorScheme="inverse"
-        onClick={() => onClickMarkReadUnread('callToAction')}
+        onClick={onClickAction}
         as={Link}
-        href={call_to_action}
+        href={actionURL}
         aria-label={t.takeMeThere}
       >
         <Text colorScheme="inverse.contrastText">
@@ -131,41 +138,76 @@ const NotificationFooter = ({ call_to_action, onClickMarkReadUnread }: Notificat
   )
 }
 
-interface NotificationItemProps extends Props {
-  onClickMarkReadUnread: (read: boolean, type: 'callToAction' | 'icon') => void,
+interface DeprecatedNotificationItemProps extends Props {
+  /**
+   * @deprecated use `onCommit` and `onClickAction` instead.
+   * 
+   * Function to call when the user marks a notification as read or unread. This can happen either through the mail icon or when the user
+   * clicks the action button of a notification. Type will be "icon" on the first case or "callToAction" on the former.
+   * 
+   * Tip: clicking the action button (callToAction) should only change the read status if the message is unread. This is not treated by this
+   * component, be sure to handle it on your side.
+   * 
+   * Deprecation warning: since the deprecation, the parameter `read` is always true.
+   */
+  onClickMarkReadUnread: (read: boolean, type: 'callToAction' | 'icon') => void | Promise<void>,
+}
+
+interface NewNotificationItemProps extends Props {
+  /**
+   * Function to call when the user marks a notification as read (committed).
+   */
+  onCommit: () => void,
+  /**
+   * Whenever the user clicks the action button of a notification, the notification is marked as read (committed) and the browser is
+   * redirected to the page that corresponds to the action.
+   * 
+   * If you need additional behavior, use this parameter, which is a function to call whenever the button is clicked.
+   */
+  onClickAction?: () => void,
 }
 
+type NotificationItemProps = DeprecatedNotificationItemProps | NewNotificationItemProps
+
 /**
  * NotificationItem component that renders a notification item.
  *
  * @param props the component's props {@link NotificationItemProps}.
  */
-export const NotificationItem = ({ notification, isSummary, onClickMarkReadUnread, id }: NotificationItemProps) => {
+export const NotificationItem = ({ notification, isSummary, ...props }: NotificationItemProps) => {
   const t = useTranslate(dictionary)
+
+  function commit() {
+    if ('onCommit' in props) props.onCommit()
+    else props.onClickMarkReadUnread(true, 'icon')
+  }
+
+  function clickAction() {
+    if ('onCommit' in props) {
+      if (!notification.committed) props.onCommit()
+      props.onClickAction?.()
+    }
+    else props.onClickMarkReadUnread(true, 'callToAction')
+  }
+  
   return (
-    <Box sx={{ position: 'relative' }} id={id}>
+    <Box sx={{ position: 'relative' }}>
       <Flex bg="light.400" p="3 3 3 5" r="xs"
         flexDirection="column" w="100%" sx={styles.item(statusToColor[notification.criticality], notification.committed)}>
-        <NotificationHeader notification={notification} isSummary={isSummary} onClickMarkReadUnread={onClickMarkReadUnread}/>
+        <NotificationHeader title={notification.title} isSummary={isSummary} />
         <NotificationContent notification={notification} isSummary={isSummary} />
-        {notification.call_to_action && <NotificationFooter call_to_action={notification.call_to_action} 
-          onClickMarkReadUnread={(type) => onClickMarkReadUnread(notification.committed, type)} />}
+        {notification.call_to_action && <NotificationFooter actionURL={notification.call_to_action} onClickAction={clickAction} />}
       </Flex>
       <Box sx={{ position: 'absolute', top: '8px', right: '8px' }}>
-        <Tooltip text={notification.committed ? t.markAsUnread : t.markAsRead} position="left" 
-          id={`tooltip-${notification.title}`} role="tooltip"
-          sx={style.tooltip}>
-          <IconButton aria-describedby={`tooltip-${notification.title}`}
-            aria-live="polite"
-            aria-label={notification.committed ? t.markAsUnread : t.markAsRead}
-            sx={{ opacity: notification.committed ? 0.5 : 1 }}
-            onClick={() => {
-              onClickMarkReadUnread(notification.committed, 'icon')
-            }}> 
-            <IconBox size="xs">
-              {notification.committed ? <Envelope /> : <EnvelopeOpen />}
-            </IconBox>
-          </IconButton>
+        <Tooltip text={notification.committed ? t.committed : t.uncommitted} position="left" sx={style.tooltip}>
+          {notification.committed
+            ? <IconBox role="img" aria-label={t.committed} size="xs" style={{ margin: '4px', opacity: 0.5 }}><EnvelopeOpen /></IconBox>
+            : (
+              <IconButton aria-label={t.uncommitted} onClick={commit}> 
+                <IconBox size="xs"><Envelope /></IconBox>
+              </IconButton>
+            )
+          }
         </Tooltip>
       </Box>
     </Box>
@@ -180,8 +222,8 @@ const dictionary = {
     STUDIO: 'Studio',
     daysAgo: 'days ago',
     today: 'today',
-    markAsRead: 'Mark as read',
-    markAsUnread: 'Mark as unread',
+    committed: 'This notification has been read.',
+    uncommitted: 'This notification has not been read yet. Click to mark as read.',
   },
   pt: {
     takeMeThere: 'Leve-me para lá',
@@ -190,7 +232,7 @@ const dictionary = {
     STUDIO: 'Estúdio',
     daysAgo: 'dias atrás',
     today: 'hoje',
-    markAsRead: 'Marcar como lido',
-    markAsUnread: 'Marcar como não lido',
+    committed: 'Esta notificação já foi lida.',
+    uncommitted: 'Esta notificação ainda não foi lida. Clique para marcar como lida.',
   },
 } satisfies Dictionary

package/src/components/notification/NotificationList.tsx

@@ -0,0 +1,167 @@
+import { Box, Flex } from '@citric/core'
+import { listToClass } from '@stack-spot/portal-theme'
+import { Month } from '@stack-spot/portal-translate'
+import { last } from 'lodash'
+import { useMemo } from 'react'
+import { styled } from 'styled-components'
+import { InfiniteScroll } from '../InfiniteScroll'
+import { TimelineSection } from '../TimelineSection'
+import { NotificationItem } from './NotificationItem'
+import { NotificationPlaceholder } from './NotificationPlaceholder'
+import { InfiniteScrollConfig, StackspotNotification } from './types'
+
+export interface NotificationListProps {
+  /**
+   * Function to call when the message is marked as read (committed).
+   * @param id the id of the notification where the read status changed.
+   */
+  onCommit: (id: string) => void,
+  /**
+   * Optional. Function called when the button to perform the notification action is clicked. This function will be run in addition to
+   * the notification action.
+   * @param id the id of the notification where the button was clicked
+   */
+  onClickAction?: (id: string) => void,
+  /**
+   * If you need this notification list to be have an infinite scroll behavior, set this option.
+   */
+  infiniteScroll?: InfiniteScrollConfig,
+  /**
+   * The notifications themselves.
+   */
+  items: StackspotNotification[],
+  /**
+   * A compact notification list don't show date headers (as a timeline) or descriptions of notifications.
+   */
+  compact?: boolean,
+  /**
+   * Whether or not the content is loading. If this is true, the content becomes transparent and the cursor turns into the progress cursor.
+   */
+  loading?: boolean,
+  /**
+   * If true, when the list is empty, the placeholder will say "nothing found" instead of "no notifications".
+   */
+  showEmptySearch?: boolean,
+  style?: React.CSSProperties,
+  className?: string,
+}
+
+interface NotificationGroup {
+  month: Month,
+  day: number,
+  year: number,
+  items: StackspotNotification[],
+}
+
+const StyledBox = styled(Box)`
+  width: 100%;
+  position: relative;
+  transition: opacity 0.3s;
+
+  > div:first-child{
+    width: 100%;
+  }
+
+  &.loading {
+    opacity: 0.6;
+    .loading-mask {
+      pointer-events: auto;
+    }
+  }
+
+  .loading-mask {
+    opacity: 0;
+    position: absolute;
+    pointer-events: none;
+    top: 0;
+    right: 0;
+    left: 0;
+    bottom: 0;
+    cursor: progress;
+  }
+
+  .placeholder.compact {
+    & > div {
+      padding-block: 0;
+      gap: 15px;
+      & > div {
+        text-align: center;
+        h4 {
+          margin-bottom: 10px;
+        }
+        p {
+          margin: 0;
+        }
+      }
+    }
+  }
+`
+
+// this assumes the data from the backend is ordered by date (trigger_at)
+function groupNotificationsByDate(notifications: StackspotNotification[]): NotificationGroup[] {
+  const groups: NotificationGroup[] = []
+  for (const n of notifications) {
+    let currentGroup = last(groups)
+    const date = new Date(n.trigger_at)
+    const year = date.getFullYear()
+    const month = date.getMonth() as Month
+    const day = date.getDate()
+    if (!currentGroup || currentGroup.day !== day || currentGroup.month !== month || currentGroup.year !== year) {
+      currentGroup = { year, month, day, items: [] }
+      groups.push(currentGroup)
+    }
+    currentGroup.items.push(n)
+  }
+  return groups
+}
+
+export const NotificationList = (
+  { items, compact = false, onCommit, onClickAction, infiniteScroll, loading, showEmptySearch, style, className }: NotificationListProps,
+) => {
+  const groups: NotificationGroup[] = useMemo(
+    () => compact ? [{ day: 0, month: 0, year: 0, items }] : groupNotificationsByDate(items),
+    [compact, items],
+  )
+
+  const renderNotifications = (notifications: StackspotNotification[], key?: string) => (
+    <Flex sx={{ gap: '4px' }} flexDirection="column" key={key}>
+      {notifications?.map((item) => (
+        <NotificationItem
+          key={item.id}
+          notification={item}
+          isSummary={compact}
+          onCommit={() => onCommit(item.id)}
+          onClickAction={() => onClickAction?.(item.id)}
+        />
+      ))}
+    </Flex>
+  )
+
+  return infiniteScroll?.scrollableTarget !== null && (
+    <StyledBox style={style} className={listToClass([className, loading && 'loading'])}>
+      {items.length ? (
+        <InfiniteScroll
+          dataLength={items.length || 0}
+          next={infiniteScroll?.loadMore ?? (() => {})}
+          hasMore={infiniteScroll?.hasMore ?? false}
+          // @ts-ignore: the library is wrongly typed and abandoned, meaning, it will never be fixed. The source code clearly accepts
+          // HTMLElements as scrollable targets:
+          // https://github.com/ankeetmaini/react-infinite-scroll-component/blob/master/src/index.tsx#L168 
+          scrollableTarget={infiniteScroll?.scrollableTarget}
+        >
+          <Flex sx={{ gap: '24px' }} flexDirection="column">
+            {groups.map((group) => compact
+              ? renderNotifications(group.items, 'compact')
+              : (
+                <TimelineSection key={`${group.day}-${group.month}-${group.year}`} month={group.month} day={group.day}>
+                  {renderNotifications(group.items)}
+                </TimelineSection>
+              ),
+            )}
+          </Flex>
+        </InfiniteScroll>
+      ) : <NotificationPlaceholder isSearch={showEmptySearch} className={listToClass(['placeholder', compact && 'compact'])} />}
+      <div className="loading-mask"></div>
+    </StyledBox>
+  )
+}

package/src/components/notification/NotificationPlaceholder.tsx

@@ -0,0 +1,40 @@
+import { SxProperties } from '@citric/core/dist/sx'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { PlaceholderCallToAction } from '../Placeholder'
+
+interface Props {
+  isSearch?: boolean,
+  style?: React.CSSProperties,
+  className?: string,
+  sx?: SxProperties,
+  sxCard?: SxProperties,
+}
+
+export const NotificationPlaceholder = ({ isSearch, sx, sxCard, className, style }: Props) => {
+  const t = useTranslate(dictionary)
+
+  return <PlaceholderCallToAction
+    title={isSearch ? t.placeholderSearchTitle : t.placeholderTitle}
+    description={isSearch ? t.placeholderSearchDescription : t.placeholderDescription}
+    fullWidth
+    sx={sx}
+    sxCard={sxCard}
+    className={className}
+    style={style}
+  />
+}
+
+const dictionary = {
+  en: {
+    placeholderTitle: 'No notifications',
+    placeholderDescription: 'Your notifications will appear here.',
+    placeholderSearchTitle: 'No notifications found',
+    placeholderSearchDescription: 'You can change the current filters in the fields above',
+  },
+  pt: {
+    placeholderTitle: 'Nenhuma notificação',
+    placeholderDescription: 'Suas notificações aparecerão aqui.',
+    placeholderSearchTitle: 'Nenhuma notificação encontrada',
+    placeholderSearchDescription: 'Você pode mudar os filtros aplicados nos campos acima',
+  },
+} satisfies Dictionary

package/src/components/{Notifications → notification}/types.ts

@@ -1,3 +1,4 @@
+// fixme: please, do not ignore lint rules. They exist for a reason. Next major: transform this enum into a disjoint string type.
 // eslint-disable-next-line no-restricted-syntax
 export enum NotificationType {
   High = 'HIGH',
@@ -5,6 +6,8 @@ export enum NotificationType {
   Low = 'LOW',
 }
 
+
+// fixme: please, do not ignore lint rules. They exist for a reason. Next major: transform this enum into a disjoint string type.
 // eslint-disable-next-line no-restricted-syntax
 export enum NotificationContext {
   Account = 'ACCOUNT',
@@ -40,7 +43,25 @@ export interface NotificationCommitted {
   committed: boolean,
 }
 
+// fixme: please, do not ignore lint rules. They exist for a reason. Next major: transform this enum into a disjoint string type.
 // eslint-disable-next-line no-restricted-syntax
 export enum UnreadType {
   Unread = 'unread',
 }
+
+export interface InfiniteScrollConfig {
+  /**
+   * Function to load more items into the list. Called when the scroll is almost reaching its end.
+   */
+  loadMore: () => void,
+  /**
+   * Set this to false to prevent the scroll from loading more items when it reaches the end.
+   */
+  hasMore: boolean,
+  /**
+   * Defines which scroll will be used as the target of the infinite scroll.
+   * 
+   * If null, nothing renders, it waits until it has a value.
+   */
+  scrollableTarget?: string | HTMLElement | null,
+}

package/src/containers/NotificationsPage.tsx

@@ -0,0 +1,98 @@
+import { Text } from '@citric/core'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { styled } from 'styled-components'
+import { AsyncContent } from '../components/AsyncContent'
+import { ErrorFeedback } from '../components/error'
+import { SearchInput } from '../components/form/SearchInput'
+import { Select } from '../components/form/Select'
+import { NotificationList } from '../components/notification/NotificationList'
+import { useNotificationList } from '../context/notification/hooks'
+import { NotificationContext, NotificationPriority } from '../context/notification/types'
+import { useNotificationController } from '../notifications'
+
+const FilterBox = styled.div`
+  margin: 24px 0;
+  display: flex;
+  flex-direction: row;
+  gap: 8px;
+
+  > * {
+    flex: 1;
+  }
+`
+
+const criticalities: NotificationPriority[] = ['HIGH', 'MEDIUM', 'LOW']
+const contexts: NotificationContext[] = ['ACCOUNT', 'STUDIO', 'WORKSPACE']
+
+export const NotificationsPage = () => {
+  const t = useTranslate(dictionary)
+  const controller = useNotificationController()
+  const { hasMore, items, loadMore, applyFilters, filters, status, error } = useNotificationList()
+
+  return (<>
+    <header><Text appearance="h2" as="h1">{t.title}</Text></header>
+    <Text appearance="body2" colorScheme="light.700">
+      {t.description}
+    </Text>
+    <FilterBox>
+      <SearchInput searchText={t.filter} defaultValue={filters.search} onChange={search => applyFilters({ search })} />
+      <Select
+        value={filters.criticality}
+        options={criticalities}
+        onChange={criticality => applyFilters({ criticality })}
+        emptyOption={t.allCriticalities}
+        renderLabel={o => t[`criticality.${o}`]}
+      />
+      <Select
+        value={filters.context}
+        options={contexts}
+        onChange={context => applyFilters({ context })}
+        emptyOption={t.allContexts}
+        renderLabel={o => t[`context.${o}`]}
+      />
+    </FilterBox>
+    <AsyncContent
+      error={error}
+      loading={status === 'startup'}
+      errorDetails={{ errorComponent: () => <ErrorFeedback code={error.code} />, reportError: () => {} }}
+    >
+      <NotificationList
+        items={items}
+        loading={status === 'loading'}
+        onCommit={id => controller.markAsCommitted(id)}
+        infiniteScroll={{ hasMore, loadMore }}
+        onClickAction={controller.config.onClickAction}
+        showEmptySearch
+      />
+    </AsyncContent>
+  </>)
+}
+
+const dictionary = {
+  en: {
+    title: 'Notifications',
+    description: 'All notifications you received is shown up here.',
+    filter: 'Filter',
+    allCriticalities: 'All Criticalities',
+    'criticality.HIGH': 'High',
+    'criticality.MEDIUM': 'Medium',
+    'criticality.LOW': 'Low',
+    allContexts: 'All contexts',
+    'context.ACCOUNT': 'Account',
+    'context.STUDIO': 'Studio',
+    'context.WORKSPACE': 'Workspace',
+  },
+  pt: {
+    title: 'Notifications',
+    description: 'Todas as notificações que você recebeu são mostradas aqui.',
+    filter: 'Filtrar',
+    allCriticalities: 'Todas as criticidades',
+    'criticality.HIGH': 'Alto',
+    'criticality.MEDIUM': 'Médio',
+    'criticality.LOW': 'Baixo',
+    allContexts: 'Todos os contextos',
+    'context.ACCOUNT': 'Conta',
+    'context.STUDIO': 'Estúdio',
+    'context.WORKSPACE': 'Workspace',
+  },
+} satisfies Dictionary

package/src/context/notification/LazyNotificationList.ts

@@ -0,0 +1,95 @@
+import { pull, uniqBy } from 'lodash'
+import { StackspotNotification } from '../../components/notification/types'
+import { LazyNotificationListener, LoadNotificationsFilters, LoadNotificationsOptions, LoadResult } from './types'
+
+interface ConstructorParams {
+  id: number,
+  load: (options: LoadNotificationsOptions) => Promise<LoadResult>,
+  filters?: LoadNotificationsFilters,
+}
+
+export class LazyNotificationList {
+  readonly id: number
+  items: StackspotNotification[] = []
+  private page = -1
+  private total = 0
+  private filters: LoadNotificationsFilters
+  private readonly load: (options: LoadNotificationsOptions) => Promise<LoadResult>
+  private listeners: LazyNotificationListener[] = []
+  private currentFetch: Promise<void> | undefined
+
+  constructor({ id, load, filters = {} }: ConstructorParams) {
+    this.id = id
+    this.load = load
+    this.filters = filters
+  }
+
+  private notify() {
+    const hasMore = this.hasMore()
+    this.listeners.forEach(l => l(this.items, hasMore))
+  }
+
+  async #loadMore(reset = false): Promise<void> {
+    try {
+      const result = await this.load({ ...this.filters, page: this.page + 1 })
+      if (reset) {
+        this.items = []
+        this.total = 0
+      }
+      // we can't have items with the same id: this can happen if new notifications have been created after the first page was loaded.
+      this.items = uniqBy([...this.items, ...result.items], 'id')
+      // we can't keep loading more if we already loaded every item or if the API returned an empty list.
+      this.total = result.items.length ? (this.total || result.total) : this.items.length
+      this.page++
+      this.notify()
+    } finally {
+      this.currentFetch = undefined
+    }
+  }
+
+  async applyFilters(filters: LoadNotificationsFilters) {
+    const prevPage = this.page
+    const prevFilters = this.filters
+    this.filters = filters
+    this.page = -1
+    try {
+      await this.currentFetch
+      this.currentFetch = this.#loadMore(true)
+      await this.currentFetch
+    } catch (error) {
+      this.filters = prevFilters
+      this.page = prevPage
+      throw error
+    }
+  }
+
+  loadMore() {
+    this.currentFetch ??= this.#loadMore()
+    return this.currentFetch
+  }
+
+  hasMore() {
+    return this.items.length < this.total
+  }
+
+  subscribe(listener: LazyNotificationListener) {
+    this.listeners.push(listener)
+    return () => {
+      pull(this.listeners, listener)
+    }
+  }
+
+  update(readStatusMap: Map<string, boolean>) {
+    this.items.forEach(i => i.committed = readStatusMap.get(i.id) ?? i.committed)
+    if (this.filters.committed !== undefined) {
+      this.items = this.items.filter(i => i.committed === this.filters.committed)
+      // if the filtered list has one item or less, we update the list with the backend so it can show more items 
+      if (this.items.length <= 1) this.applyFilters(this.filters)
+    }
+    this.notify()
+  }
+
+  mute() {
+    this.listeners = []
+  }
+}