@things-factory/announcement 0.0.0-stage → 10.1.222

package/client/pages/announcement-list.ts

@@ -0,0 +1,200 @@
+import '@material/web/icon/icon.js'
+import '@operato/data-grist/ox-grist.js'
+import '@operato/data-grist/ox-filters-form.js'
+import '@operato/input/ox-select.js'
+import '@operato/popup/ox-popup-list.js'
+
+import gql from 'graphql-tag'
+import { css, html } from 'lit'
+import { customElement, query, state } from 'lit/decorators.js'
+
+import { DataGrist, FetchOption } from '@operato/data-grist'
+import { client } from '@operato/graphql'
+import { i18next, localize } from '@operato/i18n'
+import { navigate, PageView } from '@operato/shell'
+import { CommonGristStyles, CommonHeaderStyles, ScrollbarStyles, WorkSurfacePageStyles } from '@operato/styles'
+import { isMobileDevice } from '@operato/utils'
+import { hasPrivilege } from '@things-factory/auth-base/dist-client'
+
+import { LIST_FIELDS } from '../utils/announcement-api.js'
+import { CATEGORIES, categoryWord, importanceWord, readerStateWord, t, when } from '../utils/announcement-words.js'
+
+/**
+ * 공지 — the announcements addressed to the person: the current ones, pinned, urgent and important first, or the past
+ * ones (ADR-0163 decision 5). Those not read yet are bold; a row opens the announcement.
+ */
+@customElement('announcement-list')
+export class AnnouncementList extends localize(i18next)(PageView) {
+  static styles = [
+    WorkSurfacePageStyles,
+    CommonGristStyles,
+    CommonHeaderStyles,
+    ScrollbarStyles,
+    css`
+      .filters {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--spacing-medium, 8px);
+      }
+      ox-select {
+        min-width: 140px;
+      }
+    `
+  ]
+
+  @state() gristConfig: any
+  @state() period: 'current' | 'past' = 'current'
+  /* A writer manages and writes from here - the menu offers one entry, and a reader sees no group of one. */
+  @state() writer = false
+  @query('ox-grist') private grist!: DataGrist
+
+  private onChanged = () => this.grist?.fetch()
+
+  get context() {
+    return {
+      title: t('announcement.title.list'),
+      search: {
+        handler: (search: string) => {
+          this.grist.searchText = search
+        },
+        value: this.grist?.searchText || ''
+      },
+      filter: {
+        handler: () => {
+          this.grist.toggleHeadroom()
+        }
+      },
+      actions: this.writer
+        ? [
+            { title: t('announcement.title.manage'), icon: 'edit_note', action: () => navigate('announcement-manage-list') },
+            { title: t('announcement.button.new'), icon: 'add', emphasis: { raised: true }, action: () => navigate('announcement-editor') }
+          ]
+        : []
+    }
+  }
+
+  render() {
+    const periods = [
+      { value: 'current', display: t('announcement.text.period-current') },
+      { value: 'past', display: t('announcement.text.period-past') }
+    ]
+    return html`<ox-grist class="page-fill" search-mode="term" .mode=${isMobileDevice() ? 'CARD' : 'GRID'} .config=${this.gristConfig} .fetchHandler=${this.fetchHandler.bind(this)}>
+      <div slot="headroom" class="header">
+        <div class="filters">
+          <ox-select
+            .value=${this.period}
+            aria-label=${t('announcement.text.period')}
+            @change=${(e: CustomEvent) => {
+              const next = e.detail === 'past' ? 'past' : 'current'
+              if (next === this.period) return
+              this.period = next
+              this.grist.fetch()
+            }}
+          >
+            <span slot="label">${periods.find(one => one.value === this.period)?.display}</span>
+            <ox-popup-list align-left nowrap with-search>${periods.map(one => html`<div option value=${one.value}>${one.display}</div>`)}</ox-popup-list>
+          </ox-select>
+          <ox-filters-form without-search autofocus></ox-filters-form>
+        </div>
+      </div>
+    </ox-grist>`
+  }
+
+  connectedCallback() {
+    super.connectedCallback()
+    window.addEventListener('announcements-changed', this.onChanged)
+  }
+
+  disconnectedCallback() {
+    window.removeEventListener('announcements-changed', this.onChanged)
+    super.disconnectedCallback()
+  }
+
+  async pageUpdated(changes: any) {
+    if (this.active && changes.active && this.gristConfig) this.grist?.fetch()
+  }
+
+  async pageInitialized() {
+    hasPrivilege({ category: 'announcement', privilege: 'mutation', domainOwnerGranted: true }).then(writer => {
+      this.writer = !!writer
+      this.updateContext()
+    })
+    const open = (record: any) => record?.id && navigate(`announcement-view?id=${record.id}`)
+    const owed = (record: any) => record?.readerState === 'unread' || record?.readerState === 'to-acknowledge'
+    this.gristConfig = {
+      rows: { appendable: false, selectable: false, handlers: { click: (_c: any, _d: any, _col: any, record: any) => open(record) } },
+      pagination: { limit: 50, pages: [50, 100] },
+      emptyNote: { title: t('announcement.text.empty'), description: t('announcement.text.empty-description') },
+      list: { fields: ['title', 'readerState'], details: ['category', 'publishedAt'] },
+      columns: [
+        {
+          type: 'string',
+          name: 'pinned',
+          header: '',
+          width: 34,
+          record: {
+            editable: false,
+            renderer: (_v: any, _c: any, record: any) =>
+              record?.pinned && !this.isPast()
+                ? html`<md-icon style="--md-icon-size:16px" title=${t('announcement.field.pinned')}>push_pin</md-icon>`
+                : record?.importance === 'URGENT'
+                  ? html`<md-icon style="--md-icon-size:16px;color:var(--md-sys-color-error)" title=${importanceWord('URGENT')}>priority_high</md-icon>`
+                  : ''
+          }
+        },
+        {
+          type: 'string',
+          name: 'category',
+          header: t('announcement.field.category'),
+          width: 90,
+          record: { editable: false, renderer: (value: string) => categoryWord(value) },
+          filter: { type: 'select', operator: 'eq', options: [{ display: '', value: '' }, ...CATEGORIES.map(code => ({ display: categoryWord(code), value: code }))] }
+        },
+        {
+          type: 'string',
+          name: 'title',
+          header: t('announcement.field.title'),
+          width: 320,
+          record: {
+            editable: false,
+            renderer: (value: string, _c: any, record: any) =>
+              html`<span style=${owed(record) ? 'font-weight:600' : ''}>${record?.importance === 'IMPORTANT' ? `[${importanceWord('IMPORTANT')}] ` : ''}${value}</span>`
+          }
+        },
+        {
+          type: 'string',
+          name: 'readerState',
+          header: t('announcement.field.reader-state'),
+          width: 100,
+          record: { editable: false, renderer: (value: string) => html`<span style=${value === 'unread' || value === 'to-acknowledge' ? 'color:var(--md-sys-color-primary);font-weight:600' : ''}>${readerStateWord(value)}</span>` }
+        },
+        { type: 'string', name: 'publisher', header: t('announcement.field.publisher'), width: 110, record: { editable: false, renderer: (value: any) => value?.name ?? '' } },
+        { type: 'string', name: 'publishedAt', header: t('announcement.field.published-at'), width: 110, record: { editable: false, renderer: (value: string) => when(value, false) } },
+        { type: 'string', name: 'endsAt', header: t('announcement.field.ends-at'), width: 110, record: { editable: false, renderer: (value: string) => when(value, false) } }
+      ]
+    }
+  }
+
+  private isPast() {
+    return this.period === 'past'
+  }
+
+  async fetchHandler({ page = 1, limit = 50, filters = [], search }: FetchOption) {
+    const response = await client.query({
+      query: gql`
+        query ($filters: [Filter!], $pagination: Pagination, $search: String) {
+          responses: announcements(filters: $filters, pagination: $pagination, search: $search) {
+            items { ${LIST_FIELDS} }
+            total
+          }
+        }
+      `,
+      /* The period is the reader's own filter - the assistant narrows the same list the same way. */
+      variables: { filters: [...filters, { name: 'period', operator: 'eq', value: this.period }], pagination: { page, limit }, search: search?.trim() || undefined },
+      fetchPolicy: 'network-only'
+    })
+    if (response.errors?.length) throw response
+    return { total: response.data.responses.total, records: response.data.responses.items }
+  }
+}

