@blogmcp/community 0.0.0-stage → 0.1.0

package/src/core/download.ts

@@ -0,0 +1,21 @@
+/** The member's export as a file the browser saves (§8.3: the download is the SDK's). Nothing leaves the page. */
+export function saveJson(data: unknown, fileName: string): void {
+  if (typeof document === 'undefined' || typeof URL.createObjectURL !== 'function') return
+  const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = fileName
+  a.style.display = 'none'
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+  setTimeout(() => URL.revokeObjectURL(url), 1000)
+}
+
+/** `<name>-YYYY-MM-DD.json`, the name being the catalogue's (`panel.exportFileName`). */
+export function exportFileName(name: string, now: Date = new Date()): string {
+  const day = now.toISOString().slice(0, 10)
+  const safe = name.replace(/[^\p{L}\p{N}_-]+/gu, '-').replace(/^-+|-+$/g, '') || 'export'
+  return `${safe}-${day}.json`
+}

package/src/core/format.ts

@@ -0,0 +1,90 @@
+/**
+ * Dates and a statement's territorial scope as the reader's language writes them (Intl does the words; the
+ * catalogue holds the sentence around them).
+ */
+import { translator, type Lang } from './i18n'
+
+/** The Intl locale a language reads. */
+const localeOf = (lang: Lang): string => (lang === 'cs' ? 'cs-CZ' : 'en-GB')
+
+const formats = new Map<string, Intl.DateTimeFormat | null>()
+
+function format(lang: Lang, withTime: boolean): Intl.DateTimeFormat | null {
+  const key = `${lang}:${withTime ? 't' : 'd'}`
+  if (!formats.has(key)) {
+    let f: Intl.DateTimeFormat | null = null
+    try {
+      f = new Intl.DateTimeFormat(localeOf(lang), withTime ? { dateStyle: 'medium', timeStyle: 'short' } : { dateStyle: 'long' })
+    } catch {
+      // A runtime without Intl: the ISO text stays.
+    }
+    formats.set(key, f)
+  }
+  return formats.get(key) ?? null
+}
+
+/** An ISO timestamp as a date (and time); '' for anything that is no date. */
+export function formatDate(lang: Lang, iso: string | null | undefined, withTime = true): string {
+  if (typeof iso !== 'string' || iso === '') return ''
+  const at = Date.parse(iso)
+  if (!Number.isFinite(at)) return ''
+  return format(lang, withTime)?.format(new Date(at)) ?? iso
+}
+
+/** Whether an ISO timestamp lies in the past (an appeal window, a sanction's end). */
+export function isPast(iso: string | null | undefined, now: number = Date.now()): boolean {
+  if (typeof iso !== 'string') return false
+  const at = Date.parse(iso)
+  return Number.isFinite(at) && at <= now
+}
+
+/** `trust.decisions.territorial_scope`'s other shape: ISO 3166-1 alpha-2 codes, comma-separated (its CHECK). */
+const REGION_LIST = /^[A-Z]{2}(?:,[A-Z]{2})*$/
+
+const regionNames = new Map<Lang, Intl.DisplayNames | null>()
+const regionLists = new Map<Lang, Intl.ListFormat | null>()
+
+function cached<T>(cache: Map<Lang, T | null>, lang: Lang, make: (locale: string) => T): T | null {
+  if (!cache.has(lang)) {
+    let value: T | null = null
+    try {
+      value = make(localeOf(lang))
+    } catch {
+      // A runtime without this part of Intl: the codes stay.
+    }
+    cache.set(lang, value)
+  }
+  return cache.get(lang) ?? null
+}
+
+/** A region's name in the language (`CZ` → „Česko"), or the code when Intl has none. */
+function regionName(lang: Lang, code: string): string {
+  try {
+    return cached(regionNames, lang, (locale) => new Intl.DisplayNames(locale, { type: 'region' }))?.of(code) || code
+  } catch {
+    return code
+  }
+}
+
+/**
+ * A statement's territorial scope (DSA art. 17(3)(a)) as the reader reads it. kb-api stores `all` — the measure
+ * applies without a territorial limit, the catalogue's `statement.scopeAll` — or the regions it is limited to as
+ * ISO 3166-1 alpha-2 codes (`CZ,SK`), which Intl names and joins („Česko a Slovensko"; a runtime without Intl reads
+ * `CZ, SK`). Any other value — one a newer kb-api sends — is shown as it came, never dropped and never an
+ * exception; '' when there is none.
+ */
+export function formatTerritorialScope(lang: Lang, scope: string | null | undefined): string {
+  if (typeof scope !== 'string') return ''
+  const value = scope.trim()
+  if (value === 'all') {
+    const t = translator(lang)
+    return t('statement.scopeAll')
+  }
+  if (!REGION_LIST.test(value)) return value
+  const names = value.split(',').map((code) => regionName(lang, code))
+  try {
+    return cached(regionLists, lang, (locale) => new Intl.ListFormat(locale, { type: 'conjunction' }))?.format(names) ?? names.join(', ')
+  } catch {
+    return names.join(', ')
+  }
+}

