@qumra/fanar 0.0.0 → 0.0.1

package/dist/notifications.d.ts

@@ -0,0 +1,833 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { T as Tone } from './lib-DOXggTK6.js';
+
+/**
+ * Schema version.
+ *
+ * Stamped on every message so the receiver knows how to read it. A message
+ * with no `v` is read as `1` — those were sent before the field existed.
+ */
+declare const NOTIFICATION_SCHEMA_VERSION = 1;
+/**
+ * Notification priority — three levels, each with real behaviour.
+ *
+ *   `low`       arrives silently
+ *   `normal`    the default
+ *   `critical`  chimes 35% louder, is **not** cleared by "mark all read",
+ *               and counts toward `needsAction`
+ *
+ * ## There used to be four
+ *
+ * `high` existed in the union type and nowhere else — not one line read it.
+ * Four levels with one that does nothing is worse than three that all work:
+ * whoever picks agonises over a distinction that isn't there, and whoever
+ * reads the code hunts for behaviour they will never find.
+ *
+ * A message still sending `high` is read as `normal` with a warning, not
+ * rejected.
+ */
+type NotificationPriority = 'low' | 'normal' | 'critical';
+declare const NOTIFICATION_PRIORITIES: NotificationPriority[];
+/**
+ * An action — a destination, not a callback.
+ *
+ * `href` is an internal path (`/orders/1052`) or a full URL. The library
+ * never navigates on its own: it calls `onAction` and you wire that to your
+ * router. That is what lets the same message work in a React Router app, a
+ * Next app, and a static page.
+ */
+interface NotificationAction {
+    label: string;
+    href: string;
+}
+/**
+ * The message on the wire — what the server sends and the database stores.
+ *
+ * Every optional field has a default in `parseNotification`, so the server
+ * sends the minimum and the rest is derived.
+ *
+ * @example
+ * {
+ *   "v": 1,
+ *   "id": "ntf_01HZY8K3",
+ *   "kind": "order.created",
+ *   "at": "2026-08-10T14:32:00.000Z",
+ *   "title": "New order #1052",
+ *   "body": "Paid in full, awaiting fulfilment.",
+ *   "priority": "normal",
+ *   "data": { "orderId": "1052", "total": 1480, "currency": "EGP" },
+ *   "action": { "label": "Open the order", "href": "/orders/1052" }
+ * }
+ */
+interface NotificationJSON {
+    /** Schema version — absent reads as `1` */
+    v?: number;
+    /** Stable unique id. Deduplication keys off it, so it must come from the server */
+    id: string;
+    /** Event name, `domain.event` — `order.created`, `stock.depleted` */
+    kind: string;
+    /** ISO 8601 in UTC — `2026-08-10T14:32:00.000Z` */
+    at: string;
+    title: string;
+    body?: string;
+    /**
+     * When it was read, ISO — `null` or absent means unread.
+     *
+     * ## Why a timestamp and not a boolean
+     *
+     * `read: true` is one-way: there is no way to say "make it unread again",
+     * and if you tried, the next sync would flip it back — because
+     * "read wins" has no reference to compare against.
+     *
+     * A timestamp gives the same guarantee (newest wins) and three more things:
+     * "unread" becomes a newer event, an optimistic rollback can tell its own
+     * mark from another device's mark that landed in the same instant, and
+     * time-to-read falls out for free.
+     */
+    readAt?: string | null;
+    /** @deprecated Use `readAt` — this is still read and converted, and will be removed */
+    read?: boolean;
+    priority?: NotificationPriority;
+    /**
+     * Grouping key — collapses **toasts only**.
+     *
+     * A new message replaces the previous one from the same group in the toast
+     * queue. Three toasts from the same source landing together is exactly the
+     * noise that makes a merchant turn notifications off.
+     *
+     * ## The inbox does not collapse
+     *
+     * All three stay as separate rows. A toast interrupts, so collapsing it is
+     * a kindness; a row is read at leisure, so collapsing it hides information.
+     *
+     * Durable collapsing ("3 new messages" as one row) is the server's job — it
+     * is the only side that sees the whole time window. Client-side collapsing
+     * only sees what reached this tab. Toasts don't have that problem because
+     * they are per-tab by nature, live for seconds, and nobody counts them.
+     */
+    group?: string;
+    /** Event payload — the library never reads it, it hands it back to you */
+    data?: Record<string, unknown>;
+    action?: NotificationAction;
+    /**
+     * Silence one message — `'none'` and nothing else.
+     *
+     * Sound normally comes from the kind registry. This is for the exception:
+     * the same kind arriving silently during a bulk import, say. There is no
+     * other value — the chime itself is not swappable per message.
+     */
+    sound?: 'none';
+}
+/**
+ * The message after validation — this is what components work with.
+ *
+ * The difference from `NotificationJSON`: dates are `Date`, and optionals are
+ * filled with their defaults. So no component ever writes `?? 'normal'` or
+ * `new Date(...)` again — normalisation happens once, at the boundary.
+ */
+interface Notification {
+    v: number;
+    id: string;
+    kind: string;
+    at: Date;
+    title: string;
+    body?: string;
+    /** When it was read — `null` means unread */
+    readAt: Date | null;
+    /** Shorthand for `readAt !== null` — derived, never stored */
+    read: boolean;
+    priority: NotificationPriority;
+    group?: string;
+    data: Record<string, unknown>;
+    action?: NotificationAction;
+    sound?: 'none';
+}
+/**
+ * The translate function — yours, not the library's.
+ *
+ * ## Why the library does not translate
+ *
+ * The first implementation was `locale.startsWith('ar') ? '…' : '…'` inside
+ * the registry. That works for two kinds and falls apart at the twelfth:
+ *
+ *   - Strings end up buried in code, where no translator can reach them
+ *   - Arabic has a dual as well as a plural, and each inflects the noun
+ *     differently (talab · talabaan · thalaath talabaat, for one, two and
+ *     three orders). No `startsWith` check can produce that
+ *   - And if the project already has an i18n system, this builds a second
+ *     one beside it
+ *
+ * So the library owns the **hook point**, not the translation: it calls `t`
+ * with a key and values, and `t` comes from `NotificationProvider`. Strings
+ * stay in your catalogue, pluralisation stays with the system built for it,
+ * and the library stays unaware of language — exactly as it stays unaware of
+ * what `order.created` means.
+ */
+type NotificationTranslate = (key: string, vars?: Record<string, unknown>) => ReactNode;
+/**
+ * A kind's sound — one chime, or silence.
+ *
+ * `notify` is the only notification chime. It is inlined as a data URI in
+ * `chime.ts`, so there is no file to copy and no path to break when the
+ * library moves to another project. `none` silences the whole kind — for
+ * things worth reading but not worth interrupting for.
+ *
+ * The chime itself is **not swappable**: it is part of Qumra's identity, like
+ * the colours and the typeface. What a project decides is which kinds ring
+ * and which arrive quietly.
+ */
+type NotificationSoundName = 'notify' | 'none';
+/**
+ * A notification kind — the mapping from an event name to its look and sound.
+ *
+ * This is what makes the system portable: the library does not know what
+ * `order.created` means, it knows how to read the registry. Each project
+ * registers its own kinds.
+ */
+interface NotificationKind {
+    /** The event name exactly as the server sends it — `order.created` */
+    kind: string;
+    /** Human-readable name — shown in notification settings and filters */
+    label: string;
+    icon: ComponentType<{
+        size?: number;
+        strokeWidth?: number;
+    }>;
+    /**
+     * Status tone — neutral by default, on purpose.
+     *
+     * This says "this one is worrying", not "this one is from the orders
+     * module". If every kind took a colour, the inbox becomes a rainbow and the
+     * urgent item is lost in it.
+     */
+    tone?: Tone;
+    /** The kind's priority, used when the message does not set one */
+    priority?: NotificationPriority;
+    /**
+     * Whether this kind rings — `notify` by default.
+     *
+     * This is the only decision sound exposes, and it is a product decision,
+     * not an identity one: "app updated" is not worth interrupting for,
+     * "payment failed" is. The chime, its loudness, and its rhythm are fixed in
+     * the library.
+     */
+    sound?: NotificationSoundName;
+    /**
+     * Build the title from `data` instead of the server's text — **optional**.
+     *
+     * ## The problem it solves
+     *
+     * `title` is stored in whatever language was active when it was sent. The
+     * merchant switches language and finds last month's notifications still in
+     * the old one. This happens in Qumra for real — the apps ship in Arabic and
+     * English.
+     *
+     * ## Why it is opt-in and not the default
+     *
+     * If every kind rendered on the client, fixing a wording or a typo would
+     * need a **frontend deploy**. As it stands that is a server-side edit that
+     * lands immediately. So a kind with a template translates, a kind without
+     * takes the server's text — and you adopt it kind by kind, where it earns
+     * its keep.
+     *
+     * An unregistered kind keeps working off the server's text, so the backend
+     * can ship a new kind without waiting for the frontend.
+     *
+     * ## The template calls `t`, it does not translate
+     *
+     * Key and values only. The string lives in your catalogue, and plurals and
+     * inflection are your i18n system's job.
+     *
+     * If the project never passes `t` to the provider, the template is
+     * **ignored** and the server's text is shown — safer than a raw key in
+     * front of a merchant.
+     *
+     * @example
+     * {
+     *   kind: 'order.created',
+     *   title: (n, t) => t('notif.order.created', { id: n.data.orderId }),
+     * }
+     */
+    title?: (n: Notification, t: NotificationTranslate) => ReactNode;
+    /** Same idea as `title`, for the line underneath */
+    body?: (n: Notification, t: NotificationTranslate) => ReactNode;
+}
+/**
+ * A kind after resolution — look and sound guaranteed, templates not.
+ *
+ * A missing `title`/`body` is **meaning**, not absence: it says "use the
+ * server's text". So no default is filled in for them — one would overwrite
+ * text that came from the server with an empty string.
+ */
+interface ResolvedKind extends Required<Omit<NotificationKind, 'title' | 'body'>> {
+    title?: NotificationKind['title'];
+    body?: NotificationKind['body'];
+    /** This kind is not registered, and these values come from the fallback */
+    unknown: boolean;
+}
+interface NotificationKindRegistry {
+    /** Returns the kind, or the fallback with `unknown: true` if unregistered */
+    get: (kind: string) => ResolvedKind;
+    /** Every registered kind — for a notification settings screen */
+    list: () => ResolvedKind[];
+    has: (kind: string) => boolean;
+}
+
+type NotificationParseResult = {
+    ok: true;
+    value: Notification;
+    warnings: string[];
+} | {
+    ok: false;
+    issues: string[];
+};
+interface NotificationBatch {
+    items: Notification[];
+    /** اللي اتعزل — الرسالة الخام وسبب الرفض، عشان يتسجّل مش يتبلع */
+    rejected: {
+        raw: unknown;
+        issues: string[];
+    }[];
+    /** تحذيرات على رسايل عدّت — حقل اتجاهل، إصدار أحدث */
+    warnings: string[];
+}
+/**
+ * بيحقّق رسالة واحدة ويطبّعها.
+ *
+ * المطلوب: `id` و`kind` و`at` و`title`. الباقي بياخد افتراضي.
+ * `at` لازم يكون تاريخ ISO مقروء — الرقم أو النص المكسور بيترفض، لأن
+ * `Invalid Date` بيعدّي صامت وبيطلع «NaN من كذا دقيقة» في الواجهة.
+ */
+interface ParseOptions {
+    /**
+     * سجلّ الأنواع — منه بييجي افتراضي الأولوية لما الرسالة ما تحدّدش.
+     *
+     * من غيره الرسالة اللي مافيهاش `priority` بتاخد `normal` مهما كان
+     * نوعها — يعني `payment.failed` المسجّل `critical` بيوصل عادي،
+     * والسجلّ بيبقى زينة. وده بيكسر أساس النظام: المكتبة مابتعرفش
+     * `order.created` يعني إيه، بتعرف تقرا السجلّ.
+     */
+    kinds?: NotificationKindRegistry;
+}
+declare function parseNotification(raw: unknown, options?: ParseOptions): NotificationParseResult;
+/**
+ * بيحقّق دفعة ويعزل الوحش.
+ *
+ * بيقبل مصفوفة، أو نص JSON، أو كائن فيه `items`/`notifications` —
+ * التلات أشكال اللي الـAPIs بتبعت بيهم. وبيرتّب بالأحدث، وبيلغّي
+ * تكرار الـ`id` (آخر نسخة بتكسب: التحديث بيوصل بنفس المعرّف).
+ */
+declare function parseNotifications(raw: unknown, options?: ParseOptions): NotificationBatch;
+/**
+ * بيرجّع الرسالة لصيغتها على السلك — للتخزين أو إعادة الإرسال.
+ *
+ * عكس `parseNotification` بالظبط: `parse(serialize(n))` بيدّي `n`.
+ * لازم يفضل كده، وإلا الرسالة اللي اتخزّنت مابترجعش زي ما دخلت.
+ */
+declare function serializeNotification(n: Notification): NotificationJSON;
+
+/**
+ * بينشئ سجلّ أنواع.
+ *
+ * @param kinds الأنواع المسجّلة
+ * @param fallback تجاوز الشكل الاحتياطي للنوع المش معروف
+ *
+ * @example
+ * const KINDS = createKindRegistry([
+ *   { kind: 'ticket.assigned', label: 'تذكرة', icon: Ticket, priority: 'critical' },
+ * ])
+ * KINDS.get('ticket.assigned').icon      // Ticket
+ * KINDS.get('حاجة.غريبة').unknown        // true
+ */
+declare function createKindRegistry(kinds: NotificationKind[], fallback?: Partial<Omit<ResolvedKind, 'kind' | 'unknown'>>): NotificationKindRegistry;
+/**
+ * أنواع التجارة الإلكترونية — طقم جاهز لمنتجات قمرة.
+ *
+ * ده **مثال مسجّل** مش جزء من العقد. المشروع التاني بيبني سجلّه
+ * بـ`createKindRegistry` ومابياخدش الطقم ده.
+ *
+ * ── واللون هنا استثناء مش قاعدة ─────────────────────────────────────────
+ * أربعة بس من اتناشر ليهم نغمة: فشل الدفع والمخزون الخالص والطلب
+ * المتعثّر والمرتجع. الباقي محايد. لو كل نوع خد لونه، مافيش حاجة
+ * بتتشاف قبل حاجة — واللون بيبطّل يعني حالة.
+ *
+ * ── و`critical` تلاتة بس ────────────────────────────────────────────────
+ * القاعدة: نزيف **مستمرّ لحد ما حد يتصرّف**. فشل التحصيل والمخزون
+ * الخالص والطلب المتعثّر بيكلّفوا كل يوم بيعدّي؛ المرتجع حصل وخلاص.
+ * والفرق مش أكاديمي: `critical` مابتتمسحش بـ«تعليم الكل»، فلو اتوسّعت
+ * الحماية بتبقى ضجيج مالوش مفتاح إطفاء.
+ *
+ * ── والقوالب على اتنين بس ───────────────────────────────────────────────
+ * `order.created` و`payout.sent` عندهم قالب بينادي `t` بمفتاح وقيم،
+ * فبيترجموا من كتالوج المشروع. الباقي بياخد نصّ السيرفر — عشان تصليح
+ * صياغة يفضل تعديل سيرفر بيوصل فورًا مش نشر فرونت.
+ *
+ * ومن غير `t` على المزوّد، القوالب بتتجاهل والكل بياخد نصّ السيرفر.
+ *
+ * ── والصوت واحد أو ولا حاجة ─────────────────────────────────────────────
+ * النغمة نفسها لكل نوع بيستاهل مقاطعة، و`none` للي بيتقرا ومابيستاهلش:
+ * تحديث تطبيق وملخّص المجتمع. نغمات متعدّدة بتفترض إن التاجر هيحفظ
+ * إن النازلة يعني دفع فشل — وده مابيحصلش، بيسمع رنّة فبيبصّ.
+ * والإلحاح بيتقال بالعلوّ: `critical` بتعلى ٣٥٪.
+ */
+declare const QUMRA_KINDS: NotificationKind[];
+/** سجلّ قمرة جاهز — `QUMRA_NOTIFICATIONS.get('order.created')` */
+declare const QUMRA_NOTIFICATIONS: NotificationKindRegistry;
+
+/** الصوت الوحيد في المكتبة — `none` بتسكّت النوع */
+declare const NOTIFICATION_SOUNDS: Exclude<NotificationSoundName, 'none'>[];
+interface UseNotificationSoundOptions {
+    /** سجلّ الأنواع — منه بييجي صوت كل نوع (`notify` أو `none`) */
+    kinds: NotificationKindRegistry;
+}
+interface NotificationSoundApi {
+    /** الصوت اتفكّ وجاهز — قبلها أي `play` بتتبلع */
+    ready: boolean;
+    muted: boolean;
+    setMuted: (muted: boolean) => void;
+    /**
+     * بيفكّ الصوت — **لازم من معالج حدث مستخدم حقيقي**.
+     *
+     * بتتنادى لوحدها على أول ضغطة لو `autoUnlock`. النداء اليدوي لزرار
+     * «شغّل الصوت» في الإعدادات.
+     */
+    unlock: () => Promise<boolean>;
+    /** بيرنّ حسب النوع — بيحترم الكتم والحدّ الأدنى والأولوية */
+    play: (n: Notification) => void;
+    /** بيرنّ حالاً — لزرار «جرّب الصوت» في الإعدادات */
+    preview: () => void;
+}
+declare function useNotificationSound({ kinds }: UseNotificationSoundOptions): NotificationSoundApi;
+
+interface NotificationsApi {
+    /** كل الرسايل، الأحدث الأول */
+    items: Notification[];
+    /** عدد غير المقروء — ده اللي الجرس بيعرضه */
+    unread: number;
+    /**
+     * غير المقروء اللي «تعليم الكل» مش بيمسحه — الحرج.
+     *
+     * مفصول عن `unread` عن قصد: بعد «تعليم الكل» العدّاد بينزل لكن
+     * مش لصفر، وده بيتقرا عطل لو مافيش رقم تاني بيفسّره. والفصل بيسمح
+     * بوزن بصري مختلف — نقطة حمرا مابتروحش أبداً بترجّع نفس الضغط
+     * اللي بيخلّي التاجر يطفّي الإشعارات.
+     */
+    needsAction: number;
+    /** الوارد لسه — اللي الكروت الطايرة بتعرضه */
+    arrivals: Notification[];
+    /** المرفوض من آخر `hydrate`/`receive` — للتسجيل مش للعرض */
+    rejected: NotificationBatch['rejected'];
+    /**
+     * بيحمّل الموجود من قبل — **صامت وإضافي**.
+     *
+     * بيضيف ويحدّث ومابيشيلش. ده نداء أول تحميل، وتحميل صفحة تانية،
+     * وأي دفعة قديمة.
+     */
+    hydrate: (raw: unknown) => NotificationBatch;
+    /**
+     * مزامنة — **صامتة وبتشيل**.
+     *
+     * زي `hydrate` بس بتشيل كمان اللي السيرفر مابعتوش، **جوّه المدى
+     * الزمني اللي الدفعة بتغطّيه وبس**. فمزامنة الصفحة الأولى مابتمسحش
+     * الصفحات اللي تحتها.
+     */
+    sync: (raw: unknown) => NotificationBatch;
+    /**
+     * بيستقبل وارد جديد — بيرنّ وبيطلع طاير.
+     *
+     * بياخد رسالة واحدة أو دفعة. الرسالة المرفوضة بتتعزل ومابتوقّعش
+     * الباقي.
+     */
+    receive: (raw: unknown) => NotificationBatch;
+    /**
+     * إشعار محلّي من غير سيرفر — بيملى `id` و`at` و`v` لوحده.
+     *
+     * للأفعال اللي التطبيق بيعرف نتيجتها فوراً. بيعدّي على نفس
+     * التحقّق، فالمحلّي مابياخدش طريق جانبي.
+     */
+    push: (input: Omit<NotificationJSON, 'id' | 'at' | 'v'> & {
+        id?: string;
+        at?: string;
+    }) => string | null;
+    markRead: (id: string) => void;
+    markAllRead: () => void;
+    /**
+     * رجّعهم غير مقروئين — للتراجع، ولزرار «علّمه كغير مقروء».
+     *
+     * فعل باسمه زي باقي الـAPI (`dismiss` · `markAllRead` · `sync`)
+     * بدل `setRead(ids, false)`: العلَم البوليان بيخلّي مكان النداء
+     * يحتاج قراية التوقيع عشان يتفهم.
+     */
+    markUnread: (ids: string[]) => void;
+    /** بيلغي شاهد الشيل وبيرجّع الرسالة — للتراجع لما السيرفر يرفض */
+    restore: (n: Notification) => void;
+    /**
+     * السيرفر أكّد الشيل — الشاهد مابقاش لازم.
+     *
+     * من غيرها الشاهد بيستنّى انتهاء صلاحيته على الفاضي، والمجموعة
+     * بتكبر مع كل شيل في الجلسة.
+     */
+    confirmDismiss: (id: string) => void;
+    dismiss: (id: string) => void;
+    clearArrival: (id: string) => void;
+    clearAllArrivals: () => void;
+}
+interface UseNotificationsOptions {
+    /**
+     * سجلّ الأنواع — منه بييجي افتراضي الأولوية.
+     *
+     * من غيره أي رسالة مافيهاش `priority` بتاخد `normal`، فالنوع
+     * المسجّل `critical` بيوصل عادي و`needsAction` بتعدّ غلط.
+     */
+    kinds?: NotificationKindRegistry;
+    /** رسايل أولية — بتتحمّل صامتة زي `hydrate` */
+    initial?: unknown;
+    /** بيتنادى لكل وارد جديد اتقبل — ده مكان الصوت */
+    onReceive?: (n: Notification) => void;
+    /** بيتنادى لما رسالة تترفض — سجّلها، متبلعهاش */
+    onReject?: (rejected: NotificationBatch['rejected']) => void;
+}
+/** `critical` مابيتعلّمش مقروء بـ«تعليم الكل» — «شفته» مش «عالجته» */
+declare const isBulkReadable: (n: Notification) => boolean;
+declare function useNotifications({ kinds, initial, onReceive, onReject, }?: UseNotificationsOptions): NotificationsApi;
+
+/**
+ * تحديث تفاؤلي بتراجع.
+ *
+ * الواجهة بتتغيّر فوراً، والمزامنة بتجري. لو فشلت، `undo` بترجّع
+ * الحالة و`onError` بيقول للمستخدم — لأن التراجع الصامت أوحش من
+ * الفشل نفسه: العدّاد بيرجع يطلع والمستخدم مايعرفش ليه.
+ *
+ * `run` ممكن يرجّع `void` أو وعد، وممكن يرمي متزامن. التلات حالات
+ * بتتعامل واحد — المستدعي اللي مابيزامنش مابيدفعش تمن، واللي
+ * بيزامن مابيحتاجش يلفّ نداءه في `try`.
+ */
+declare function optimistic(run: (() => void | Promise<void>) | undefined, undo: () => void, onError?: (error: unknown) => void): void;
+interface UseNotificationCenterOptions extends UseNotificationsOptions {
+    /** سجلّ الأنواع — بيروح للصوت وبيترجّع عشان يتحطّ في المزوّد */
+    kinds: NotificationKindRegistry;
+    /**
+     * اتقرا إشعار — بالفتح أو بـ«تعليم كمقروء».
+     *
+     * ده مكان المزامنة مع السيرفر. العلامة بتتحطّ **قبل** النداء
+     * (تفاؤلياً) عشان الواجهة ما تستناش الشبكة.
+     *
+     * ── ولو السيرفر رفض ─────────────────────────────────────────────────
+     * ارمي أو رجّع وعداً بيترفض، والمكتبة بترجّع العلامة لوحدها. من
+     * غير كده الواجهة بتوعد بحاجة السيرفر مانفّذهاش: التاجر بيشوف
+     * العدّاد وقع، وبيفتح من جهاز تاني فيلاقيه زي ما هو.
+     *
+     * @example
+     * onRead: async (n) => { await api.markRead(n.id) }   // الفشل بيرجّع العلامة
+     */
+    onRead?: (n: Notification) => void | Promise<void>;
+    /** اتقرا الكل — نداء واحد بدل نداء لكل رسالة. الفشل بيرجّع الكل */
+    onReadAll?: (ids: string[]) => void | Promise<void>;
+    /** اتشال من الصندوق. الفشل بيرجّع الرسالة لمكانها */
+    onDismiss?: (n: Notification) => void | Promise<void>;
+    /**
+     * فشلت مزامنة مع السيرفر واتراجعنا — اعرض توست هنا.
+     *
+     * التراجع الصامت أوحش من الفشل نفسه: العدّاد بيرجع يطلع والمستخدم
+     * مايعرفش ليه.
+     *
+     * و`items` جوّه السياق عشان الرسالة تبقى مفيدة: «تعذّر حفظ قراية»
+     * بتسأل «قراية إيه؟»، و«تعذّر حفظ قراية ٣ إشعارات» بترد.
+     */
+    onSyncError?: (error: unknown, context: {
+        action: 'read' | 'readAll' | 'dismiss';
+        items: Notification[];
+    }) => void;
+    /**
+     * اتضغط إجراء الإشعار — الوجهة في `n.action.href`.
+     *
+     * وصّلها براوترك. الإشعار بيتعلّم مقروء لوحده قبل النداء.
+     */
+    onOpen?: (n: Notification) => void;
+}
+interface NotificationCenter extends NotificationsApi {
+    sound: NotificationSoundApi;
+    /** نفس السجلّ اللي دخل — عشان `NotificationProvider` ياخده من مصدر واحد */
+    kinds: NotificationKindRegistry;
+    /**
+     * الخصائص الجاهزة للمزوّد والأسطح — بتوصّل الفتح والقراءة لوحدها.
+     *
+     * `<NotificationProvider {...inbox.bind.provider}>` بدل ما تكتب
+     * `onAction` و`onOpen` في كل سطح.
+     */
+    bind: {
+        provider: {
+            kinds: NotificationKindRegistry;
+            onAction: (n: Notification) => void;
+        };
+        surface: {
+            items: Notification[];
+            unread: number;
+            needsAction: number;
+            sound: NotificationSoundApi;
+            onMarkAllRead: () => void;
+            onDismiss: (id: string) => void;
+            onOpen: (n: Notification) => void;
+        };
+    };
+}
+/**
+ * الحالة والصوت موصولين — نداء واحد.
+ *
+ * @example
+ * const inbox = useNotificationCenter({
+ *   kinds: QUMRA_NOTIFICATIONS,
+ *   initial: await api.notifications(),   // بيتحمّل صامت
+ * })
+ *
+ * <NotificationProvider kinds={inbox.kinds} onAction={(n) => navigate(n.action.href)}>
+ *   <NotificationMenu unread={inbox.unread} items={inbox.items} sound={inbox.sound} … />
+ *   <NotificationToastHost items={inbox.arrivals} onClose={inbox.clearArrival} />
+ * </NotificationProvider>
+ *
+ * // والوارد من السوكت — بيرنّ وبيطلع طاير
+ * socket.on('notification', inbox.receive)
+ */
+declare function useNotificationCenter({ kinds, onReceive, onRead, onReadAll, onDismiss, onOpen, onSyncError, ...rest }: UseNotificationCenterOptions): NotificationCenter;
+
+/**
+ * الوقت النسبي — «من دقيقتين»، «إمبارح»، «من ٣ شهور».
+ *
+ * أقل من نصّ دقيقة بيتقري «الآن» بدل «قبل ٣٠ ثانية»: الفرق مالوش
+ * معنى للقارئ، والرقم اللي بيتغيّر كل ثانية بيسحب العين. والنصّ من
+ * `Intl` — فبيشتغل على أي لغة من غير ما المكتبة تعرفها.
+ *
+ * @param at وقت الإشعار
+ * @param locale اللغة — الافتراضي `ar`
+ * @param now لحقن الوقت في الاختبار
+ */
+declare function formatRelativeTime(at: Date, locale?: string, now?: Date): string;
+/**
+ * كل كام يجب إعادة الرسم عشان النصّ يفضل صح.
+ *
+ * «من دقيقة» بيبقى غلط بعد دقيقة، و«من ٣ شهور» بيفضل صح لأسبوع.
+ * المؤقّت بيتظبط على دقّة الوحدة بدل ما يشتغل كل ثانية على قايمة
+ * فيها أربعين سطر.
+ */
+declare function relativeTickMs(at: Date, now?: Date): number;
+
+interface NotificationContext {
+    kinds: NotificationKindRegistry;
+    locale: string;
+    t?: NotificationTranslate;
+    onAction?: (n: Notification) => void;
+}
+interface NotificationProviderProps {
+    /** سجلّ الأنواع — الافتراضي سجلّ قمرة */
+    kinds?: NotificationKindRegistry;
+    /** لغة الوقت النسبي — الافتراضي `ar` */
+    locale?: string;
+    /**
+     * دالة الترجمة من نظام مشروعك — لقوالب عناوين الأنواع.
+     *
+     * من غيرها القوالب بتتجاهل ونصّ السيرفر بيتعرض. المكتبة مابتترجمش
+     * بنفسها: بتنادي `t(key, vars)` وبس، فالنصوص بتفضل في كتالوجك
+     * والجمع شغل نظامك.
+     */
+    t?: NotificationTranslate;
+    /**
+     * التنقّل لوجهة الإشعار.
+     *
+     * المكتبة مابتنقّلش بنفسها لأن الرسالة بتحمل `href` مش دالة.
+     * خدها من `n.action.href` ووصّلها لراوترك.
+     */
+    onAction?: (n: Notification) => void;
+    children: ReactNode;
+}
+/** بيوزّع السجلّ واللغة والتنقّل على كل الأسطح — مرّة في الجذر */
+declare function NotificationProvider({ kinds, locale, t, onAction, children, }: NotificationProviderProps): react.JSX.Element;
+declare const useNotificationContext: () => NotificationContext;
+interface NotificationBellProps {
+    unread: number;
+    /**
+     * منهم كام محتاج إجراء — بيغيّر **شكل** العدّاد مش رقمه.
+     *
+     * نقطة حمرا مابتروحش أبداً بترجّع نفس الضغط اللي بيخلّي التاجر
+     * يطفّي الإشعارات. فالعدّاد بيفضل رقم غير المقروء، والحرج بيتعلّم
+     * بحلقة حواليه — علامة تانية على نفس الرقم مش رقم تاني.
+     */
+    needsAction?: number;
+    onClick: () => void;
+    /** بيوصل لـ`aria-expanded` — الجرس اللي بيفتح لوح لازم يقولها */
+    expanded?: boolean;
+    label?: string;
+    /** «٣ غير مقروءة» — الرقم في `aria-label` مش في الشكل وحده */
+    unreadLabel?: (n: number) => string;
+    className?: string;
+}
+/**
+ * زرّ الجرس بعدّاد غير المقروء.
+ *
+ * العدّاد أحمر ومحاط بحلقة من لون الخلفية — من غيرها الرقم بيتلزق في
+ * أي أيقونة وراه وبيتقرا جزء منها. والرقم في `aria-label` كمان: قارئ
+ * الشاشة مابيشوفش الشارة، وجرس بيقول «الإشعارات» وبس بيخلّي اللي بيسمع
+ * يفتح الصندوق كل مرة عشان يعرف فيه جديد ولا لأ.
+ */
+declare function NotificationBell({ unread, needsAction, onClick, expanded, label, unreadLabel, className, }: NotificationBellProps): react.JSX.Element;
+interface NotificationRowProps {
+    item: Notification;
+    /** بيتنادى بعد فتح الوجهة — علّمه مقروء هنا */
+    onOpen?: (n: Notification) => void;
+    onDismiss?: (id: string) => void;
+    dismissLabel?: string;
+    unreadLabel?: string;
+}
+/**
+ * سطر إشعار واحد.
+ *
+ * غير المقروء بيتعلّم بحاجتين: نقطة وخطّ أتقل. اللون وحده مابيكفيش —
+ * واحد من كل اتني عشر راجل مابيفرّقش بين درجتين رماديين صغيّرين،
+ * والوزن بيتقرا بالعين مهما كان.
+ *
+ * والسطر **مش زرار كله**. الصندوق فيه سطور بتفتح وسطور بتتقري وبس،
+ * ولو السطر كله قابل للضغط اللي عايز يقرا بيدوس بالغلط ويلاقي نفسه في
+ * صفحة تانية. الإجراء زرار له اسم.
+ */
+declare function NotificationRow({ item, onOpen, onDismiss, dismissLabel, unreadLabel, }: NotificationRowProps): react.JSX.Element;
+interface NotificationListProps {
+    items: Notification[];
+    onOpen?: (n: Notification) => void;
+    onDismiss?: (id: string) => void;
+    emptyTitle?: ReactNode;
+    emptyDescription?: ReactNode;
+    className?: string;
+}
+/** القايمة نفسها — نفسها في اللوح المنسدل وفي الدرج الجانبي بالظبط */
+declare function NotificationList({ items, onOpen, onDismiss, emptyTitle, emptyDescription, className, }: NotificationListProps): react.JSX.Element;
+interface NotificationPanelProps extends NotificationListProps {
+    title?: ReactNode;
+    unread?: number;
+    /**
+     * غير المقروء اللي «تعليم الكل» مش بيمسحه.
+     *
+     * لازم يتعرض: العدّاد بينزل من ١٢ لـ٢ وبيقف، واللي مايعرفش ليه
+     * بيدوس تاني ومافيش، فبيتقرا عطل. السطر بيقول السبب مرّة واحدة.
+     */
+    needsAction?: number;
+    onMarkAllRead?: () => void;
+    markAllLabel?: string;
+    /** تذييل «عرض الكل» — من غيره الصندوق بيبقى نهاية الطريق */
+    onViewAll?: () => void;
+    viewAllLabel?: string;
+    /** زرّ كتم الصوت في الترويسة — مرّره من `useNotificationSound` */
+    sound?: {
+        muted: boolean;
+        setMuted: (m: boolean) => void;
+        ready: boolean;
+    };
+}
+/**
+ * اللوح المنسدل — صندوق الإشعارات جنب الجرس.
+ *
+ * ارتفاع القايمة محدود و**بيتمرّر جوّه**: اللوح اللي بيطول بطول القايمة
+ * بيوصل لآخر الشاشة وبيقص آخر إشعار من غير ما يبان إنه مقصوص.
+ *
+ * و«تعليم الكل كمقروء» بيختفي لما يبقى مفيش غير مقروء — زرار بيعمل لا
+ * حاجة موجود دايماً بيعلّم المستخدم إن الأزرار هنا مش بترد.
+ */
+declare function NotificationPanel({ items, title, unread, needsAction, onMarkAllRead, markAllLabel, onViewAll, viewAllLabel, sound, onOpen, onDismiss, emptyTitle, emptyDescription, className, }: NotificationPanelProps): react.JSX.Element;
+interface SoundToggleProps {
+    muted: boolean;
+    setMuted: (m: boolean) => void;
+    /** الصوت اتفكّ — قبلها الزرار بيقول إنه مقفول من المتصفّح مش من المستخدم */
+    ready: boolean;
+    className?: string;
+}
+/**
+ * كتم صوت الإشعارات.
+ *
+ * الحالة التالتة مهمة: **مش مكتوم بس المتصفّح لسه قافل**. الزرار
+ * بيقولها بدل ما يدّعي إن الصوت شغّال — والمستخدم اللي مستني رنّة
+ * مش جاية يستاهل يعرف السبب.
+ */
+declare function SoundToggle({ muted, setMuted, ready, className }: SoundToggleProps): react.JSX.Element;
+interface NotificationMenuProps extends Omit<NotificationPanelProps, 'unread'> {
+    unread: number;
+    bellLabel?: string;
+    /**
+     * الحافة اللي اللوح بيتحاذى عليها مع الجرس — الافتراضي `end`.
+     *
+     * الجرس في الشريط العلوي بيبقى ناحية `end`، فاللوح بيتمدّد ناحية
+     * `start` وبيفضل جوّه الشاشة. لو الجرس اتحرّك لازم ده يتقلب.
+     */
+    align?: 'start' | 'end';
+    /**
+     * فوق الجرس ولا تحته — الافتراضي `bottom`.
+     *
+     * الشريط السفلي على الموبايل محتاج `top`: لوح بينزل من جرس على آخر
+     * الشاشة بيطلع كله برّه.
+     */
+    side?: 'top' | 'bottom';
+    className?: string;
+}
+/**
+ * الجرس واللوح كوحدة — ده اللي الشريط العلوي بيحطّه.
+ *
+ * الإغلاق بالضغط برّه وبـEscape. والاتنين لازمين: الضغط برّه هو
+ * المتوقّع بالفأرة، وEscape هو المخرج الوحيد للي ماسك كيبورد.
+ */
+declare function NotificationMenu({ unread, bellLabel, align, side, className, onViewAll, onOpen, ...panel }: NotificationMenuProps): react.JSX.Element;
+interface NotificationDrawerProps extends NotificationListProps {
+    open: boolean;
+    onClose: () => void;
+    title?: ReactNode;
+    unread?: number;
+    /** زي `NotificationPanel` — الشرح لازم يبان على الموبايل كمان */
+    needsAction?: number;
+    onMarkAllRead?: () => void;
+    markAllLabel?: string;
+    closeLabel?: string;
+}
+/**
+ * الدرج الجانبي — نفس الصندوق لكن من حافة الشاشة.
+ *
+ * ليه التنين مش واحد: اللوح المنسدل معلّق في الجرس، وعلى شاشة ٣٦٠
+ * بكسل ده يعني لوح بيغطّي الشاشة وطرفه بره الحافة. والدرج بيفتح من
+ * `inline-end` — الشمال في العربي واليمين في الإنجليزي، لوحده.
+ *
+ * والقايمة جوّاه **هي هي** بلا فرق حرف: اللي شاف إشعاراً على الديسكتوب
+ * وبصّ له على الموبايل لازم يشوف نفس السطر، وإلا بيفتكرهم اتنين.
+ */
+declare function NotificationDrawer({ open, onClose, items, title, unread, needsAction, onMarkAllRead, markAllLabel, closeLabel, onOpen, onDismiss, emptyTitle, emptyDescription, }: NotificationDrawerProps): react.JSX.Element;
+/**
+ * ركن الشاشة اللي الطاير بينزل فيه.
+ *
+ * `start`/`end` منطقية مش يمين وشمال: `end` يعني الشمال في العربي
+ * واليمين في الإنجليزي. الجرس بيقلب مكانه مع اللغة، والإشعار لازم
+ * يقلب معاه — وإلا بيجي من ناحية وبيتخزّن في ناحية تانية.
+ */
+type NotificationPlacement = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+interface NotificationToastHostProps {
+    items: Notification[];
+    onClose: (id: string) => void;
+    onOpen?: (n: Notification) => void;
+    /**
+     * الركن — الافتراضي `top-end` عشان يقع جنب الجرس.
+     *
+     * وخلّيه بعيد عن ركن `ToastHost` (`bottom-start` افتراضاً): التوست
+     * بيقول «الفعل اللي عملته حصل» والإشعار بيقول «حاجة جت من برّه»،
+     * ولو الاتنين طلعوا من نفس المكان بيتقروا طابور واحد.
+     */
+    placement?: NotificationPlacement;
+    /** عرض العمود فوق `sm` — تحتها بياخد العرض كله */
+    width?: string;
+    closeLabel?: string;
+    regionLabel?: string;
+    className?: string;
+}
+/**
+ * الإشعار الطاير — الكرت اللي بينزل لما حاجة توصل.
+ *
+ * `aria-live="polite"` مش `assertive`: الأخير بيقطع قارئ الشاشة في
+ * نصّ الجملة. الإشعار مقاطعة أصلاً، مايستاهلش يقاطع مرتين — اللي بيقرا
+ * هيسمعه لما يخلّص السطر.
+ */
+declare function NotificationToastHost({ items, onClose, onOpen, placement, width, closeLabel, regionLabel, className, }: NotificationToastHostProps): react.JSX.Element | null;
+
+export { NOTIFICATION_PRIORITIES, NOTIFICATION_SCHEMA_VERSION, NOTIFICATION_SOUNDS, type Notification, type NotificationAction, type NotificationBatch, NotificationBell, type NotificationBellProps, type NotificationCenter, NotificationDrawer, type NotificationDrawerProps, type NotificationJSON, type NotificationKind, type NotificationKindRegistry, NotificationList, type NotificationListProps, NotificationMenu, type NotificationMenuProps, NotificationPanel, type NotificationPanelProps, type NotificationParseResult, type NotificationPlacement, type NotificationPriority, NotificationProvider, type NotificationProviderProps, NotificationRow, type NotificationRowProps, type NotificationSoundApi, type NotificationSoundName, NotificationToastHost, type NotificationToastHostProps, type NotificationTranslate, type NotificationsApi, type ParseOptions, QUMRA_KINDS, QUMRA_NOTIFICATIONS, type ResolvedKind, SoundToggle, type SoundToggleProps, type UseNotificationCenterOptions, type UseNotificationSoundOptions, type UseNotificationsOptions, createKindRegistry, formatRelativeTime, isBulkReadable, optimistic, parseNotification, parseNotifications, relativeTickMs, serializeNotification, useNotificationCenter, useNotificationContext, useNotificationSound, useNotifications };