@fvc/notification 1.2.1 → 1.2.2-next-ec65dfb844e6183b3d7f417eee613cfe5ecfd997

package/README.md

@@ -0,0 +1,224 @@
+# @fvc/notification
+
+`@fvc/notification` wraps Ant Design's notification system with FE-VIS design tokens and icons. It applies the dark card background, per-type icon colours, and Roboto typography automatically. Supports both a hook-based API (recommended) and static methods for non-component contexts.
+
+## Installation
+
+```bash
+bun add @fvc/notification
+```
+
+## Peer Dependencies
+
+```bash
+bun add react antd @fvc/icons
+```
+
+## Import
+
+```ts
+import { notification } from '@fvc/notification';
+```
+
+## Quick Start
+
+```tsx
+import { notification } from '@fvc/notification';
+
+function SaveButton() {
+  const [api, contextHolder] = notification.useNotification({});
+
+  return (
+    <>
+      {contextHolder}
+      <button onClick={() => api.success({ message: 'Changes saved' })}>
+        Save
+      </button>
+    </>
+  );
+}
+```
+
+## Notification Types
+
+| Type | Auto icon | Message colour |
+| --- | --- | --- |
+| `success` | `CheckCircleOutline` | `--link-on-dark-bg-color-400` |
+| `info` | `Info` | `--gray-300` |
+| `warning` | `Warning` | `--orange-200` |
+| `error` | `Report` | `--warning-icon-on-dark-bg-color-400` |
+
+Icons and colours are applied automatically by type. Pass `icon` explicitly to override.
+
+## Usage Patterns
+
+### `useNotification` — recommended
+
+Binds the notification to the React tree so it inherits `ConfigProvider` context (locale, theme, etc.). `contextHolder` must be rendered somewhere in the tree above where the notification is triggered — placing it at the top of the component is sufficient.
+
+```tsx
+function Page() {
+  const [api, contextHolder] = notification.useNotification({});
+
+  const handleError = () => {
+    api.error({
+      message: 'Request failed',
+      innerComponent: <button onClick={retry}>Retry</button>,
+    });
+  };
+
+  return (
+    <>
+      {contextHolder}
+      <button onClick={handleError}>Submit</button>
+    </>
+  );
+}
+```
+
+### Static API — deprecated
+
+Works without a hook but does not inherit React context. Suitable for non-component code such as axios interceptors where a hook cannot be called.
+
+```tsx
+notification.success({ message: 'Done' });
+notification.error({ message: 'Something went wrong' });
+```
+
+> **Deprecated.** Static methods (`success`, `error`, `info`, `warning`) will be removed in a future major version. Use `notification.useNotification()` for all new code.
+
+## Methods
+
+| Method | Description |
+| --- | --- |
+| `useNotification(config)` | Returns `[api, contextHolder]`. Recommended pattern. |
+| `open(config)` | Opens a notification without a preset type. |
+| `success(config)` | Opens a success notification. Deprecated. |
+| `info(config)` | Opens an info notification. Deprecated. |
+| `warning(config)` | Opens a warning notification. Deprecated. |
+| `error(config)` | Opens an error notification. Deprecated. |
+| `destroy(key?)` | Destroys one notification by key, or all if no key is provided. |
+| `config(globalConfig)` | Sets global defaults (placement, duration, maxCount, etc.). |
+
+## Config (`ArgsProps`)
+
+Extends antd's `ArgsProps`. The `description` field from antd is replaced by `innerComponent`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `message` | `ReactNode` | Notification title. |
+| `innerComponent` | `ReactNode` | Content rendered below the title. Replaces antd's `description`. |
+| `icon` | `ReactNode` | Overrides the automatic type icon. |
+| `duration` | `number` | Auto-close in seconds. `0` disables auto-close. |
+| `placement` | `NotificationPlacement` | Where the notification appears. Default: `topRight`. |
+| `key` | `string` | Unique key for programmatic updates or targeted destruction. |
+| `onClose` | `() => void` | Called when the notification closes. |
+
+## Common Usage
+
+### With `innerComponent`
+
+```tsx
+api.warning({
+  message: 'Session expiring soon',
+  duration: 0,
+  innerComponent: (
+    <button onClick={extendSession}>Extend session</button>
+  ),
+});
+```
+
+### Custom placement
+
+```tsx
+const [api, contextHolder] = notification.useNotification({
+  placement: 'bottomRight',
+});
+```
+
+### Custom icon
+
+```tsx
+import { Icon } from '@fvc/icons';
+
+api.open({
+  message: 'Upload complete',
+  icon: <Icon.CheckCircle color="var(--green-400)" width={24} height={24} />,
+});
+```
+
+### Persistent notification
+
+```tsx
+api.error({
+  key: 'save-error',
+  message: 'Could not save changes',
+  duration: 0,
+});
+
+// Dismiss programmatically
+api.destroy('save-error');
+```
+
+## Consumer Example
+
+```tsx
+import { notification } from '@fvc/notification';
+
+function useFormSubmit() {
+  const [api, contextHolder] = notification.useNotification({
+    placement: 'bottomRight',
+  });
+
+  const submit = async (data: FormData) => {
+    try {
+      await postData(data);
+      api.success({ message: 'Record saved successfully' });
+    } catch {
+      api.error({
+        message: 'Save failed',
+        duration: 0,
+        innerComponent: (
+          <button onClick={() => submit(data)}>Try again</button>
+        ),
+      });
+    }
+  };
+
+  return { submit, contextHolder };
+}
+```
+
+## Testing
+
+Notifications render outside the React tree in a portal. Call `notification.destroy()` in `afterEach` to prevent toast leakage between test cases.
+
+```ts
+afterEach(() => {
+  notification.destroy();
+});
+```
+
+## CSS Classes
+
+| Class | Description |
+| --- | --- |
+| `.fvc-notification` | Root notification container |
+| `.fvc-notification-notice-wrapper` | Individual notification card (dark background) |
+| `.fvc-notification-notice` | Inner notice element |
+| `.fvc-notification-notice-message` | Title text |
+| `.fvc-notification-notice-icon` | Icon slot |
+| `.fvc-notification-notice-btn` | `innerComponent` slot |
+| `.fvc-notification-notice-close` | Close button |
+| `.fvc-notification-notice-success` | Applied on `success` type notifications |
+| `.fvc-notification-notice-info` | Applied on `info` type notifications |
+| `.fvc-notification-notice-warning` | Applied on `warning` type notifications |
+| `.fvc-notification-notice-error` | Applied on `error` type notifications |
+
+## Development
+
+```bash
+bun run lint
+bun run type-check
+bun run test
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fvc/notification",
-  "version": "1.2.1",
+  "version": "1.2.2-next-ec65dfb844e6183b3d7f417eee613cfe5ecfd997",
   "main": "./dist/lib/index.js",
   "types": "./dist/lib/notification/src/index.d.ts",
   "files": [
@@ -27,8 +27,20 @@
     "test": "bun test --preload ../../tests/happydom.ts --preload ../../tests/testing-library.tsx"
   },
   "peerDependencies": {
-    "@fvc/icons": "*",
+    "@fvc/icons": "1.1.4-next-ec65dfb844e6183b3d7f417eee613cfe5ecfd997",
     "react": "^18.0.0",
     "antd": "^5.0.0"
-  }
+  },
+  "keywords": [
+    "react",
+    "react-component",
+    "fvc",
+    "fe-vis-core",
+    "ui",
+    "notification",
+    "toast",
+    "alert",
+    "design-system",
+    "antd"
+  ]
 }