package/client/pages/announcement-manage-list.ts

@@ -0,0 +1,113 @@
+import '@operato/data-grist/ox-grist.js'
+import '@operato/data-grist/ox-filters-form.js'
+
+import gql from 'graphql-tag'
+import { html } from 'lit'
+import { customElement, query, state } from 'lit/decorators.js'
+
+import { DataGrist, FetchOption } from '@operato/data-grist'
+import { client } from '@operato/graphql'
+import { i18next, localize } from '@operato/i18n'
+import { navigate, PageView } from '@operato/shell'
+import { CommonGristStyles, CommonHeaderStyles, ScrollbarStyles, WorkSurfacePageStyles } from '@operato/styles'
+import { isMobileDevice } from '@operato/utils'
+
+import { CATEGORIES, categoryWord, importanceWord, statusWord, t, when } from '../utils/announcement-words.js'
+
+const STATUSES = ['DRAFT', 'SCHEDULED', 'PUBLISHED', 'WITHDRAWN']
+
+/**
+ * 공지 관리 — every announcement of the domain for its writers: the ones out, scheduled and withdrawn, and one's own
+ * drafts, with how many each reached and how many read it (ADR-0163 decision 4). A draft opens in the editor; the rest
+ * open as their readers see them, with the writer's actions.
+ */
+@customElement('announcement-manage-list')
+export class AnnouncementManageList extends localize(i18next)(PageView) {
+  static styles = [WorkSurfacePageStyles, CommonGristStyles, CommonHeaderStyles, ScrollbarStyles]
+
+  @state() gristConfig: any
+  @query('ox-grist') private grist!: DataGrist
+
+  get context() {
+    return {
+      title: t('announcement.title.manage'),
+      /* Opened from 공지사항; the menu marks it. */
+      menu: 'announcement-list',
+      search: {
+        handler: (search: string) => {
+          this.grist.searchText = search
+        },
+        value: this.grist?.searchText || ''
+      },
+      filter: {
+        handler: () => {
+          this.grist.toggleHeadroom()
+        }
+      },
+      actions: [{ title: t('announcement.button.new'), icon: 'add', emphasis: { raised: true }, action: () => navigate('announcement-editor') }],
+      exportable: { name: t('announcement.title.manage'), data: () => this.grist.exportRecords() }
+    }
+  }
+
+  render() {
+    return html`<ox-grist class="page-fill" search-mode="term" .mode=${isMobileDevice() ? 'CARD' : 'GRID'} .config=${this.gristConfig} .fetchHandler=${this.fetchHandler.bind(this)}>
+      <div slot="headroom" class="header">
+        <div class="filters"><ox-filters-form without-search autofocus></ox-filters-form></div>
+      </div>
+    </ox-grist>`
+  }
+
+  async pageUpdated(changes: any) {
+    if (this.active && changes.active && this.gristConfig) this.grist?.fetch()
+  }
+
+  async pageInitialized() {
+    const open = (record: any) => record?.id && navigate(record.status === 'DRAFT' ? `announcement-editor?id=${record.id}` : `announcement-view?id=${record.id}`)
+    const readonly = (type: string, name: string, header: string, width: number, extra: any = {}) => ({ type, name, header, width, sortable: true, ...extra, record: { editable: false, ...extra.record } })
+    this.gristConfig = {
+      rows: { appendable: false, selectable: false, handlers: { click: (_c: any, _d: any, _col: any, record: any) => open(record) } },
+      pagination: { limit: 50, pages: [50, 100, 500] },
+      emptyNote: { title: t('announcement.text.manage-empty'), description: t('announcement.text.manage-empty-description') },
+      list: { fields: ['title', 'status'], details: ['publishedAt', 'readCount'] },
+      columns: [
+        readonly('string', 'status', t('announcement.field.status'), 80, {
+          record: { renderer: (value: string) => statusWord(value) },
+          filter: { type: 'select', operator: 'eq', options: [{ display: '', value: '' }, ...STATUSES.map(code => ({ display: statusWord(code), value: code }))] }
+        }),
+        readonly('string', 'category', t('announcement.field.category'), 90, {
+          record: { renderer: (value: string) => categoryWord(value) },
+          filter: { type: 'select', operator: 'eq', options: [{ display: '', value: '' }, ...CATEGORIES.map(code => ({ display: categoryWord(code), value: code }))] }
+        }),
+        readonly('string', 'importance', t('announcement.field.importance'), 70, { record: { renderer: (value: string) => importanceWord(value) } }),
+        readonly('string', 'title', t('announcement.field.title'), 320),
+        readonly('string', 'startsAt', t('announcement.field.starts-at'), 140, { record: { renderer: (value: string) => when(value) } }),
+        readonly('string', 'endsAt', t('announcement.field.ends-at'), 140, { record: { renderer: (value: string) => when(value) } }),
+        readonly('integer', 'audienceSize', t('announcement.field.audience-size'), 70, { sortable: false, record: { align: 'right' } }),
+        readonly('integer', 'readCount', t('announcement.field.read-count'), 70, { sortable: false, record: { align: 'right' } }),
+        readonly('integer', 'acknowledgedCount', t('announcement.field.acknowledged-count'), 70, {
+          sortable: false,
+          record: { align: 'right', renderer: (value: number, _c: any, record: any) => (record?.requiresAcknowledgement ? (value ?? '') : '') }
+        }),
+        readonly('string', 'updatedAt', t('announcement.field.updated-at'), 140, { record: { renderer: (value: string) => when(value) } })
+      ],
+      sorters: [{ name: 'updatedAt', desc: true }]
+    }
+  }
+
+  async fetchHandler({ page = 1, limit = 50, sortings = [], filters = [], search }: FetchOption) {
+    const response = await client.query({
+      query: gql`
+        query ($filters: [Filter!], $pagination: Pagination, $sortings: [Sorting!], $search: String) {
+          responses: managedAnnouncements(filters: $filters, pagination: $pagination, sortings: $sortings, search: $search) {
+            items { id title category importance status startsAt endsAt requiresAcknowledgement publishedAt audienceSize readCount acknowledgedCount updatedAt }
+            total
+          }
+        }
+      `,
+      variables: { filters, pagination: { page, limit }, sortings, search: search?.trim() || undefined },
+      fetchPolicy: 'network-only'
+    })
+    if (response.errors?.length) throw response
+    return { total: response.data.responses.total, records: response.data.responses.items }
+  }
+}

