@blogmcp/community 0.2.0 → 0.3.0

package/README.md

@@ -26,10 +26,42 @@ With the community module (M2) there are five more:
   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;
+  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).
@@ -97,23 +129,27 @@ import { KbDiscussion } from '@blogmcp/community/react' // a client component
 <KbDiscussion articleId={article.id} apiBase="/api/community" signInHref="/sign-in" />
 ```
 
-`KbNoticeForm`, `KbMyCommunity`, `KbNotificationCentre`, `KbBadge`, `KbMemberSettings`, `KbProfile` and
-`KbWelcome` 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)`, `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.
+`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.2.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 eight 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
@@ -140,10 +176,22 @@ The script build (`@blogmcp/community/global`) registers all eight elements. It
 | `<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`, `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
+`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
@@ -160,7 +208,9 @@ 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
+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.
 
@@ -214,7 +264,8 @@ reads it once, clears it from the address bar, and sends it only when the member
 (`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
@@ -237,8 +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 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
+                    # 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)
 ```