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

package/src/containers/NotificationsPage.tsx

@@ -0,0 +1,121 @@
+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']
+type TimeKey = `time.${1 | 7 | 30 | 90 | 365}`
+const times = [1, 7, 30, 90, 365]
+
+export const NotificationsPage = () => {
+  const t = useTranslate(dictionary)
+  const controller = useNotificationController()
+  const { hasMore, items, loadMore, applyFilters, filters, status, error } = useNotificationList()
+  const hasFilters = Object.entries(filters).length > 0
+
+  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.createdSince}
+        options={times}
+        onChange={createdSince => applyFilters({ createdSince })}
+        emptyOption={t.anyTime}
+        renderLabel={o => t[`time.${o}` as TimeKey]}
+      />
+      <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)}
+        onUncommit={id => controller.markAsUncommitted(id)}
+        infiniteScroll={{ hasMore, loadMore }}
+        onClickAction={controller.config.onClickAction}
+        showEmptySearch={hasFilters}
+      />
+    </AsyncContent>
+  </>)
+}
+
+const dictionary = {
+  en: {
+    title: 'Notifications',
+    description: 'Here you can view all your received notifications.',
+    filter: 'Filter',
+    allCriticalities: 'All severities',
+    'criticality.HIGH': 'High',
+    'criticality.MEDIUM': 'Medium',
+    'criticality.LOW': 'Low',
+    allContexts: 'All contexts',
+    'context.ACCOUNT': 'Account',
+    'context.STUDIO': 'Studio',
+    'context.WORKSPACE': 'Workspace',
+    'anyTime': 'Any time',
+    'time.1': 'Last 24 hours',
+    'time.7': 'Last 7 days',
+    'time.30': 'Last 30 days',
+    'time.90': 'Last 90 days',
+    'time.365': 'Last 12 months',
+  },
+  pt: {
+    title: 'Notificações',
+    description: 'Aqui você encontra todas as notificações recebidas.',
+    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',
+    'anyTime': 'Todos os períodos',
+    'time.1': 'Últimas 24 horas',
+    'time.7': 'Últimos 7 dias',
+    'time.30': 'Últimos 30 dias',
+    'time.90': 'Últimos 90 dias',
+    'time.365': 'Últimos 12 meses',
+  },
+} satisfies Dictionary

package/src/context/anchor.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react'
+
+export type AnchorComponent = (props: React.AnchorHTMLAttributes<HTMLAnchorElement>) => React.ReactElement
+
+interface AnchorContext {
+  /**
+   * The component to render by a layout component a link is needed.
+   * @default <a>
+   */
+  anchorTag?: AnchorComponent,
+}
+
+const context = createContext<AnchorContext>({})
+
+const Anchor: AnchorComponent = props => <a {...props} />
+
+/**
+ * Some components need to create HTML anchors (links) to other pages in the website. These links, sometimes, must to be managed by a 
+ * navigator for React. Since we don't want to couple this library with any specific navigator, you can provide your own component for
+ * creating links, it must follow the same interface of the HTML's `a` tag.
+ * 
+ * If this is not used, the tag `<a>` is used by default.
+ * @param props the anchor component (anchorTag) and the content to render (children).
+ */
+export const AnchorProvider = ({ children, ...props }: Required<AnchorContext> & { children: React.ReactNode }) => (
+  <context.Provider value={props}>{children}</context.Provider>
+)
+
+/**
+ * A React hook for retrieving the Link (anchor) component.
+ * @returns the link component declared at {@link AnchorProvider} or a component that renders the tag <a> from HTML if no link component was
+ * provided.
+ */
+export function useAnchorTag(): AnchorComponent {
+  const { anchorTag } = useContext(context)
+  return anchorTag ?? Anchor
+}

package/src/context/loading.tsx

@@ -0,0 +1,36 @@
+import { LoadingCircular } from '@citric/ui'
+import { createContext, ReactElement, useContext } from 'react'
+
+interface LoadingContext {
+  /**
+   * The component to render by a layout component.
+   * @default <LoadingCircular>
+   */
+  loading?: ReactElement,
+}
+
+const context = createContext<LoadingContext>({})
+
+const Loading: ReactElement = <LoadingCircular size="sm" sx={{ position: 'absolute' }} />
+
+/**
+ * Some portals use a different loading style than what we have in citric.
+ * You can provide your own loading component to use wherever you want within the application.
+ * 
+ * @param position The position parameter is mandatory to be passed as absolute in the loading component that is being passed.
+ *
+ * If this is not used, the component `LoadingCircular` from citric is used by default.
+ * @param props the loading component (useLoadingComponent) and the content to render (children).
+ */
+export const LoadingProvider = ({ children, ...props }: Required<LoadingContext> & { children: React.ReactNode }) => (
+  <context.Provider value={props}>{children}</context.Provider>
+)
+
+/**
+ * A React hook for retrieving the Loading component.
+ * @returns the loading component declared at `LoadingProvider`.
+ */
+export function useLoadingComponent(): ReactElement {
+  const { loading } = useContext(context)
+  return loading ?? Loading
+}