package/src/core/i18n.ts

@@ -0,0 +1,49 @@
+/**
+ * The elements' language and their texts (m1-contracts.md §10.4): every string a reader sees comes from
+ * the SDK's catalogue, `communityMessage` — one catalogue, one tone test. The elements add no words of
+ * their own; test/text-only.spec.ts scans src/ for any.
+ */
+import { communityMessage, hasCommunityMessage, type CommunityMessageKey } from '@blogmcp/sdk/community'
+
+export type Lang = 'cs' | 'en'
+
+/**
+ * The review layer's rule: the first candidate that is Czech or Slovak reads Czech, the first that is
+ * English reads English; anything else is passed over; English when none decides. The candidates are
+ * the `lang` attribute, then `<html lang>`.
+ */
+export function pickLang(...candidates: Array<string | null | undefined>): Lang {
+  for (const c of candidates) {
+    if (!c) continue
+    const l = c.toLowerCase()
+    if (l.startsWith('cs') || l.startsWith('sk')) return 'cs'
+    if (l.startsWith('en')) return 'en'
+  }
+  return 'en'
+}
+
+/** The page's own language attribute, when there is a page (the elements mount in a browser only). */
+export function documentLang(): string | null {
+  return typeof document === 'undefined' ? null : document.documentElement.lang || null
+}
+
+export type TextParams = Record<string, string | number>
+export type Translate = (key: CommunityMessageKey, params?: TextParams) => string
+
+export function translator(lang: Lang): Translate {
+  return (key, params) => communityMessage(lang, key, params)
+}
+
+/**
+ * A key built from one of kb-api's open codes (`restriction.<code>`, `caseStatus.<status>`, …) when the
+ * catalogue has a text for it, else null: a code a newer kb-api sends is skipped, never shown raw.
+ */
+export function knownKey(key: string): CommunityMessageKey | null {
+  return hasCommunityMessage(key) ? key : null
+}
+
+/** A message key and its params: what a controller hands the view, which turns it into text. */
+export interface TextRef {
+  readonly key: CommunityMessageKey
+  readonly params?: TextParams
+}

package/src/core/names.ts

