@izara_frontend/notification

Shared React notification components and a portable Redux contract for Izara frontend applications.

Developer documentation:

• English developer guide
• คู่มือสำหรับ Developer ภาษาไทย

Install

npm install @izara_frontend/notification

React is a peer dependency. The host must also provide @izaraFrontends/styles, normally through the Izara import map.

Local development with npm link

Register the notification checkout as a local package:

cd "{path to local repo}"
npm install
npm run build
npm link

Link it into a consumer such as TableConfig or PageOutput Config:

cd "{path to local repo}"
npm link @izara_frontend/notification --no-save

Run npm run watch in the notification repository when the bundle should rebuild continuously.

Public API

Import only from the package root:

import {
  NotificationCards,
  NotificationConfirmation,
  NotificationStack,
  TopLevelNotificationStack,
  addTopLevelNotificationGroup,
  clearNotificationGroups,
  createNotificationState,
  removeNotificationGroup,
  removeNotificationGroupsByUniqueIdentifier,
  removeTopLevelNotificationGroup,
  sendExtraReducerNotification,
  selectNotificationGroups,
  selectTopLevelNotificationGroups,
  setNotificationGroup,
} from '@izara_frontend/notification';

Deep imports from src are not part of the package API.

Notification group contract

const notificationGroup = {
  uniqueIdentifier: 'save-table-success',
  severity: 'success',
  timeoutMilliseconds: 5000,
  notificationItems: [
    {
      subject: 'Save completed',
      notificationEntries: [
        {
          title: 'OK',
          message: 'The table configuration was saved.',
        },
      ],
    },
  ],
};

The supported severity values are success and warning. Every other value uses the error appearance. timeoutMilliseconds: null creates a sticky notification.

notificationGroupKey is the collection key used to add, replace, and remove a host-owned group. It is separate from uniqueIdentifier, which represents the business identity of a group.

Host-owned Redux setup

The package does not create a Redux slice and does not know the host's root state key. Add the notification state to the slice owned by each MFE and register the package's extra reducers alongside that MFE's reducers:

import { createSlice } from '@reduxjs/toolkit';
import {
  createNotificationState,
  sendExtraReducerNotification,
} from '@izara_frontend/notification';

const visibleConfigSlice = createSlice({
  name: 'myMfeVisibleConfig',
  initialState: {
    ...createNotificationState(),
    // other MFE-owned fields
  },
  reducers: {
    // other MFE-owned reducers
  },
  extraReducers(builder) {
    sendExtraReducerNotification(builder);
  },
});

The action creators use the package namespace (notification/...) and therefore work with any host slice name.

Case 1: Host-controlled notification stack

Read the host slice, adapt it with the subtree selector, and pass removal callbacks to the stack:

import { useDispatch, useSelector } from 'react-redux';
import {
  NotificationStack,
  selectNotificationGroups,
  setNotificationGroup,
  removeNotificationGroup,
  clearNotificationGroups,
} from '@izara_frontend/notification';

export function SaveNotificationExample() {
  const dispatch = useDispatch();
  const notificationState = useSelector((state) => state.myMfeVisibleConfig);
  const notificationGroups = selectNotificationGroups(notificationState);

  function showSavedNotification() {
    const notificationGroup = {
      uniqueIdentifier: 'table-save-success',
      severity: 'success',
      timeoutMilliseconds: 5000,
      notificationItems: [
        {
          subject: 'Saved',
          notificationEntries: [{ title: 'OK', message: 'Configuration saved.' }],
        },
      ],
    };
    const setNotificationAction = setNotificationGroup({
      notificationGroupKey: 'table-save',
      notificationGroup: notificationGroup,
    });
    dispatch(setNotificationAction);
  }

  return (
    <>
      <button type="button" onClick={showSavedNotification}>
        Save
      </button>
      <NotificationStack
        notificationGroups={notificationGroups}
        onRemoveGroup={(notificationGroupKey) =>
          dispatch(removeNotificationGroup({ notificationGroupKey }))
        }
        onClearGroups={() => dispatch(clearNotificationGroups())}
        placement="topRight"
      />
    </>
  );
}

Supported placements:

• bottomLeft (default)
• bottomCenter
• bottomRight
• center
• topLeft
• topCenter
• topRight

Unsupported values safely use bottom-left coordinates. Replacing a group under the same notificationGroupKey cancels its previous timer and starts a fresh lifecycle.

Style ownership and recovery backup

The notification library contains no hardcoded visual or placement CSS. Components select semantic styletags, and the Styles MFE owns the runtime definitions in src/lib/themeStyles/NotificationCssStyles.js. The stack position, card appearance, confirmation placement, icons, and progress element all come from that file.

The package includes a non-runtime recovery copy at backup/styles/NotificationCssStyles.js. If notification rules are deleted accidentally from the Styles MFE, follow the backup recovery instructions. After an intentional CSS change, update the Styles MFE source and backup together. Never import the backup into library source.

Notification actions (registered with the host slice by sendExtraReducerNotification):

| Action | Payload | Result | | --------------------------------- | --------------------------------------------- | ---------------------------------------- | | setNotificationGroup | { notificationGroupKey, notificationGroup } | Adds or replaces one keyed group | | removeNotificationGroup | { notificationGroupKey } | Removes one keyed group | | clearNotificationGroups | None | Removes every keyed group | | addTopLevelNotificationGroup | { notificationGroup } | Appends one host-slice top-level group | | removeTopLevelNotificationGroup | { notificationGroupIndex } | Removes a host-slice top-level group by index |

Case 2: Parent-owned notification stack

Use TopLevelNotificationStack when the parent owns the array through React state:

const [notificationGroups, setNotificationGroups] = useState([]);

<TopLevelNotificationStack
  notificationGroups={notificationGroups}
  setNotificationGroups={setNotificationGroups}
/>;

The component handles non-null timeouts and removes a card through the parent setter when its close button is clicked.

Case 3: Confirmation notification

const [confirmation, setConfirmation] = useState({});
const [successNotificationGroups, setSuccessNotificationGroups] = useState([]);

<NotificationConfirmation
  confirmation={confirmation}
  setConfirmation={setConfirmation}
  setSuccessNotificationGroups={setSuccessNotificationGroups}
  onConfirm={resetTable}
  position="reset-dialog"
  placement="center"
/>;

position selects which mounted confirmation instance renders. placement controls where it appears. Clicking OK runs onConfirm, replaces the built-in success group in the supplied array, and closes the prompt. Cancel only closes the prompt.

Case 4: Raw card renderer

NotificationCards renders cards without owning state, timers, or Redux dispatch:

<NotificationCards
  notificationGroups={notificationGroups}
  progressPercentages={progressPercentages}
  onClose={handleNotificationClose}
/>

onClose(notificationGroupKey) must update the source collection. Omit progressPercentages when no progress bar is needed.

Selectors and helper

const notificationState = useSelector((state) => state.myMfeVisibleConfig);
const notificationGroups = selectNotificationGroups(notificationState);
const topLevelNotificationGroups = selectTopLevelNotificationGroups(notificationState);

removeNotificationGroupsByUniqueIdentifier(notificationGroups, 'save-table-success', dispatch);

The helper removes every keyed host-owned group whose uniqueIdentifier matches.

Build, test, and publish

npm test
npm run build
npm pack --dry-run
npm version major
npm publish

This refactor replaces the public API without compatibility aliases, so its first release must use a new major version. Publish that notification version before updating and publishing PageOutput Config or TableConfig dependency locks.