@blogmcp/community 0.1.0 → 0.2.0

package/README.md

@@ -4,13 +4,36 @@ The community elements for your own site, over `@blogmcp/sdk/community`:
 
 - `<blogmcp-discussion>`: the discussion under an article. A two-level thread, the composer, reactions,
   reports, blocks, the inline onboarding, and the states of a member's own messages ("awaiting review",
-  removed, deleted);
+  removed, deleted). Where the tenant asks for the art. 9 consent, the onboarding asks it the way the tenant set
+  it in kb-api: one consent, or one per controller the consent text names, and a refusal that still lets the
+  member write in public where the tenant allows it. Your site passes nothing for this;
 - `<blogmcp-notice-form>`: the notice form for anyone, signed in or not (DSA art. 16), with Cloudflare
   Turnstile;
 - `<blogmcp-my-community>`: the reader's „Moje komunita" panel. It holds statements of reasons and appeals,
-  reports, notifications, the consent, the export and the profile's deletion. It also renders a statement
+  reports, notifications, the consent (to withdraw it, or to give one the member refused), the export and the
+  profile's deletion. It also renders a statement
   page (`decision-id`) and a notifier's status page (`#t=<receipt>` in the address).
 
+With the community module (M2) there are five more:
+
+- `<blogmcp-notification-centre>`: the member's notifications, newest first. Older ones load a page at a time,
+  „Jen nepřečtené" filters them, each one or all can be marked read, and each row links its subject where your
+  site has a page for it (a decision's statement, the settings, „Moje komunita"). It links your settings page;
+- `<blogmcp-badge>`: the unread count for your header, a link to the centre. It asks once who is viewing, then
+  the count every 60 s while the tab is visible and again when it is shown again. It renders nothing for a
+  visitor, a reader who never joined, a module that is off, or nothing unread;
+- `<blogmcp-member-settings>`: the six notification switches (replies, mentions, topics, browser notifications,
+  the daily e-mail digest, the quiet night 22:00–7:00), each saved on its own; this browser's notifications;
+  and the digest e-mail's unsubscribe link (below);
+- `<blogmcp-profile handle="…">`: a member's public profile: name, avatar, since when they are a member, the
+  bio as text and the trust level as a label („Nový člen", „Člen", „Stálý člen", „Moderátor"), never a number;
+- `<blogmcp-welcome>`: the page after joining: the rules in summary and three links (the discussions, the
+  settings, the member's own profile; a visitor gets your sign-in link instead).
+
+`<blogmcp-discussion>` also links every `@handle` in a comment to that member's profile page (for a signed-in
+reader; an anonymous one reads the mention as text), and takes live updates through its `realtime` property
+(below).
+
 Each element lives in a shadow root and renders text only. A member's links pass through `sanitizeUrl` and
 carry `rel="nofollow ugc noopener noreferrer"`. Every text comes from the SDK's catalogue
 (`communityMessage`), in Czech or English.
@@ -74,21 +97,23 @@ import { KbDiscussion } from '@blogmcp/community/react' // a client component
 <KbDiscussion articleId={article.id} apiBase="/api/community" signInHref="/sign-in" />
 ```
 
-`KbNoticeForm` and `KbMyCommunity` work the same way. Each wrapper mounts its element after hydration and
+`KbNoticeForm`, `KbMyCommunity`, `KbNotificationCentre`, `KbBadge`, `KbMemberSettings`, `KbProfile` and
+`KbWelcome` work the same way. Each wrapper mounts its element after hydration and
 removes it on unmount. It renders a single empty `<div data-blogmcp-community="…">` as the mount point: the
 discussion is part of the page's flow, so the element goes where the wrapper is.
 
-`mountDiscussion(o)`, `mountNoticeForm(o)` and `mountMyCommunity(o)` do the same from any client-side hook.
-Each returns the unmount function.
+`mountDiscussion(o)`, `mountNoticeForm(o)`, `mountMyCommunity(o)`, `mountNotificationCentre(o)`, `mountBadge(o)`,
+`mountMemberSettings(o)`, `mountProfile(o)` and `mountWelcome(o)` do the same from any client-side hook. Each
+returns the unmount function.
 
 **Plain HTML**
 
 ```html
 <blogmcp-discussion article-id="…" api-base="/api/community" sign-in-href="/prihlaseni"></blogmcp-discussion>
-<script src="https://cdn.jsdelivr.net/npm/@blogmcp/community@0.1.0/dist/blogmcp-community.global.js" nonce="…"></script>
+<script src="https://cdn.jsdelivr.net/npm/@blogmcp/community@0.2.0/dist/blogmcp-community.global.js" nonce="…"></script>
 ```
 
-The script build (`@blogmcp/community/global`) registers all three elements. It exposes
+The script build (`@blogmcp/community/global`) registers all eight elements. It exposes
 `window.BlogmcpCommunity` and gives the elements its own `nonce`.
 
 ## Attributes
@@ -108,10 +133,22 @@ The script build (`@blogmcp/community/global`) registers all three elements. It
 | | `turnstile-site-key` | your Turnstile site key; without it no widget renders |
 | `<blogmcp-my-community>` | `decision-id` | open this statement of reasons |
 | | `sign-in-href` | your sign-in page |
+| `<blogmcp-notification-centre>` | `sign-in-href` | your sign-in page (a visitor's link) |
+| `<blogmcp-badge>` | `poll-ms` | how often to read the count while the tab is visible (default 60000, and never less — a smaller value reads as 60000; 0 = once, and when the tab is shown again) |
+| `<blogmcp-member-settings>` | `sw-path` | your service worker route (default `${site-base}/sw.js`) |
+| | `sign-in-href` | your sign-in page |
+| `<blogmcp-profile>` | `handle` | the member's handle (an `@` in front is fine) |
+| | `sign-in-href` | your sign-in page (profiles are for signed-in readers) |
+| `<blogmcp-welcome>` | `sign-in-href` | your sign-in page (in the profile link's place, for a visitor) |
 
 `routes` names your community pages: `statementPath` (with `{id}`), `myCommunityPath`, `rulesPath`,
-`reportPath` and `noticesPath`. Each is a full path on your site, used as it is. A page you leave out
-falls back to the managed blog's pages: `${site-base}/community/…`. The tenant's own statement and „Moje
+`reportPath`, `noticesPath` and, with the module, `profilePath` (with `{handle}`), `settingsPath`,
+`notificationsPath`, `welcomePath` and `discussionsPath`. Each is a full path on your site, used as it is. A page you leave out
+falls back to the managed blog's pages: `${site-base}/community/…`. `articlePath` (with `{slug}`; no default)
+is your article page — the managed blogs' `/blog/articles/{slug}`, a shop's `/blog/{slug}`: the notification
+centre links a reply or a mention to its message there (`…/<slug>#bcm-msg-<seq>`), and without it those rows stay
+text. The discussion gives every message the anchor `bcm-msg-<seq>` and, opened at one, scrolls to it itself once
+its first page is in (the rows live in a shadow root, where the browser's own jump cannot reach). The tenant's own statement and „Moje
 komunita" paths, set in its community settings, come before that fallback.
 `consultationPath` (no default) turns the regulated preset's adverse-event note into a link to your
 consultation page.
@@ -120,6 +157,62 @@ as soon as it reads it.
 
 A `transport` property replaces the HTTP layer, for tests.
 
+## Live updates (`realtime`)
+
+The discussion keeps itself fresh by polling. For live updates, import the SDK's realtime entry yourself and pass
+its `createRealtimeSession` as the discussion's `realtime` property (a property, never an attribute). Your bundle
+then needs `centrifuge` (≥ 5.7), the entry's peer dependency; the elements never import either, so a site
+without it ships no socket code.
+
+```ts
+import { createRealtimeSession } from '@blogmcp/sdk/community/realtime'
+import { KbDiscussion } from '@blogmcp/community/react'
+
+<KbDiscussion articleId={article.id} apiBase="/api/community" realtime={createRealtimeSession} />
+// plain: document.querySelector('blogmcp-discussion').realtime = createRealtimeSession
+```
+
+The element starts the session over its own discussion after the first page is read, and stops it when it
+unmounts. It starts none for an anonymous reader, nor while the community's live updates are off (the module is
+`read_only` or off, or the instance runs no realtime): the discussion polls then, with no socket. A session that
+falls back to polling — kb-api answers `REALTIME_OFF`, or the server ends the connection for good — makes the
+discussion say once that live updates are off; it is never reopened. When the session was revoked (4501), the
+session asks kb-api for a fresh token once first: a member whose own password change ended the old session keeps
+the page live under the new one; a refusal, or a second 4501, falls back for good. While the socket cannot get
+through (the subscription is not live 15 s after connecting, or after the connection dropped), the discussion polls
+meanwhile and says so once; Centrifuge keeps reconnecting, and the sentence goes when it is live again. An article
+without comments yet has no channel to subscribe to: it polls for the first one and is never called off for that.
+
+The composer knows the member's mention limit (`me/get`'s `caps.mentionsPerMessage`, by trust level): a comment
+that mentions more distinct `@handle`s says so as it is typed and is not sent (kb-api refuses it too).
+
+The URL to connect to comes from kb-api's token answer (the instance's own host, `/rt/…`), never from your
+configuration.
+
+## Browser notifications and the digest's unsubscribe link
+
+`<blogmcp-member-settings>` shows this browser's notifications only while the community offers them. „Zapnout
+upozornění" (the member's click; nothing is registered on page load) registers **your** service worker at
+`sw-path`, asks the member's permission, subscribes the browser and hands the subscription to kb-api; „Vypnout"
+ends it. Serve the worker from `@blogmcp/sdk/community/sw` (`communityServiceWorkerSource`, as
+`COMMUNITY_SW_CONTENT_TYPE`, `Cache-Control: no-cache`) at that route, and the manifest from
+`@blogmcp/sdk/community/manifest`. Inside Facebook's or Instagram's app the element offers „Otevřít v prohlížeči"
+with the page's URL instead; on an iPhone or iPad it explains that the site must be added to the home screen first.
+After a key rotation (or kb-api's „switch it on again" notice) it asks the member to switch them on again. The
+switch reads on only for a subscription this member made in this browser (a shared browser shows another member's
+as off) and that kb-api still holds: with the permission granted, the element asks kb-api on load whether it still
+holds this browser's endpoint (`me/push/status` — a read: no worker registered, no permission asked, nothing
+subscribed). kb-api drops a subscription after a sign-out everywhere or a dead endpoint without telling the page;
+the switch then reads off and stays off until the member presses „Zapnout upozornění" — a sign-out everywhere never
+brings notifications back on its own. When kb-api cannot answer (the status, or the current key's `me/push/vapid` that is checked first), the switch
+reads off too, without a sentence. The element also clears `#u=` from the address when
+it is misconfigured and renders nothing.
+
+The digest e-mail links to your settings page with the unsubscribe token in the fragment (`#u=…`). The element
+reads it once, clears it from the address bar, and sends it only when the member clicks „Odhlásit denní souhrn"
+(a mail scanner that opens the link unsubscribes nobody). That works without a session. Route your settings page
+(`settingsPath`) where kb-api's e-mails point.
+
 Events (bubbling, composed):
 - `bcm-posted`, `{ state: 'visible' | 'held' }`: the reader's comment went out;
 - `bcm-notice-submitted`, `{ contactKept }`: a notice was received.
@@ -134,7 +227,9 @@ The properties are `--bcm-bg`, `-fg`, `-muted`, `-line`, `-soft`, `-accent`, `-a
 ## Content Security Policy
 
 - The styles are one `<style>` in each shadow root, carrying the nonce you pass.
-- `connect-src 'self'` is enough: the elements only talk to your own base.
+- `connect-src 'self'` is enough: the elements only talk to your own base. With live updates on a headless
+  site, add your instance's host (`https://<instance host>` and `wss://<instance host>`): the socket goes there.
+- Browser notifications need `worker-src 'self'` (and `manifest-src 'self'` for the manifest).
 - The notice form with Turnstile needs `script-src` and `frame-src` for `https://challenges.cloudflare.com`.
   Only a page with the notice form loads that script.
 
@@ -143,5 +238,7 @@ The properties are `--bcm-bg`, `-fg`, `-muted`, `-line`, `-soft`, `-accent`, `-a
 ```bash
 npm run build       # ESM + the <script> build (+ size budget, 200 KiB gzip)
 npm test            # vitest (happy-dom): controllers, store, onboarding, outcomes, elements, text-only and closed-path scans
-npm run test:e2e    # Playwright: desktop + iPhone profile + a plain bundler, mocked community API (ports 8286/8287)
+npm run test:e2e    # Playwright: desktop + iPhone profile + a plain bundler, mocked community API (ports 8286/8287);
+                    # m2.e2e.ts drives the centre (its link to a reply's message), the badge, the settings,
+                    # a profile, the welcome page and the composer's mention limit
 ```