@@ -0,0 +1,51 @@
+/**
+ * Names in the onboarding and the profile form, checked the way kb-api checks them before a request goes
+ * (m1-contracts.md §7.4.3): the display name NFKC-folded, 2–80 characters; a handle `COMMUNITY_HANDLE_RE`.
+ * kb-api decides the rest (reserved words, look-alikes, clashes) and the element shows its answer.
+ */
+import { COMMUNITY_DISPLAY_NAME_MAX, COMMUNITY_DISPLAY_NAME_MIN, COMMUNITY_HANDLE_RE } from '@blogmcp/sdk/community'
+import { codePointLength } from './text'
+
+/** The display name as kb-api will fold it: NFKC, white space collapsed, trimmed. */
+export function normalizeName(name: string): string {
+  return typeof name === 'string' ? name.normalize('NFKC').replace(/\s+/gu, ' ').trim() : ''
+}
+
+export function isDisplayNameOk(name: string): boolean {
+  const n = codePointLength(normalizeName(name))
+  return n >= COMMUNITY_DISPLAY_NAME_MIN && n <= COMMUNITY_DISPLAY_NAME_MAX
+}
+
+/** A handle's length as COMMUNITY_HANDLE_RE takes it (3–30), for the hint and the field's maxlength. */
+export const HANDLE_MIN = 3
+export const HANDLE_MAX = 30
+
+/** A handle as typed: lower case, trimmed; '' when none was typed. */
+export function normalizeHandle(handle: string): string {
+  return typeof handle === 'string' ? handle.trim().toLowerCase() : ''
+}
+
+export function isHandleOk(handle: string): boolean {
+  const h = normalizeHandle(handle)
+  return h === '' || COMMUNITY_HANDLE_RE.test(h)
+}
+
+/** Letters NFD does not take apart, as kb-api's stem maps them. */
+const ASCII: Readonly<Record<string, string>> = Object.freeze({ ß: 'ss', ł: 'l', đ: 'd', ð: 'd', ø: 'o', ħ: 'h', ŧ: 't', ı: 'i', æ: 'ae', œ: 'oe', þ: 'th', ŀ: 'l' })
+
+/**
+ * The handle kb-api would make of a display name when the member gives none (its stem: fold → ASCII →
+ * words joined by `_`, at most 24 characters) — shown as a suggestion; null when the name gives too little.
+ * kb-api may still add a number on a clash, or leave out a reserved word.
+ */
+export function suggestedHandle(displayName: string): string | null {
+  const folded = normalizeName(displayName).toLowerCase().normalize('NFD').replace(/\p{M}+/gu, '').normalize('NFC')
+  const ascii = folded.replace(/[ßłđðøħŧıæœþŀ]/g, (ch) => ASCII[ch] ?? ch)
+  const stem = ascii
+    .split(/[^a-z0-9]+/)
+    .filter((p) => p !== '')
+    .join('_')
+    .slice(0, 24)
+    .replace(/_+$/, '')
+  return COMMUNITY_HANDLE_RE.test(stem) ? stem : null
+}

package/src/core/notice.ts

