@blogmcp/community 0.1.0 → 0.3.0

package/README.md

@@ -4,13 +4,68 @@ 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", „Důvěryhodný člen"), never a
+  number; with the forum, „Moderátor" and the categories the member moderates now (an appointment, not a trust
+  level);
+- `<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).
+
+With the forum (M3) there are six more. The forum is for members only: a visitor reads one sentence and your
+sign-in link, a member short of the onboarding „Vstoupit do komunity" (the onboarding opens in place; a forum write
+needs the art. 9 consent whatever the tenant asks elsewhere).
+
+- `<blogmcp-forum>`: the forum's index. The categories in the team's order, each with its count, its latest
+  topics and the link to all of them, and a search box that opens your search page with the query in the
+  address's fragment (`#q=…`, never the query string);
+- `<blogmcp-forum-category slug="…">`: a category's topics, by activity or newest, pinned first, more a page at
+  a time. Where members open topics, the new-topic composer (a title of at most 200 characters, the opening post,
+  the link to the rules); a topic that waits for review says so and lists for its author only. In „Články" the
+  rows are the article discussions, each with its follow button;
+- `<blogmcp-topic conversation-id="…">`: a topic's page. The header (title, category, closed, pinned, count),
+  the thread in the forum's words („příspěvek", where an article's discussion says „komentář"), the composer,
+  reactions, reports, the follow button and, for the opening post's author, the title's edit. A moderator of the
+  topic's category gets its menu: close or reopen it, pin it, move it, remove a message (with the rule and the
+  facts; the author gets a statement of reasons) or pass a message to the team;
+- `<blogmcp-forum-search>`: the forum's search, as text. It reads the query from `#q=…`; a query shorter than two
+  characters is said, never sent;
+- `<blogmcp-follow-button target-kind="…" target-id="…">`: follow a topic or an article discussion
+  (`conversation`) or a category (`category`). A follow the member may not have reads „not available"; an unfollow
+  never fails;
+- `<blogmcp-forum-moderation>`: a category moderator's queue. The package of each case as text, the decision with
+  its statement previewed before it is decided, a matter passed to the team, the messages waiting for review
+  published or refused. It renders nothing for a member who moderates nothing.
+
+A missing title reads one of three ways: „Smazané téma" only when the opening post was deleted, its own words
+while it is withheld from the viewer, and its title with „Čeká na kontrolu" for the author of a topic waiting for
+review. The forum's own brake pauses the forum's writes only, the article discussions' brake the discussions only
+(the module's brake both); while the team is away the forum says so in one sentence.
+
+`<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 +129,27 @@ 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`,
+`KbWelcome` and the forum's `KbForum`, `KbForumCategory`, `KbTopic`, `KbForumSearch`, `KbFollowButton` and
+`KbForumModeration` 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)`, `mountWelcome(o)` and the forum's `mountForum(o)`,
+`mountForumCategory(o)`, `mountTopic(o)`, `mountForumSearch(o)`, `mountFollowButton(o)` and
+`mountForumModeration(o)` do the same from any client-side hook. Each returns the unmount function. The tag names
+are exported too (`DISCUSSION_ELEMENT_TAG` … `FORUM_MODERATION_ELEMENT_TAG`), and `defineForumElement()` and its
+siblings register one element alone.
 
 **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.3.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 fourteen elements. It exposes
 `window.BlogmcpCommunity` and gives the elements its own `nonce`.
 
 ## Attributes
@@ -108,10 +169,34 @@ 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) |
+| `<blogmcp-forum>` | `sign-in-href` | your sign-in page (a visitor's link) |
+| `<blogmcp-forum-category>` | `slug` | the category's slug |
+| | `sign-in-href` | your sign-in page |
+| `<blogmcp-topic>` | `conversation-id` | the topic (its conversation id) |
+| | `sign-in-href` | your sign-in page |
+| | `poll-ms` | how often to check for new posts while the topic is in view (default 20000; 0 = off) |
+| `<blogmcp-forum-search>` | `sign-in-href` | your sign-in page |
+| `<blogmcp-follow-button>` | `target-kind` | `conversation` (a topic, an article discussion) or `category` |
+| | `target-id` | its id |
+| | `following` | `true` / `false` when your page knows it (left out: the element reads the member's follows) |
+| `<blogmcp-forum-moderation>` | `category-id` | one of the moderator's categories only (left out: all of them) |
 
 `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`, and with the forum `forumPath`, `categoryPath` (with
+`{slug}`), `topicPath` (with `{id}`, the topic's conversation id) and `searchPath`. 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,8 +205,67 @@ 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) — or the
+topic's: `<blogmcp-topic>` takes it the same way (a change of the topic's header, its title or state, reads the
+topic again). 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-posted`, `{ state: 'visible' | 'held' }`: the reader's comment (or, in a topic, post) went out;
+- `bcm-topic-created`, `{ conversationId, state: 'visible' | 'held' }`: the member opened a topic;
 - `bcm-notice-submitted`, `{ contactKept }`: a notice was received.
 
 ## Look
@@ -134,7 +278,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.
 
@@ -142,6 +288,9 @@ 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 test            # vitest (happy-dom): controllers, store, onboarding, outcomes, elements, the forum's six, text-only and closed-path scans
+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; plain-bundler.e2e.ts mounts
+                    # M1's, M2's and the forum's elements from dist/ (a topic opened from a category included)
 ```