package/src/context/notification/LazyNotificationList.ts

@@ -0,0 +1,103 @@
+import { pull, uniqBy } from 'lodash'
+import { GetTenantNotificationsResponse, ResponseModelGetTenantNotificationsResponse } from '../../notifications'
+import { LazyNotificationListener, LoadNotificationsFilters, LoadNotificationsOptions } from './types'
+
+interface ConstructorParams {
+  id: number,
+  load: (options: LoadNotificationsOptions) => Promise<ResponseModelGetTenantNotificationsResponse>,
+  filters?: LoadNotificationsFilters,
+}
+
+export class LazyNotificationList {
+  readonly id: number
+  items: GetTenantNotificationsResponse[] = []
+  private page = -1
+  private total = 0
+  private filters: LoadNotificationsFilters
+  private readonly load: (options: LoadNotificationsOptions) => Promise<ResponseModelGetTenantNotificationsResponse>
+  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) {
+    try {
+      await this.currentFetch
+    } catch {
+      /* empty: this error will be treated by the function who actually triggered `currentFetch`. We just need to make sure we wait until 
+      it ends before making new requests. */
+    }
+    const prevPage = this.page
+    const prevFilters = this.filters
+    this.filters = filters
+    this.page = -1
+    try {
+      
+      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.
+      // we can't use loadMore in this case because the page 2 would now skip some items. We'd need the backend to implement a cursor
+      // interface.
+      if (this.items.length <= 1) this.applyFilters(this.filters)
+    }
+    this.notify()
+  }
+
+  mute() {
+    this.listeners = []
+  }
+}

package/src/context/notification/NotificationController.ts

@@ -0,0 +1,119 @@
+import { pull } from 'lodash'
+import { LazyNotificationList } from './LazyNotificationList'
+import { LoadNotificationsFilters, NotificationConfig, UnreadNotificationListener } from './types'
+
+const DEFAULT_POLLING_MS = 120000
+
+export class NotificationController {
+  private lazyLists = new Map<number, LazyNotificationList>()
+  readonly config: NotificationConfig
+  private readStatusMap = new Map<string, boolean>()
+  private nextId = 1
+  private unreadNotification = false
+  private lastUnreadVerification: Date | undefined
+  private pollingTimeoutId: number | undefined
+  private unreadNotificationListeners: UnreadNotificationListener[] = []
+
+  constructor(config: NotificationConfig) {
+    this.config = config
+    config.pollingMS ??= DEFAULT_POLLING_MS
+    config.notificationsPath ??= '/notifications'
+  }
+
+  private hasUnreadNotificationInMemory() {
+    for (const [, read] of this.readStatusMap) {
+      if (!read.valueOf()) return true
+    }
+    return false
+  }
+
+  private setUnreadNotification(value: boolean) {
+    this.unreadNotification = value
+    if (!value) {
+      this.pollingTimeoutId = window.setTimeout(() => this.checkUnread(), this.config.pollingMS)
+    }
+    this.unreadNotificationListeners.forEach(l => l(value))
+  }
+
+  createLazyNotificationList(filters?: LoadNotificationsFilters): LazyNotificationList {
+    const list = new LazyNotificationList({
+      id: this.nextId++,
+      filters,
+      load: async (options) => {
+        const result = await this.config.load(options)
+        result.items.forEach((i) => {
+          this.readStatusMap.set(i.id, i.committed)
+          // updating the unread indicator, since it might be stale
+          if (!i.committed) this.setUnreadNotification(true)
+        })
+        this.lazyLists.forEach(l => l !== list && list.update(this.readStatusMap))
+        return result
+      },
+    })
+    this.lazyLists.set(list.id, list)
+    return list
+  }
+
+  destroyLazyNotificationList(id: number) {
+    this.lazyLists.get(id)?.mute()
+    this.lazyLists.delete(id)
+  }
+
+  async checkUnread() {
+    window.clearInterval(this.pollingTimeoutId)
+    this.setUnreadNotification(await this.config.checkForUnreadNotificationsSince(this.lastUnreadVerification))
+    this.lastUnreadVerification = new Date()
+  }
+
+  async markAsCommitted(notificationId: string) {
+    if (this.readStatusMap.get(notificationId)) return
+    this.readStatusMap.set(notificationId, true)
+    this.lazyLists.forEach(l => l.update(this.readStatusMap))
+    try {
+      await this.config.markAsCommitted(notificationId)
+      // update the notification indicator: this is an inconsistency, we should actually ask the API, but since it's an expensive
+      // operation in the backend, we won't, instead, we'll only check the notifications we have loaded in memory.
+      if (!this.hasUnreadNotificationInMemory()) this.setUnreadNotification(false)
+    } catch {
+      this.readStatusMap.set(notificationId, false)
+      this.lazyLists.forEach(l => l.update(this.readStatusMap))
+    }
+  }
+
+  async markAsUncommitted(notificationId: string) {
+    if (!this.readStatusMap.get(notificationId)) return
+    this.readStatusMap.set(notificationId, false)
+    this.lazyLists.forEach(l => l.update(this.readStatusMap))
+    try {
+      await this.config.markAsUncommitted(notificationId)
+      // update the notification indicator: this is an inconsistency, we should actually ask the API, but since it's an expensive
+      // operation in the backend, we won't, instead, we'll only check the notifications we have loaded in memory.
+      if (this.hasUnreadNotificationInMemory()) this.setUnreadNotification(true)
+    } catch {
+      this.readStatusMap.set(notificationId, true)
+      this.lazyLists.forEach(l => l.update(this.readStatusMap))
+    }
+  }
+
+  onUnreadNotificationChange(listener: UnreadNotificationListener) {
+    this.unreadNotificationListeners.push(listener)
+    return () => {
+      pull(this.unreadNotificationListeners, listener)
+    }
+  }
+
+  hasUnreadNotification() {
+    return this.unreadNotification
+  }
+
+  reset() {
+    this.lazyLists.clear()
+    this.readStatusMap.clear()
+    this.lastUnreadVerification = undefined
+    this.unreadNotification = false
+  }
+
+  mute() {
+    this.unreadNotificationListeners = []
+  }
+}