@@ -0,0 +1,178 @@
+/**
+ * `<blogmcp-notice-form>`'s brain (m1-contracts.md §7.7, §10.4; community.md §5; DSA art. 16): the notice
+ * anyone may send about a message, a profile or an article — with or without a session. The category, the
+ * description, the optional name and e-mail (hidden and never sent for `child_at_risk`: kb-api refuses a
+ * contact there, NOTIFIER_NOT_ALLOWED), the Turnstile token, and the good-faith statement of art. 16(2)(d)
+ * (`confirmations: ['good_faith']`, §7.14 I-2). The answer is the notifier's receipt: the status link carries
+ * it in its fragment only.
+ */
+import { reactive } from 'vue'
+import {
+  CATEGORY_WITHOUT_NOTIFIER,
+  COMMUNITY_GOOD_FAITH,
+  COMMUNITY_NOTICE_DESCRIPTION_MAX,
+  COMMUNITY_NOTIFIER_NAME_MAX,
+  communityRulesOf,
+  noticeStatusLink,
+  type CaseCategory,
+  type CommunityCallOptions,
+  type CommunityClient,
+  type CommunityFailure,
+  type CommunityRule,
+  type NoticeReceipt,
+  type NoticeSubmitInput,
+  type NoticeTarget,
+} from '@blogmcp/sdk/community'
+import type { Lang } from './i18n'
+import { codePointLength, normalizeBody } from './text'
+
+/** `off`: no site key (development, a host without the widget); kb-api then decides alone. */
+export type CaptchaState = 'off' | 'loading' | 'ready' | 'unavailable'
+
+export interface NoticeFormUi {
+  target: NoticeTarget | null
+  category: CaseCategory | ''
+  ruleId: string
+  rules: CommunityRule[] | null
+  description: string
+  name: string
+  email: string
+  goodFaith: boolean
+  captcha: CaptchaState
+  /** The widget's one-shot token, or null. */
+  token: string | null
+  /** Bumped after every failed send: the widget issues a new token. */
+  resetSignal: number
+  sending: boolean
+  failure: CommunityFailure | null
+  receipt: NoticeReceipt | null
+  /** The notifier's status page with the receipt in the fragment. */
+  statusLink: string | null
+}
+
+export interface NoticeFormController {
+  readonly state: NoticeFormUi
+  /** The name and e-mail fields apply (not for an endangered child). */
+  contactAllowed(): boolean
+  canSubmit(): boolean
+  descriptionLength(): number
+  setCategory(category: CaseCategory | ''): void
+  setToken(token: string | null): void
+  setCaptcha(state: CaptchaState): void
+  submit(): Promise<void>
+  dispose(): void
+}
+
+export interface NoticeFormOptions {
+  client: Pick<CommunityClient, 'notices' | 'legal'>
+  lang: Lang
+  target: NoticeTarget | null
+  /** A Turnstile site key was given: a token is needed before the form can be sent. */
+  captcha: boolean
+  /** The host's status page (the receipt goes in its fragment). */
+  noticesPath: string
+  /** The form was sent (the receipt is the page's: it is not passed on). */
+  onSubmitted?(answer: { contactKept: boolean }): void
+}
+
+export function createNoticeForm(o: NoticeFormOptions): NoticeFormController {
+  const abort = new AbortController()
+  const call: CommunityCallOptions = { signal: abort.signal }
+  const state = reactive<NoticeFormUi>({
+    target: o.target,
+    category: '',
+    ruleId: '',
+    rules: null,
+    description: '',
+    name: '',
+    email: '',
+    goodFaith: false,
+    captcha: o.captcha ? 'loading' : 'off',
+    token: null,
+    resetSignal: 0,
+    sending: false,
+    failure: null,
+    receipt: null,
+    statusLink: null,
+  }) as NoticeFormUi
+  let rulesAsked = false
+
+  const contactAllowed = (): boolean => state.category !== CATEGORY_WITHOUT_NOTIFIER
+  const descriptionLength = (): number => codePointLength(normalizeBody(state.description))
+
+  function canSubmit(): boolean {
+    const length = descriptionLength()
+    return (
+      !state.sending &&
+      state.receipt === null &&
+      state.target !== null &&
+      state.category !== '' &&
+      length > 0 &&
+      length <= COMMUNITY_NOTICE_DESCRIPTION_MAX &&
+      codePointLength(state.name.trim()) <= COMMUNITY_NOTIFIER_NAME_MAX &&
+      state.goodFaith &&
+      (state.captcha === 'off' || (state.captcha === 'ready' && state.token !== null))
+    )
+  }
+
+  function loadRules(): void {
+    if (rulesAsked) return
+    rulesAsked = true
+    void o.client.legal.current({ kind: 'rules', locale: o.lang }, call).then((r) => {
+      state.rules = r.ok ? communityRulesOf(r.value.bodyJson) : []
+    })
+  }
+
+  async function submit(): Promise<void> {
+    if (!canSubmit() || !state.target || state.category === '') return
+    state.sending = true
+    state.failure = null
+    const input: NoticeSubmitInput = {
+      category: state.category,
+      target: state.target,
+      description: normalizeBody(state.description),
+      confirmations: [COMMUNITY_GOOD_FAITH],
+    }
+    if (state.category === 'rules' && state.ruleId !== '') input.ruleId = state.ruleId
+    // An endangered child is reported without the notifier's name and e-mail: not even sent.
+    const name = state.name.trim()
+    const email = state.email.trim()
+    if (contactAllowed() && (name !== '' || email !== '')) input.notifier = { name: name || null, email: email || null, locale: o.lang }
+    if (state.token !== null) input.turnstileToken = state.token
+    // The token is spent by this request whatever its answer.
+    state.token = null
+    const r = await o.client.notices.submit(input, call)
+    state.sending = false
+    if (r.ok) {
+      state.receipt = r.value
+      state.statusLink = noticeStatusLink(o.noticesPath, r.value.receipt)
+      o.onSubmitted?.({ contactKept: r.value.contactKept })
+      return
+    }
+    state.failure = r
+    if (state.captcha !== 'off') state.resetSignal += 1
+  }
+
+  return {
+    state,
+    contactAllowed,
+    canSubmit,
+    descriptionLength,
+    setCategory(category) {
+      state.category = category
+      if (category !== 'rules') state.ruleId = ''
+      else loadRules()
+    },
+    setToken(token) {
+      state.token = token
+      if (token !== null && state.captcha === 'loading') state.captcha = 'ready'
+    },
+    setCaptcha(captcha) {
+      if (state.captcha !== 'off') state.captcha = captcha
+    },
+    submit,
+    dispose() {
+      abort.abort()
+    },
+  }
+}