package/client/pages/announcement-view.ts

@@ -0,0 +1,172 @@
+import '@operato/list-state/ox-page-state.js'
+import '../components/announcement-sheet.js'
+import '../components/announcement-receipts.js'
+
+import { css, html, nothing } from 'lit'
+import { customElement, state } from 'lit/decorators.js'
+
+import { i18next, localize } from '@operato/i18n'
+import { notify, openPopup } from '@operato/layout'
+import { navigate, PageView } from '@operato/shell'
+import { DocumentPageStyles } from '@operato/styles'
+
+import { announcementApi, type AnnouncementItem } from '../utils/announcement-api.js'
+import { reasonOf, statusWord, t, when } from '../utils/announcement-words.js'
+
+/**
+ * 공지 보기 — one announcement. Opening it reads it for its audience (ADR-0163 decision 5). Its writers also see whom it
+ * reached and who read it, and change, remind or withdraw it from here (decision 4).
+ */
+@customElement('announcement-view')
+export class AnnouncementView extends localize(i18next)(PageView) {
+  static styles = [
+    DocumentPageStyles,
+    css`
+      .notice {
+        padding: var(--spacing-medium, 8px) var(--spacing-large, 12px);
+        border-radius: var(--border-radius, 4px);
+        background: var(--md-sys-color-surface-container, rgba(0, 0, 0, 0.04));
+        font-size: var(--ui-t-body, 14px);
+      }
+      .audience {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--spacing-small, 4px) var(--spacing-medium, 8px);
+        font-size: var(--ui-t-small, 12px);
+        color: var(--ui-muted, var(--md-sys-color-on-surface-variant));
+      }
+      ul.deliveries {
+        margin: var(--spacing-small, 4px) 0 0;
+        padding: 0;
+        list-style: none;
+        font-size: var(--ui-t-small, 12px);
+        color: var(--ui-muted, var(--md-sys-color-on-surface-variant));
+      }
+      h2 {
+        margin: 0;
+        font-size: var(--ui-t-title-large, 22px);
+      }
+    `
+  ]
+
+  @state() announcement: AnnouncementItem | null = null
+  @state() loading = false
+  @state() error: unknown = null
+
+  get context() {
+    const one = this.announcement
+    const actions: any[] = []
+    if (one?.editable) {
+      actions.push({ title: t('announcement.button.edit'), icon: 'edit', action: () => navigate(`announcement-editor?id=${one.id}`) })
+      if (one.status === 'PUBLISHED') {
+        actions.push({ title: t('announcement.button.receipts'), icon: 'groups', action: () => this.openReceipts() })
+        actions.push({ title: t('announcement.button.remind'), icon: 'notifications_active', action: () => this.remind() })
+      }
+      if (one.status === 'PUBLISHED' || one.status === 'SCHEDULED') actions.push({ title: t('announcement.button.withdraw'), icon: 'unpublished', action: () => this.withdraw() })
+      actions.push({ title: t('announcement.button.copy'), icon: 'content_copy', action: () => navigate(`announcement-editor?from=${one.id}`) })
+    }
+    return {
+      title: t('announcement.title.view'),
+      ...(one && one.status !== 'PUBLISHED' ? { description: statusWord(one.status) } : {}),
+      frame: 'document',
+      /* Opened from the list of announcements; the menu marks it. */
+      menu: 'announcement-list',
+      actions
+    }
+  }
+
+  async pageUpdated(changes: any, lifecycle: any) {
+    if (!this.active || !(changes.active || changes.params)) return
+    const id = lifecycle?.params?.id
+    if (id) await this.load(id)
+  }
+
+  render() {
+    const one = this.announcement
+    return html`<ox-page-state .loading=${this.loading} .error=${this.error} @retry=${() => one && this.load(one.id)}>
+      ${one
+        ? html`<div class="page">
+            <section class="page-section">
+              <h2>${one.title}</h2>
+              ${one.status === 'WITHDRAWN' ? html`<p class="notice">${t('announcement.text.withdrawn', { when: when(one.withdrawnAt), reason: one.withdrawReason ?? '' })}</p>` : nothing}
+              ${one.status === 'SCHEDULED' ? html`<p class="notice">${t('announcement.text.scheduled', { when: when(one.startsAt) })}</p>` : nothing}
+              <announcement-sheet .announcement=${one} @announcement-acknowledged=${() => this.load(one.id)}></announcement-sheet>
+            </section>
+            ${one.editable && one.audiences
+              ? html`<section class="page-section">
+                  <header class="page-section-header"><h3>${t('announcement.field.audience')}</h3></header>
+                  <div class="audience">
+                    ${one.audiences.map(target => html`<span>${t(`announcement.scope.${target.scope}`)} · ${target.targetName ?? target.targetId}</span>`)}
+                  </div>
+                  ${(one.deliveries ?? []).length
+                    ? html`<ul class="deliveries">
+                        ${[...(one.deliveries ?? [])].reverse().map(
+                          sent => html`<li>
+                            ${when(sent.at)} · ${t(`announcement.delivery.${sent.kind}`)} ·
+                            ${sent.failed ? t('announcement.text.delivery-not-sent', { count: sent.receivers }) : t('announcement.text.delivery-app', { count: sent.receivers })}
+                            ${sent.email.sent || sent.email.failed ? html` · ${t('announcement.text.delivery-email', { sent: sent.email.sent, failed: sent.email.failed })}` : nothing}
+                            ${sent.teams.sent || sent.teams.failed ? html` · ${t('announcement.text.delivery-teams', { sent: sent.teams.sent, failed: sent.teams.failed })}` : nothing}
+                          </li>`
+                        )}
+                      </ul>`
+                    : nothing}
+                  ${one.status === 'PUBLISHED'
+                    ? html`<p class="audience">
+                        ${t('announcement.text.reach', { size: one.audienceSize ?? 0, read: one.readCount ?? 0 })}
+                        ${one.requiresAcknowledgement ? t('announcement.text.reach-acknowledged', { acknowledged: one.acknowledgedCount ?? 0 }) : ''}
+                      </p>`
+                    : nothing}
+                </section>`
+              : nothing}
+          </div>`
+        : nothing}
+    </ox-page-state>`
+  }
+
+  private async load(id: string) {
+    this.loading = true
+    this.error = null
+    try {
+      let one = await announcementApi.one(id)
+      if (!one) throw new Error(t('announcement.refusal.unknown-announcement'))
+      /* Opening it reads it - asked again after, so its writer's counts include this reading. */
+      if (one.addressed && !one.mine?.readAt) {
+        await announcementApi.read(id)
+        one = (await announcementApi.one(id)) ?? one
+      }
+      this.announcement = one
+    } catch (error) {
+      this.announcement = null
+      this.error = error
+    } finally {
+      this.loading = false
+      this.updateContext()
+    }
+  }
+
+  private openReceipts() {
+    const one = this.announcement!
+    const popup: any = openPopup(html`<announcement-receipts .announcement=${one} @done=${() => popup.close()}></announcement-receipts>`, {
+      backdrop: true,
+      size: 'large',
+      title: `${t('announcement.button.receipts')} · ${one.title}`
+    })
+  }
+
+  private async remind() {
+    try {
+      const told = await announcementApi.remind(this.announcement!.id)
+      notify({ message: t('announcement.text.reminded', { count: told }) })
+    } catch (error) {
+      notify({ level: 'error', message: reasonOf(error) })
+    }
+  }
+
+  private withdraw() {
+    const one = this.announcement!
+    const popup: any = openPopup(
+      html`<announcement-withdraw-form .announcement=${one} @announcement-withdrawn=${() => this.load(one.id)} @done=${() => popup.close()}></announcement-withdraw-form>`,
+      { backdrop: true, size: 'small', title: `${t('announcement.button.withdraw')} · ${one.title}` }
+    )
+  }
+}