package/src/context/notification/context.tsx

@@ -0,0 +1,23 @@
+import { createContext, useContext } from 'react'
+import { NotificationController } from './NotificationController'
+
+export interface Props {
+  children: React.ReactNode,
+  controller: NotificationController,
+}
+
+const context = createContext<NotificationController | undefined>(undefined)
+
+export const NotificationProvider = ({ children, controller }: Props) => (
+  <context.Provider value={controller}>{children}</context.Provider>
+)
+
+export function useNotificationController() {
+  const controller = useContext(context)
+  if (!controller) {
+    throw new Error(
+      'A NotificationController was requested, but no NotificationController is available in the React Context. Please, be sure to wrap your component in a NotificationProvider.',
+    )
+  }
+  return controller
+}

package/src/context/notification/hooks.ts

@@ -0,0 +1,115 @@
+import { useLanguage } from '@stack-spot/portal-translate'
+import { useCallback, useRef, useState } from 'react'
+import { useManualRender } from '../../hooks/manual-render'
+import { useEffectOnce } from '../../hooks/use-effect-once'
+import { GetTenantNotificationsResponse } from '../../notifications'
+import { useNotificationController } from './context'
+import { LazyNotificationList } from './LazyNotificationList'
+import { LoadNotificationsFilters } from './types'
+
+function cleanFilters<T extends Record<string, unknown>>(filters: T): T {
+  const cleaned = { ...filters }
+
+  const keys = Object.keys(cleaned) as (keyof T)[]
+  keys.forEach((key) => {
+    const value = cleaned[key]
+
+    if (value === undefined || value === null || value === '') {
+      delete cleaned[key]
+    }
+  })
+
+  return cleaned
+}
+
+export function useNotificationList(initialFilters: LoadNotificationsFilters = {}) {
+  const { repaint } = useManualRender()
+  const [status, setStatus] = useState<'startup' | 'idle' | 'error' | 'loading'>('startup')
+  const error = useRef<any>()
+  const controller = useNotificationController()
+  const [filters, setFilters] = useState(initialFilters)
+  const list = useRef<LazyNotificationList | undefined>()
+
+  useEffectOnce(() => {
+    async function start() {
+      list.current = controller.createLazyNotificationList(initialFilters)
+      list.current.subscribe(repaint)
+      try {
+        await list.current?.loadMore()
+        setStatus('idle')
+      } catch (e) {
+        setStatus('error')
+        error.current = e
+      }
+    }
+    start()
+    return () => {
+      if (list.current) controller.destroyLazyNotificationList(list.current.id)
+    }
+  })
+
+  const applyFilters = useCallback(async (newFilters: LoadNotificationsFilters) => {
+    if (!list.current) return
+    setStatus('loading')
+    // since we're inside a useCallback, we don't have direct access to the current value of "filters". The only way we can access this
+    // value is from the function "setFilters". But "setFilters" run async. For this reason, we wait the function to run and retrieve the
+    // current value before continuing, hence the use of the await and promise below.
+    const { next, prev } = await new Promise<{ next: LoadNotificationsFilters, prev: LoadNotificationsFilters }>((resolve) => {
+      setFilters((filters) => {
+        const prev = filters
+        const merged = { ...filters, ...newFilters }
+        const next = cleanFilters(merged)
+
+        resolve({ prev, next })
+        return next
+      })
+    })
+    try {
+      await list.current.applyFilters(next)
+      setStatus('idle')
+      error.current = undefined
+    } catch (e) {
+      setFilters(prev)
+      if (error.current) {
+        error.current = e
+        setStatus('error')
+      } else {
+        setStatus('idle')
+      }
+    }
+  }, [])
+
+  return {
+    status,
+    items: list.current?.items ?? [],
+    hasMore: list.current?.hasMore() ?? false,
+    loadMore: () => list.current?.loadMore(),
+    refresh: () => applyFilters(filters),
+    applyFilters,
+    filters,
+    error: error.current,
+  }
+}
+
+export function useGetNotificationTitleAndDescription({ content }: GetTenantNotificationsResponse) {
+  const language = useLanguage()
+  const { title, description } = content?.[language] || content?.en || {}
+
+  return {
+    title,
+    description,
+  }
+}
+
+export function useUnreadNotifications() {
+  const [hasUnreadNotifications, setUnreadNotifications] = useState(false)
+  const controller = useNotificationController()
+
+  useEffectOnce(() => {
+    const unsubscribe = controller.onUnreadNotificationChange(setUnreadNotifications)
+    controller.checkUnread()
+    return unsubscribe
+  })
+
+  return hasUnreadNotifications
+}

