@speles7172/message-console

The screens for the notification, inquiry and email module: a bell with its dropdown, the notifications page behind it, the settings that decide what reaches whom, a conversation panel that hangs off any record, and the administrator's editor for the wording of every notification the application sends.

npm install @speles7172/message-console

import { NotificationBell, ThreadPanel } from '@speles7172/message-console';
import '@speles7172/message-console/styles.css';

React 18 or 19, as a peer dependency.

The transport

A browser cannot query Postgres and must never hold a mail credential, so the console queries nothing itself. The consuming application exposes endpoints backed by @speles7172/message-client and supplies one object:

// Module scope, not inline in JSX — see below.
const transport = {
  notifications: (query) => api.get('/notifications', query),
  unreadCount: () => api.get('/notifications/unread'),
  markRead: (ids) => api.post('/notifications/read', { ids }),
  markAllRead: () => api.post('/notifications/read-all'),

  thread: (id) => api.get(`/threads/${id}`),
  postMessage: (input) => api.post(`/threads/${input.threadId}/messages`, input),
  people: {
    search: (query) => api.get('/options/people', query),
    resolve: (values) => api.get('/options/people/resolve', { values }),
  },
};

<NotificationBell transport={transport} pollMs={60_000} onSeeAll={() => navigate('/notifications')} />

Every method except notifications is optional, and each one is a capability. A transport with no postMessage renders a read-only transcript; one with no people renders no participant picker and no @ autocomplete. The alternative — a button that always fails — is worse than a button that is not there.

There are two kinds of endpoint here, and they belong behind different gates. The notification and thread methods act as the signed-in person: take the recipient id from the session and never from the request, because a recipientId a browser can choose is a way to read anybody's notifications. The template methods are administrative. This package applies no access control of its own.

Hold the transport still. Every component keys its effects on the object's identity, so an object literal written inline in JSX is a new transport on every render and therefore an endless reload. Put it in a module constant or behind useMemo.

What is in it

| | | |---|---| | <NotificationBell> | The bell, its badge and the dropdown. Loads the list only once opened — a bell is on every page, and fetching twenty rows to render a number is a request per page view. | | <NotificationsConsole> | The same rows on a page of their own, with search, a read/unread filter and a pager. | | <NotificationPreferences> | A master switch per channel, and a row per event. Each toggle is its own request, because a page that PUTs the whole object loses every change made in another tab. | | <ThreadPanel> | One conversation: its messages, its people, the status, and the box to reply in. Says "via email" on a message that arrived that way. | | <InquiryButton> | The entry point from a record to its conversations. Drop it on an invoice and that invoice has inquiries. | | <NewInquiryForm> | Subject, people and a first message, in one submit. | | <MessageComposer> | A plain textarea with @ mentions. Enter sends; Shift+Enter is a newline. | | <MentionText> | A body with its mentions rendered as mentions rather than as raw markup. | | <TemplatesConsole> | The wording of every notification, with a live preview that runs the real renderer. With setTemplateEnabled on the transport it offers an on/off switch per channel; with sendTestTemplate, a “Send a test to me” button for email that sends the wording on screen, saved or not. | | <RoutingConsole> | Who hears each event: the named groups, and the rule pointing an event at one. The other half of the templates page — that one decides what a notification says, this one decides who gets it. | | useNotifications, useThread, useRouting | The behaviour without the markup, for an application with its own design system. |

Words

Every string these components render can be replaced, and every one defaults to today's English — so a caller that passes nothing sees no change at all.

import { ThreadPanel, type MessageLabels } from '@speles7172/message-console';

const HEBREW: MessageLabels = {
  send: 'שליחה',
  composerPlaceholder: 'כתבו הודעה…',
  statuses: { open: 'פתוח' },       // the other two keep their defaults
  minuteAgo: 'לפני דקה',
  minutesAgo: 'לפני {count} דקות',
};

<ThreadPanel transport={transport} threadId={id} viewer={viewer} labels={HEBREW} />

This exists because the problem is ownership, not translation. These parts go on screens an application has already translated — a subscriber's portal, a customer's own inbox — and a console saying "Inquiries" in English inside an otherwise Hebrew page is not a styling mismatch, it is a screen the reader cannot use. An admin console can live with the package's words; a subscriber-facing one cannot.

Three things worth knowing:

• Singular and plural are separate fields. "1 minutes ago" is the failure in English, and in most languages the plural changes more than a suffix — the consuming application already knows how its own language counts. {count} is substituted where a number appears.
• An absent value means "leave it alone", not "make it empty." A caller building labels from its own catalog produces undefined for anything it has not translated yet, and those keep the default rather than blanking it.
• statuses is merged a level deeper. Renaming "Open" alone must not drop the other two.

DEFAULT_MESSAGE_LABELS is exported, so four words can be overridden without restating forty.

Theming

One stylesheet, one class, custom properties throughout:

.my-app .msgc {
  --msgc-accent: #7c3aed;
  --msgc-radius: 10px;
}

The dark palettes are wrapped in :where() so nothing in the stylesheet out-specifies a host that overrides a token. theme takes light (the default), dark, or auto — auto follows prefers-color-scheme, which is right only when the host follows it too.

The stylesheet already contains @speles7172/controls, whose pickers this console renders. Importing both is harmless — the shared rules are byte- identical and at identical specificity.

Licence

MIT