@stack-spot/portal-components 0.0.18 → 1.0.0-dev.1768482754546

package/src/components/notification/NotificationItem.tsx

@@ -0,0 +1,353 @@
+import { Box, Button, Flex, IconBox, OneOfColorSchemesWithVariants, Styles, SxProp, Text } from '@citric/core'
+import { Envelope, EnvelopeOpen, ExternalLink } from '@citric/icons'
+import { IconButton, Tooltip } from '@citric/ui'
+import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
+import { differenceInDays, parseISO } from 'date-fns'
+import styled from 'styled-components'
+import { useAnchorTag } from '../../context/anchor'
+import { useGetNotificationTitleAndDescription } from '../../context/notification/hooks'
+import { useDateFormatter } from '../../hooks/date'
+import { LazyMarkdown } from '../LazyMarkdown'
+import { GetTenantNotificationsResponse } from './types'
+
+const styles = {
+  item: (color: string, isRead: boolean) => ({
+    borderLeft: `2px solid ${color}`,
+    opacity: isRead ? 0.5 : 1,
+  }),
+} satisfies Record<string, (...args: any) => SxProp>
+
+const statusToColor: Record<string, OneOfColorSchemesWithVariants> = {
+  LOW: 'success.500',
+  MEDIUM: 'warning.500',
+  HIGH: 'danger.500',
+}
+
+interface Props {
+  notification: GetTenantNotificationsResponse,
+  isSummary: boolean,
+  // @deprecated this property currently does nothing. Remove in next major.
+  id?: string,
+  onClickViewNotification?: () => void,
+}
+
+const style: Styles = {
+  notificationDescription: {
+    display: '-webkit-box',
+    WebkitBoxOrient: 'vertical',
+    overflow: 'hidden',
+    WebkitLineClamp: '2',
+    lineHeight: '1.5',
+    maxHeight: '3em',
+    maxWidth: '340px',
+  },
+  notificationTooltip: {
+    overflowWrap: 'break-word',
+  },
+}
+
+/**
+ * NotificationHeader component that renders the header of a notification.
+ *
+ * @param props the component's props.
+ */
+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'} weight="medium" nowrapEllipsis mr={5}>
+      {title}
+    </Text>
+  </Flex>
+)
+
+/**
+ * Get the number of days ago from the given date string.
+ *
+ * @param {string} dateString - The date string to calculate the days ago.
+ * @returns {number} The number of days ago.
+ */
+const getDaysAgo = (dateString: string): number => {
+  const givenDate = parseISO(dateString)
+  const today = new Date()
+  return differenceInDays(today, givenDate)
+}
+
+/**
+ * NotificationContent component that renders the content of a notification.
+ *
+ * @param props the component's props {@link Props}.
+ */
+const NotificationContent = ({ notification, isSummary, onClickViewNotification }: Props) => {
+  const { formatRelativeWithTooltip } = useDateFormatter()
+  const relativeDate = formatRelativeWithTooltip(notification.trigger_at)
+  const Link = useAnchorTag()
+
+  const t = useTranslate(dictionary)
+  const { description } = useGetNotificationTitleAndDescription(notification)
+  const daysAgo = getDaysAgo(notification.trigger_at)
+
+  const components = () => ({
+    ul: (props: any) => (
+      <Text
+        as="ul"
+        appearance="body2"
+        colorScheme="light.700"
+        sx={{ listStyleType: 'disc', marginLeft: '2rem', marginBottom: '1em' }}
+        {...props}
+      />
+    ),
+    li: (props: any) => (
+      <Text
+        as="li"
+        appearance="body2"
+        colorScheme="light.700"
+        sx={{ marginBottom: '0.5em' }}
+        {...props}
+      />
+    ),
+    p: (props: any) => (
+      <Text
+        as="p"
+        appearance="body2"
+        sx={{ marginBottom: '1em' }}
+        {...props}
+      />
+    ),
+  })
+
+  const navigateToNotificationPosition = (ev: React.MouseEvent<HTMLElement>, anchorText: string) => {
+    ev.preventDefault()
+
+    const checkElement = setInterval(() => {
+      const target = document.getElementById(anchorText)
+      if (target) {
+        target.scrollIntoView({ behavior: 'smooth', block: 'start' })
+        clearInterval(checkElement)
+      }
+    }, 100)
+  }
+
+  return (
+    <>
+      {!isSummary && <Flex mt={4} mb={3} flexDirection="column">
+        <LazyMarkdown components={components()}>{description}</LazyMarkdown>
+      </Flex>}
+      {isSummary && (
+        <Text appearance="body2" mb={3} sx={style.notificationDescription}>
+          {handleTextMark(description)}
+        </Text>
+      )}
+      <Flex justifyContent="space-between">
+        <Flex>
+          <Text appearance="microtext1" colorScheme="light.700">
+            {t[notification.context]}
+          </Text>
+          <Text appearance="microtext1" colorScheme="light.700" mx="2">
+            •
+          </Text>
+          {!isSummary && relativeDate && (<>
+            <Text appearance="microtext1" colorScheme="light.700">
+              {relativeDate.relative}
+            </Text>
+            <Text appearance="microtext1" colorScheme="light.700" mx="2">
+              •
+            </Text>
+          </>)}
+          <Text appearance="microtext1" colorScheme="light.700">
+            {daysAgo > 0 ? daysAgo + ' ' + t.daysAgo : t.today}
+          </Text>
+        </Flex>
+        {isSummary && description.length > 120 && (
+          <Link
+            href="/notifications"
+            onClick={(ev: React.MouseEvent<HTMLElement>) => {
+              onClickViewNotification?.()
+              navigateToNotificationPosition(ev, `notification-item-${notification.id}`)
+            }}>
+            <Text appearance="microtext1" colorScheme="light.700">{t.readMore}</Text>
+          </Link>
+        )}
+      </Flex>
+    </>
+  )
+}
+
+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,
+  /**
+   * Notification title
+   */
+  title?: string,
+}
+
+/**
+ * NotificationFooter component that renders the footer of a notification.
+ *
+ * @param props the component's props {@link NotificationFooterProps}.
+ */
+const NotificationFooter = ({ actionURL, onClickAction, title }: NotificationFooterProps) => {
+  const t = useTranslate(dictionary)
+  const Link = useAnchorTag()
+
+  return (
+    <Flex mt="5">
+      <Button
+        size="sm"
+        colorScheme="inverse"
+        appearance="text"
+        onClick={onClickAction}
+        as={Link}
+        href={actionURL}
+        aria-label={t.viewNotification.replace('%s', title || t.moreDetails)}
+        target="_blank"
+      >
+        <Text sx={{ mr: 2, textDecoration: 'underline' }}>
+          {t.moreDetails}
+        </Text>
+        <IconBox size="xs">
+          <ExternalLink />
+        </IconBox>
+      </Button>
+    </Flex>
+  )
+}
+
+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,
+  /**
+   * Function to call when the user marks a notification as unread (uncommitted).
+   */
+  onUncommit: () => 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,
+  /**
+   * Function to call when the user clicks in read more button.
+   */
+  onClickViewNotification?: () => void,
+}
+
+type NotificationItemProps = DeprecatedNotificationItemProps | NewNotificationItemProps
+
+const StyledBox = styled(Box)<{$isSummary?: boolean}>`
+  .notification-item {
+    padding: ${({ $isSummary }) => $isSummary ? '8px 8px 8px 16px' : '16px'};
+  }
+`
+
+/**
+ * NotificationItem component that renders a notification item.
+ *
+ * @param props the component's props {@link NotificationItemProps}.
+ */
+export const NotificationItem = ({ notification, isSummary, ...props }: NotificationItemProps) => {
+  const t = useTranslate(dictionary)
+  const { title } = useGetNotificationTitleAndDescription(notification)
+  const committed = notification.committed
+
+  function commit() {
+    if ('onCommit' in props) props.onCommit()
+    else props.onClickMarkReadUnread(true, 'icon')
+  }
+
+  function uncommit() {
+    if ('onUncommit' in props) props.onUncommit()
+    else props.onClickMarkReadUnread(false, 'icon')
+  }
+
+  function clickAction() {
+    if ('onCommit' in props) {
+      if (!committed) props.onCommit()
+      props.onClickAction?.()
+    }
+    else props.onClickMarkReadUnread(true, 'callToAction')
+  }
+
+  return (
+    <StyledBox sx={{ position: 'relative' }} id={props.id} $isSummary={isSummary}>
+      <Flex bg="light.400" r="xs"
+        flexWrap="nowrap"
+        className="notification-item"
+        flexDirection="column" w="100%" sx={styles.item(statusToColor[notification.criticality], committed)}>
+        <NotificationHeader title={title} isSummary={isSummary} />
+        <NotificationContent notification={notification} isSummary={isSummary} onClickViewNotification={props.onClickViewNotification} />
+        {notification.call_to_action && <NotificationFooter
+          actionURL={notification.call_to_action}
+          onClickAction={clickAction}
+          title={title}
+        />}
+      </Flex>
+      <Box sx={{ position: 'absolute', top: '8px', right: '8px' }}>
+        <Tooltip text={committed ? t.committed : t.uncommitted} position="left">
+          <IconButton aria-label={committed ? t.committed : t.uncommitted} onClick={() => committed ? uncommit() : commit()}>
+            <IconBox size="xs" style={{ opacity: committed ? 0.5 : 1 }}>
+              {committed ? <EnvelopeOpen /> : <Envelope />}
+            </IconBox>
+          </IconButton>
+        </Tooltip>
+      </Box>
+    </StyledBox>
+  )
+}
+
+function handleTextMark(text: string) {
+  // eslint-disable-next-line no-useless-escape
+  return text.replace(/[^\p{L}\p{N}\s\p{Emoji_Presentation}:!'()"\/_-]/gu, '')
+}
+
+const dictionary = {
+  en: {
+    ACCOUNT: 'Account',
+    WORKSPACE: 'Workspace',
+    STUDIO: 'Studio',
+    AI: 'AI',
+    daysAgo: 'days ago',
+    today: 'today',
+    committed: 'This notification has been read.',
+    uncommitted: 'This notification has not been read yet. Click to mark as read.',
+    moreDetails: 'More details',
+    viewNotification: 'View notification %s',
+    readMore: 'Read more',
+  },
+  pt: {
+    ACCOUNT: 'Conta',
+    WORKSPACE: 'Workspace',
+    STUDIO: 'Estúdio',
+    AI: 'AI',
+    daysAgo: 'dias atrás',
+    today: 'hoje',
+    committed: 'Esta notificação já foi lida.',
+    uncommitted: 'Esta notificação ainda não foi lida. Clique para marcar como lida.',
+    moreDetails: 'Acessar detalhes',
+    viewNotification: 'Visualizar notificação %s',
+    readMore: 'Ler mais',
+  },
+} satisfies Dictionary

package/src/components/notification/NotificationList.tsx

@@ -0,0 +1,185 @@
+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 { GetTenantNotificationsResponse, InfiniteScrollConfig } 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,
+  /**
+   * Function to call when the message is marked as unread (uncommitted).
+   * @param id the id of the notification where the read status changed.
+   */
+  onUncommit: (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,
+ /**
+   * Optional. Function called when the button read more in notification is clicked.
+   */
+  onClickViewNotification?: () => void,
+  /**
+   * If you need this notification list to be have an infinite scroll behavior, set this option.
+   */
+  infiniteScroll?: InfiniteScrollConfig,
+  /**
+   * The notifications themselves.
+   */
+  items: GetTenantNotificationsResponse[],
+  /**
+   * 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: GetTenantNotificationsResponse[],
+}
+
+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: 16px;
+      & > 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: GetTenantNotificationsResponse[]): 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, onUncommit, onClickAction, onClickViewNotification,
+    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: GetTenantNotificationsResponse[], key?: string) => (
+    <Flex sx={{ gap: '4px' }} flexDirection="column" key={key}>
+      {notifications?.map((item) => (
+        <NotificationItem
+          key={item.id}
+          id={key ? '' : `notification-item-${item.id}`}
+          notification={item}
+          isSummary={compact}
+          onClickViewNotification={onClickViewNotification}
+          onCommit={() => onCommit(item.id)}
+          onUncommit={() => onUncommit(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'])}
+        titleAs="p"
+        sx={{ minHeight: '350px' }}
+      />}
+      <div className="loading-mask"></div>
+    </StyledBox>
+  )
+}

package/src/components/notification/NotificationPlaceholder.tsx

@@ -0,0 +1,60 @@
+import { AsProp } from '@citric/core/dist/forward-ref-as'
+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,
+  titleAs?: AsProp,
+}
+
+export const NotificationPlaceholder = ({ isSearch, sx, sxCard, className, style, titleAs }: Props) => {
+  const t = useTranslate(dictionary)
+
+  return <PlaceholderCallToAction
+    title={
+      isSearch
+        ? (<>{t.placeholderSearchTitle}<br />{t.placeholderSearchSubTitle}</>)
+        : (<>{t.placeholderTitle}<br />{t.placeholderSubTitle}</>)
+    }
+    description={
+      isSearch
+        ? (<>{t.placeholderSearchDescription}<br />{t.placeholderSearchSubDescription}</>)
+        : (<>{t.placeholderDescription}<br />{t.placeholderSubDescription}</>)
+    }
+    fullWidth
+    sx={sx}
+    sxCard={sxCard}
+    className={className}
+    style={style}
+    titleAs={titleAs}
+    placeholderImageConfig={{ width: '200', height: '200' }}
+  />
+}
+
+const dictionary = {
+  en: {
+    placeholderTitle: 'You don’t have',
+    placeholderSubTitle: 'any notifications yet.',
+    placeholderDescription: 'Relevant updates will show up here',
+    placeholderSubDescription: 'as soon as they’re available.',
+    placeholderSearchTitle: 'No notifications',
+    placeholderSearchSubTitle: 'match your filters.',
+    placeholderSearchDescription: 'Try changing the filters',
+    placeholderSearchSubDescription: 'to see more results.',
+  },
+  pt: {
+    placeholderTitle: 'Você ainda não tem',
+    placeholderSubTitle: 'notificações.',
+    placeholderDescription: 'Quando houver alguma atualização relevante,',
+    placeholderSubDescription: 'ela será exibida aqui.',
+    placeholderSearchTitle: 'Nenhuma notificação',
+    placeholderSearchSubTitle: 'corresponde aos filtros',
+    placeholderSearchDescription: 'Experimente mudar os filtros',
+    placeholderSearchSubDescription: 'para encontrar mais notificações.',
+  },
+} satisfies Dictionary

package/src/components/notification/types.ts

@@ -0,0 +1,72 @@
+export type NotificationType = 'LOW' | 'MEDIUM' | 'HIGH'
+
+export type NotificationContext = 'ACCOUNT' | 'STUDIO' | 'WORKSPACE' | 'AI'
+
+//The following three notification types comes from the api swagger
+
+export type NotificationContentResponse = {
+  title: string,
+  description: string,
+};
+
+export type GetTenantNotificationsResponse = {
+  id: string,
+  content: {
+    [key: string]: NotificationContentResponse,
+  },
+  broadcast_level: 'ACCOUNT' | 'INDIVIDUAL' | 'PLATFORM' | 'RESOURCE',
+  context: 'ACCOUNT' | 'STUDIO' | 'WORKSPACE' | 'AI',
+  target?: string,
+  criticality: 'LOW' | 'MEDIUM' | 'HIGH',
+  call_to_action: string,
+  persistent: boolean,
+  committed: boolean,
+  last_until?: string,
+  trigger_at: string,
+  created_at?: string,
+  isBanner?: boolean,
+}
+
+export type ResponseModelGetTenantNotificationsResponse = {
+  items: GetTenantNotificationsResponse[],
+  total: number,
+}
+
+export type NotificationTypeFilters = NotificationType | UnreadType
+
+export interface NotificationFilters { 
+  filterBy?: 'criticality' | 'context',
+  filterValue?: string,
+  sort?: string,
+  direction?: string,
+  page?: any,
+  size?: string,
+}
+
+export interface NotificationCommitted {
+  id: string,
+  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,
+}