package/src/context/notification/types.ts

@@ -0,0 +1,71 @@
+import { GetTenantNotificationsResponse, ResponseModelGetTenantNotificationsResponse } from '../../notifications'
+
+export type NotificationPriority = 'HIGH' | 'MEDIUM' | 'LOW'
+
+export type NotificationContext = 'ACCOUNT' | 'STUDIO' | 'WORKSPACE'
+
+export interface LoadNotificationsFilters {
+  committed?: boolean,
+  criticality?: NotificationPriority,
+  search?: string,
+  context?: NotificationContext,
+  size?: number,
+  isBanner?: boolean,
+  createdSince?: number,
+}
+
+export interface LoadNotificationsOptions extends LoadNotificationsFilters {
+  page: number,
+  isBanner?: boolean,
+}
+
+export type LazyNotificationListener = (notifications: GetTenantNotificationsResponse[], hasMore: boolean) => void
+
+export interface NotificationConfig {
+  /**
+   * Fetches the notifications according to the options passed as parameters.
+   * @param options page, size and filters.
+   * @returns a promise that resolves to a {@link ResponseModelGetTenantNotificationsResponse}.
+   */
+  load(options: LoadNotificationsOptions): Promise<ResponseModelGetTenantNotificationsResponse>,
+  /**
+   * Check for unread notifications since the date passed as parameter.
+   * @param date the date to start the search from
+   * @returns a promise that resolves to true if there are unread notifications or false otherwise.
+   */
+  checkForUnreadNotificationsSince(date?: Date): Promise<boolean>,
+  /**
+   * Marks the notification with the id passed as parameter as read (committed).
+   * @param id the id of the notification.
+   */
+  markAsCommitted(id: string): Promise<void>,
+  /**
+   * Marks the notification with the id passed as parameter as unread (uncommitted).
+   * @param id the id of the notification.
+   */
+  markAsUncommitted(id: string): Promise<void>,
+  /**
+   * How long (ms) we should wait before checking for unread notifications again.
+   * @default 120000
+   */
+  pollingMS?: number,
+  /**
+   * Path to the notifications page.
+   * @default '/notifications'
+   */
+  notificationsPath?: string,
+  /**
+   * A function to call whenever an action button of a notification is clicked. It receives the id of the notification as a parameter.
+   * 
+   * Useful for adding a behavior other than committing the notification and redirecting to its action. Example: analytics.
+   * 
+   * @param id the id of the notification.
+   */
+  onClickAction?: (id: string) => void,
+  /**
+   * Function that is called whenever the "read more" button is clicked.
+   */
+  onClickViewNotification?: () => void,
+}
+
+export type UnreadNotificationListener = (hasUnreadNotification: boolean) => void