package/client/route.ts

@@ -0,0 +1,17 @@
+/* The pages this module brings to an application that puts them in its menu (ADR-0163 decision 9). */
+export default function route(page: string) {
+  switch (page) {
+    case 'announcement-list':
+      import('./pages/announcement-list.js')
+      return page
+    case 'announcement-view':
+      import('./pages/announcement-view.js')
+      return page
+    case 'announcement-manage-list':
+      import('./pages/announcement-manage-list.js')
+      return page
+    case 'announcement-editor':
+      import('./pages/announcement-editor.js')
+      return page
+  }
+}

package/client/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig-base.json",
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "declaration": true,
+    "module": "esnext",
+    "outDir": "../dist-client",
+    "baseUrl": "./"
+  },
+  "include": ["./**/*"]
+}

package/client/utils/announcement-api.ts

@@ -0,0 +1,142 @@
+/*
+ * The announcement doors as the screens call them (ADR-0163). Every call throws the server's words when it is refused.
+ */
+import gql from 'graphql-tag'
+
+import { client, uploadContext } from '@operato/graphql'
+
+export type Audience = { scope: 'DOMAIN' | 'DEPARTMENT' | 'ROLE' | 'USER' | string; targetId: string; targetName?: string | null }
+export type AnnouncementLink = { label: string; url: string }
+export type FileRow = { id: string; name: string; fullpath: string; size?: number; mimetype?: string }
+export type Receipt = { readAt?: string | null; acknowledgedAt?: string | null }
+export type Delivery = { at: string; kind: string; receivers: number; email: { sent: number; failed: number }; teams: { sent: number; failed: number }; failed?: boolean }
+
+export interface AnnouncementItem {
+  id: string
+  title: string
+  body?: string | null
+  category: string
+  importance: 'NORMAL' | 'IMPORTANT' | 'URGENT' | string
+  status: 'DRAFT' | 'SCHEDULED' | 'PUBLISHED' | 'WITHDRAWN' | string
+  startsAt?: string | null
+  endsAt?: string | null
+  pinned: boolean
+  requiresAcknowledgement: boolean
+  acknowledgeBy?: string | null
+  popup: boolean
+  sendEmail?: boolean
+  deliveries?: Delivery[] | null
+  links?: AnnouncementLink[] | null
+  version: number
+  publishedAt?: string | null
+  audienceSize?: number | null
+  withdrawnAt?: string | null
+  withdrawReason?: string | null
+  readerState?: 'unread' | 'read' | 'to-acknowledge' | 'acknowledged'
+  readCount?: number | null
+  acknowledgedCount?: number | null
+  editable?: boolean
+  addressed?: boolean
+  mine?: Receipt | null
+  publisher?: { id: string; name?: string } | null
+  creator?: { id: string; name?: string } | null
+  audiences?: Audience[]
+  attachments?: FileRow[]
+}
+
+export interface AnnouncementInput {
+  title: string
+  body?: string
+  category?: string
+  importance?: string
+  startsAt?: string | null
+  endsAt?: string | null
+  pinned?: boolean
+  requiresAcknowledgement?: boolean
+  acknowledgeBy?: string | null
+  popup?: boolean
+  sendEmail?: boolean
+  links?: AnnouncementLink[]
+  audiences?: Audience[]
+}
+
+/** The fields a list row needs. */
+export const LIST_FIELDS = `id title category importance status startsAt endsAt pinned requiresAcknowledgement acknowledgeBy popup publishedAt version readerState publisher { id name }`
+
+/** Everything one announcement shows. */
+export const FULL_FIELDS = `${LIST_FIELDS} body links sendEmail deliveries audienceSize withdrawnAt withdrawReason editable addressed mine { readAt acknowledgedAt }
+  creator { id name } audiences { scope targetId targetName } attachments { id name fullpath size mimetype }`
+
+function answer<T>(response: any, field: string): T {
+  if (response.errors?.length) throw new Error(response.errors.map((one: any) => one.message).join(' · '))
+  return response.data?.[field] as T
+}
+
+async function ask<T>(query: string, variables: Record<string, unknown>, field: string): Promise<T> {
+  return answer<T>(await client.query({ query: gql(query), variables, fetchPolicy: 'network-only' }), field)
+}
+
+async function change<T>(mutation: string, variables: Record<string, unknown>, field: string, uploading?: (fraction: number) => void): Promise<T> {
+  return answer<T>(await client.mutate({ mutation: gql(mutation), variables, ...(uploading ? { context: uploadContext(uploading) } : {}) }), field)
+}
+
+/** Tells the badge and an open list that a reading changed. */
+export const announcementsChanged = () => window.dispatchEvent(new CustomEvent('announcements-changed'))
+
+export const announcementApi = {
+  one: (id: string) => ask<AnnouncementItem | null>(`query ($id: String!) { announcement(id: $id) { ${FULL_FIELDS} readCount acknowledgedCount } }`, { id }, 'announcement'),
+  summary: () => ask<{ unread: number; toAcknowledge: number; pending: number }>(`query { announcementSummary { unread toAcknowledge pending } }`, {}, 'announcementSummary'),
+  popups: () => ask<AnnouncementItem[]>(`query { announcementPopups { ${FULL_FIELDS} } }`, {}, 'announcementPopups'),
+  read: async (id: string) => {
+    const one = await change<AnnouncementItem>(`mutation ($id: String!) { readAnnouncement(id: $id) { id readerState mine { readAt acknowledgedAt } } }`, { id }, 'readAnnouncement')
+    announcementsChanged()
+    return one
+  },
+  acknowledge: async (id: string) => {
+    const one = await change<AnnouncementItem>(`mutation ($id: String!) { acknowledgeAnnouncement(id: $id) { id readerState mine { readAt acknowledgedAt } } }`, { id }, 'acknowledgeAnnouncement')
+    announcementsChanged()
+    return one
+  },
+  receipts: (id: string) =>
+    ask<{ userId: string; name?: string; email?: string; listed: boolean; notifiedAt?: string; readAt?: string; acknowledgedAt?: string }[]>(
+      `query ($id: String!) { announcementReceipts(id: $id) { userId name email listed notifiedAt readAt acknowledgedAt } }`,
+      { id },
+      'announcementReceipts'
+    ),
+  revisions: (id: string) =>
+    ask<{ version: number; title: string; body?: string; rest?: any; createdAt: string; creator?: { name?: string } }[]>(
+      `query ($id: String!) { announcementRevisions(id: $id) { version title body rest createdAt creator { name } } }`,
+      { id },
+      'announcementRevisions'
+    ),
+  choices: () =>
+    ask<{ domainId: string; domainName: string; departments: { id: string; name: string; note?: string }[]; roles: { id: string; name: string; note?: string }[] }>(
+      `query { announcementAudienceChoices { domainId domainName departments { id name note } roles { id name note } } }`,
+      {},
+      'announcementAudienceChoices'
+    ),
+  people: (text: string) => ask<{ id: string; name: string; note?: string }[]>(`query ($text: String!) { announcementPeople(text: $text) { id name note } }`, { text }, 'announcementPeople'),
+  audienceSize: (audiences: Audience[]) =>
+    ask<number>(`query ($audiences: [AnnouncementAudienceInput!]!) { announcementAudienceSize(audiences: $audiences) }`, { audiences }, 'announcementAudienceSize'),
+  create: (input: AnnouncementInput, attach: File[], uploading?: (fraction: number) => void) =>
+    change<AnnouncementItem>(
+      `mutation ($input: AnnouncementInput!, $attach: [Upload!]) { createAnnouncement(input: $input, attach: $attach) { id } }`,
+      { input, attach },
+      'createAnnouncement',
+      attach.length ? uploading ?? (() => {}) : undefined
+    ),
+  update: (id: string, input: AnnouncementInput, attach: File[], remove: string[], notifyAgain: boolean, uploading?: (fraction: number) => void) =>
+    change<AnnouncementItem>(
+      `mutation ($id: String!, $input: AnnouncementInput!, $attach: [Upload!], $remove: [String!], $notifyAgain: Boolean) {
+        updateAnnouncement(id: $id, input: $input, attach: $attach, remove: $remove, notifyAgain: $notifyAgain) { id status }
+      }`,
+      { id, input, attach, remove, notifyAgain },
+      'updateAnnouncement',
+      attach.length ? uploading ?? (() => {}) : undefined
+    ),
+  publish: (id: string) => change<AnnouncementItem>(`mutation ($id: String!) { publishAnnouncement(id: $id) { id status startsAt } }`, { id }, 'publishAnnouncement'),
+  withdraw: (id: string, reason: string) =>
+    change<AnnouncementItem>(`mutation ($id: String!, $reason: String!) { withdrawAnnouncement(id: $id, reason: $reason) { id status } }`, { id, reason }, 'withdrawAnnouncement'),
+  remove: (id: string) => change<boolean>(`mutation ($id: String!) { deleteAnnouncement(id: $id) }`, { id }, 'deleteAnnouncement'),
+  remind: (id: string) => change<number>(`mutation ($id: String!) { remindAnnouncement(id: $id) }`, { id }, 'remindAnnouncement')
+}