@hobbit254/notify-react 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Mkenya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @hobbit254/notify-react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hooks and drop-in components (`NotificationBell`, `InboxDrawer`) for [Notify](https://notify.hobbit254.org) in-app notifications, built on [`@hobbit254/notify-core`](https://www.npmjs.com/package/@hobbit254/notify-core).
+
+```sh
+npm install @hobbit254/notify-core @hobbit254/notify-react
+```
+
+```tsx
+import { Notify } from '@hobbit254/notify-core';
+import { NotificationBell, NotifyProvider } from '@hobbit254/notify-react';
+import '@hobbit254/notify-react/styles.css';
+
+const notify = new Notify({
+  apiUrl: 'https://notify.hobbit254.org',
+  tokenProvider: () => fetch('/api/notify-token').then((r) => r.text()),
+});
+
+export function Header() {
+  return (
+    <NotifyProvider client={notify}>
+      <NotificationBell />
+    </NotifyProvider>
+  );
+}
+```
+
+Headless: use `useInbox()`, `useUnreadCount()` and `usePreferences()` and skip the stylesheet. Theme with the `--notify-*` CSS variables. Details: [docs/SDK.md](https://github.com/hobbit254/in_app_notification/blob/main/docs/SDK.md).
+
+MIT licensed.

package/dist/components.d.ts

@@ -0,0 +1,19 @@
+import { type ReactNode } from 'react';
+import type { InboxItem } from '@hobbit254/notify-core';
+export interface InboxDrawerProps {
+    onClose?: () => void;
+    /** Shows a settings button in the header. */
+    onOpenPreferences?: () => void;
+    /** Shows "View all" in the footer. */
+    viewAllHref?: string;
+    /** Replaces the default item rendering. */
+    renderItem?: (item: InboxItem) => ReactNode;
+    title?: string;
+}
+/** The inbox panel: tabs, list, mark all read, connection status. A dialog with a focus trap. */
+export declare function InboxDrawer({ onClose, onOpenPreferences, viewAllHref, renderItem, title }: InboxDrawerProps): import("react").JSX.Element;
+export interface NotificationBellProps extends Omit<InboxDrawerProps, 'onClose'> {
+    label?: string;
+}
+/** A bell button with the unread badge that opens the InboxDrawer. */
+export declare function NotificationBell({ label, ...drawer }: NotificationBellProps): import("react").JSX.Element;

package/dist/hooks.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+import type { Notify } from '@hobbit254/notify-core';
+/** What the hooks and components need from a client (a Notify instance). */
+export type NotifyClient = Pick<Notify, 'state' | 'subscribe' | 'start' | 'stop' | 'markRead' | 'archive' | 'markAllRead' | 'loadArchived' | 'getPreferences' | 'setPreferences'>;
+/** Starts the client while mounted and makes it available to the hooks and components below. */
+export declare function NotifyProvider({ client, children }: {
+    client: NotifyClient;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<NotifyClient | null>>;
+export declare function useNotify(): NotifyClient;
+/** The inbox (newest first) with its actions. */
+export declare function useInbox(): {
+    items: import("@hobbit254/notify-core").InboxItem[];
+    unread: number;
+    status: import("@hobbit254/notify-core").Status;
+    transport?: import("@hobbit254/notify-core").TransportName;
+    markRead: (id: string) => Promise<void>;
+    archive: (id: string) => Promise<void>;
+    markAllRead: () => Promise<void>;
+    loadArchived: () => Promise<void>;
+};
+export declare function useUnreadCount(): number;
+/** The subscriber's category opt-ins, loaded on mount. */
+export declare function usePreferences(): {
+    categories: Record<string, boolean> | null;
+    loading: boolean;
+    error: Error | null;
+    update: (next: Record<string, boolean>) => Promise<void>;
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { NotifyProvider, useNotify, useInbox, useUnreadCount, usePreferences, type NotifyClient } from './hooks';
+export { NotificationBell, InboxDrawer, type NotificationBellProps, type InboxDrawerProps } from './components';

package/dist/index.js

@@ -0,0 +1 @@
+import{createContext as S,createElement as L,useCallback as x,useContext as B,useEffect as k,useState as g,useSyncExternalStore as $}from"react";var C=S(null);function U({client:e,children:r}){return k(()=>(e.start().catch(()=>{}),()=>e.stop()),[e]),L(C.Provider,{value:e},r)}function p(){let e=B(C);if(!e)throw new Error("useNotify: wrap your app in <NotifyProvider client={\u2026}>");return e}function w(e){let r=p(),t=x(o=>r.subscribe(o),[r]);return $(t,()=>e(r.state),()=>e(r.state))}function m(){let e=p();return{...w(t=>t),markRead:t=>e.markRead(t),archive:t=>e.archive(t),markAllRead:()=>e.markAllRead(),loadArchived:()=>e.loadArchived()}}function b(){return w(e=>e.unread)}function H(){let e=p(),[r,t]=g(null),[o,s]=g(null);k(()=>{let l=!0;return e.getPreferences().then(u=>l&&t(u.categories),u=>l&&s(u)),()=>{l=!1}},[e]);let i=x(async l=>{t(l);try{t((await e.setPreferences(l)).categories)}catch(u){s(u)}},[e]);return{categories:r,loading:r===null&&!o,error:o,update:i}}import{useEffect as K,useRef as T,useState as h}from"react";import{jsx as a,jsxs as c}from"react/jsx-runtime";var I=typeof Intl<"u"?new Intl.RelativeTimeFormat(void 0,{numeric:"auto"}):void 0;function O(e,r=Date.now()){let t=Math.round((new Date(e).getTime()-r)/1e3),[o,s]=Math.abs(t)<60?[t,"second"]:Math.abs(t)<3600?[Math.round(t/60),"minute"]:Math.abs(t)<86400?[Math.round(t/3600),"hour"]:[Math.round(t/86400),"day"];return I?I.format(o,s):new Date(e).toLocaleString()}var F={idle:"Not connected",connecting:"Connecting\u2026",online:"Live",offline:"Offline \xB7 showing saved notifications"},q=()=>c("svg",{width:"20",height:"20",viewBox:"0 0 24 24","aria-hidden":"true",fill:"none",stroke:"currentColor",strokeWidth:"1.8",strokeLinecap:"round",strokeLinejoin:"round",children:[a("path",{d:"M6 8a6 6 0 1 1 12 0c0 7 3 9 3 9H3s3-2 3-9"}),a("path",{d:"M10.3 21a1.94 1.94 0 0 0 3.4 0"})]});function _({item:e,onRead:r,onArchive:t}){let o=e.payload,s=e.state==="unread",i=o.title??e.template??"Notification";return c("article",{className:`notify-item${s?" notify-item--unread":""}`,"aria-label":`${s?"Unread: ":""}${i}`,children:[a("span",{className:"notify-avatar","aria-hidden":"true",children:(o.category??i).slice(0,1).toUpperCase()}),c("div",{className:"notify-item-body",children:[a("button",{type:"button",className:"notify-item-title",onClick:r,children:i}),o.body&&a("p",{className:"notify-item-text",children:o.body}),c("p",{className:"notify-item-meta",children:[o.category&&a("span",{className:"notify-chip",children:o.category}),a("time",{dateTime:e.created_at,children:O(e.created_at)})]}),o.url&&a("a",{className:"notify-item-action",href:o.url,onClick:r,children:"Open"})]}),s&&a("span",{className:"notify-dot","aria-hidden":"true"}),e.state!=="archived"&&a("button",{type:"button",className:"notify-icon-button","aria-label":`Archive: ${i}`,onClick:t,children:"\xD7"})]})}function E({onClose:e,onOpenPreferences:r,viewAllHref:t,renderItem:o,title:s="Notifications"}){let i=m(),[l,u]=h("all"),[P,R]=h(!1),d=T(null);K(()=>{let n=document.activeElement;return d.current?.querySelector("button, a[href]")?.focus(),()=>n?.focus?.()},[]);let A=n=>{if(n.key==="Escape")n.stopPropagation(),e?.();else if(n.key==="Tab"&&d.current){let f=[...d.current.querySelectorAll('button, a[href], [tabindex="0"]')];if(!f.length)return;let[v,N]=[f[0],f[f.length-1]];n.shiftKey&&document.activeElement===v?(n.preventDefault(),N.focus()):!n.shiftKey&&document.activeElement===N&&(n.preventDefault(),v.focus())}},M=n=>{u(n),n==="archived"&&!P&&(R(!0),i.loadArchived())},y=i.items.filter(n=>l==="archived"?n.state==="archived":n.state!=="archived"&&(l==="all"||n.state==="unread")),D={all:"You're all caught up.",unread:"No unread notifications.",archived:"Nothing archived."}[l];return c("div",{ref:d,className:"notify-drawer",role:"dialog","aria-modal":"true","aria-label":s,onKeyDown:A,children:[c("div",{className:"notify-drawer-header",children:[a("h2",{children:s}),a("button",{type:"button",className:"notify-link-button",onClick:()=>i.markAllRead(),disabled:i.unread===0,children:"Mark all read"}),r&&a("button",{type:"button",className:"notify-icon-button","aria-label":"Notification settings",onClick:r,children:"\u2699"})]}),a("div",{className:"notify-tabs",role:"tablist","aria-label":"Filter",children:["all","unread","archived"].map(n=>a("button",{type:"button",role:"tab","aria-selected":l===n,className:"notify-tab",onClick:()=>M(n),children:n==="all"?"All":n==="unread"?`Unread (${i.unread})`:"Archived"},n))}),a("div",{className:"notify-list",role:y.length?"feed":void 0,"aria-busy":i.status==="connecting",children:y.length===0?a("p",{className:"notify-empty",children:D}):y.map(n=>o?a("article",{children:o(n)},n.id):a(_,{item:n,onRead:()=>i.markRead(n.id),onArchive:()=>i.archive(n.id)},n.id))}),c("div",{className:"notify-drawer-footer",children:[a("span",{className:`notify-status notify-status--${i.status}`,role:"status",children:F[i.status]}),t&&a("a",{href:t,children:"View all"})]})]})}function V({label:e="Notifications",...r}){let t=b(),[o,s]=h(!1),i=T(null),l=()=>{s(!1),i.current?.focus()};return c("div",{className:"notify-bell-anchor",children:[c("button",{ref:i,type:"button",className:"notify-bell","aria-label":`${e}, ${t} unread`,"aria-expanded":o,"aria-haspopup":"dialog",onClick:()=>s(!o),children:[a(q,{}),t>0&&a("span",{className:"notify-badge","aria-hidden":"true",children:t>99?"99+":t})]}),o&&a(E,{...r,title:e,onClose:l})]})}export{E as InboxDrawer,V as NotificationBell,U as NotifyProvider,m as useInbox,p as useNotify,H as usePreferences,b as useUnreadCount};

package/dist/styles.css

@@ -0,0 +1,70 @@
+/* @hobbit254/notify-react default theme (docs/UI.md). Override any --notify-* variable to theme; skip this file
+   and use the hooks for a fully custom (headless) UI. */
+.notify-bell-anchor {
+  --notify-font: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  --notify-ink: #17191f;
+  --notify-secondary: #4b5361;
+  --notify-muted: #6b7280;
+  --notify-border: #dde1e8;
+  --notify-surface: #ffffff;
+  --notify-canvas: #f5f6f8;
+  --notify-accent: #1f4fd8;
+  --notify-accent-tint: #eef2ff;
+  --notify-unread-tint: #f5f7ff;
+  --notify-success: #15803d;
+  --notify-warning: #b45309;
+  --notify-danger: #b91c1c;
+  --notify-radius: 12px;
+  position: relative;
+  display: inline-block;
+  font-family: var(--notify-font);
+}
+.notify-bell {
+  position: relative; display: inline-flex; align-items: center; justify-content: center;
+  min-width: 40px; min-height: 40px; border: 1px solid var(--notify-border); border-radius: 10px;
+  background: var(--notify-surface); color: var(--notify-ink); cursor: pointer;
+}
+.notify-bell:focus-visible, .notify-drawer :focus-visible { outline: 2px solid var(--notify-accent); outline-offset: 2px; }
+.notify-badge {
+  position: absolute; top: -6px; right: -6px; min-width: 18px; height: 18px; padding: 0 5px; border-radius: 9px;
+  background: var(--notify-danger); color: #fff; font-size: 11.5px; font-weight: 600; line-height: 18px; text-align: center;
+}
+.notify-drawer {
+  position: absolute; right: 0; top: calc(100% + 8px); z-index: 1000; display: flex; flex-direction: column;
+  width: min(400px, calc(100vw - 32px)); height: 536px; max-height: calc(100vh - 80px);
+  background: var(--notify-surface); color: var(--notify-ink); border: 1px solid var(--notify-border);
+  border-radius: var(--notify-radius); box-shadow: 0 12px 32px rgba(23, 25, 31, 0.14); font: 13px/1.45 var(--notify-font);
+}
+.notify-drawer-header { display: flex; align-items: center; gap: 8px; padding: 14px 16px 8px; }
+.notify-drawer-header h2 { flex: 1; margin: 0; font-size: 15px; font-weight: 600; }
+.notify-link-button { min-height: 40px; border: 0; background: none; color: var(--notify-accent); font: inherit; font-weight: 500; cursor: pointer; }
+.notify-link-button:disabled { color: var(--notify-muted); cursor: default; }
+.notify-icon-button { min-width: 40px; min-height: 40px; border: 0; border-radius: 8px; background: none; color: var(--notify-secondary); font-size: 16px; cursor: pointer; }
+.notify-icon-button:hover { background: var(--notify-canvas); }
+.notify-tabs { display: flex; gap: 4px; padding: 0 12px; border-bottom: 1px solid var(--notify-border); }
+.notify-tab { min-height: 40px; padding: 0 10px; border: 0; border-bottom: 2px solid transparent; background: none; color: var(--notify-secondary); font: inherit; cursor: pointer; }
+.notify-tab[aria-selected="true"] { color: var(--notify-ink); border-bottom-color: var(--notify-accent); font-weight: 600; }
+.notify-list { flex: 1; overflow-y: auto; }
+.notify-item { position: relative; display: flex; gap: 12px; padding: 12px 16px; border-bottom: 1px solid #e6e9ef; }
+.notify-item--unread { background: var(--notify-unread-tint); }
+.notify-avatar {
+  flex: none; width: 36px; height: 36px; border-radius: 50%; display: flex; align-items: center; justify-content: center;
+  background: var(--notify-accent-tint); color: var(--notify-accent); font-weight: 600;
+}
+.notify-item-body { flex: 1; min-width: 0; }
+.notify-item-title { display: block; padding: 0; border: 0; background: none; color: var(--notify-ink); font: inherit; font-weight: 600; text-align: left; cursor: pointer; }
+.notify-item-text { margin: 2px 0 0; color: var(--notify-secondary); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.notify-item-meta { display: flex; align-items: center; gap: 8px; margin: 6px 0 0; color: var(--notify-muted); font-size: 11.5px; }
+.notify-chip { padding: 1px 8px; border-radius: 999px; background: var(--notify-canvas); color: var(--notify-secondary); }
+.notify-item-action { display: inline-block; margin-top: 6px; color: var(--notify-accent); font-weight: 500; }
+.notify-dot { position: absolute; top: 18px; right: 52px; width: 8px; height: 8px; border-radius: 50%; background: var(--notify-accent); }
+.notify-empty { margin: 48px 16px; color: var(--notify-muted); text-align: center; }
+.notify-drawer-footer { display: flex; justify-content: space-between; align-items: center; padding: 10px 16px; border-top: 1px solid var(--notify-border); font-size: 11.5px; }
+.notify-drawer-footer a { color: var(--notify-accent); }
+.notify-status { color: var(--notify-muted); }
+.notify-status--online { color: var(--notify-success); }
+.notify-status--offline { color: var(--notify-warning); }
+@media (max-width: 480px) {
+  .notify-drawer { position: fixed; inset: auto 16px 16px; width: auto; }
+  .notify-bell, .notify-icon-button, .notify-tab, .notify-link-button { min-height: 44px; }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@hobbit254/notify-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.2",
+  "description": "React hooks and drop-in components (NotificationBell, InboxDrawer) for Notify",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hobbit254/in_app_notification.git",
+    "directory": "packages/react"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "*.css"
+  ],
+  "peerDependencies": {
+    "@hobbit254/notify-core": "^0.2.0",
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@hobbit254/notify-core": "0.2.0",
+    "@testing-library/react": "16.3.3",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "esbuild": "0.28.2",
+    "jsdom": "31.0.0",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2",
+    "vitest": "5.1.0"
+  },
+  "scripts": {
+    "build": "esbuild src/index.tsx --bundle --format=esm --target=es2020 --minify --jsx=automatic --external:react --external:react/jsx-runtime --external:@hobbit254/notify-core --outfile=dist/index.js && cp src/styles.css dist/styles.css && tsc -p tsconfig.json --emitDeclarationOnly",
+    "test": "vitest run"
+  }
 }