Skip to content

Mentions list (for a site)

One page of one site's mentions, the same in Carrel and in every site admin.

<p>Tabs with the site's counts; <kbd>j</kbd> and <kbd>k</kbd> move, <kbd>a</kbd> approves and <kbd>r</kbd> rejects at once with Undo (<kbd>z</kbd>), <kbd>x</kbd> selects for the bulk bar, and <kbd>d</kbd> deletes after a confirm with the count to type. The sweep shows what the site's retention will remove before it runs.</p>
<div data-mount="editor"></div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/mentions-list.css";
import { mentionsHref, withMentions, currentView } from "capsomer/behavior/mentions-list";

Usage

<section class="cap-mq cap-mentions" data-cap="mentions-list" data-view="pending" aria-labelledby="m-h">
  <h2 class="cap-sr-only" id="m-h">Mentions on example.com</h2>
  <nav class="cap-tabs-list cap-mentions-tabs" aria-label="Mentions by state">
    <a class="cap-tab" href="/mentions?view=pending" aria-current="page">Waiting<span class="cap-tab-count">3</span></a>
    ...Source not found, Approved, Rejected, All
  </nav>
  <div class="cap-mq-head"><p class="cap-mq-summary" role="status">3 waiting</p><a class="cap-pill" data-variant="secondary" href="/mentions?view=all">1 not yet checked</a><p class="cap-mentions-count">3 mentions</p></div>
  <ul class="cap-mentions-withheld">...</ul>
  <div class="cap-message cap-content-result" role="status">...</div>
  <form id="bulk" class="cap-mentions-bulk-form" method="post" action="/mentions"></form>
  <div class="cap-bulk" data-cap="bulk-bar" ...>...Approve, Reject, Delete as submit buttons with form="bulk"; the outcome list...</div>
  <ul class="cap-rows cap-mq-list" role="list">
    <li class="cap-row cap-mq-row" data-id="m-101" data-state="pending">
      <span class="cap-mq-check"><label class="cap-check"><input type="checkbox" name="ids" value="m-101" form="bulk">...</label></span>
      <span class="cap-row-status"><span class="cap-status" data-tone="info">...Waiting</span></span>
      <div class="cap-row-title"><a href="/mentions?open=m-101" aria-expanded="false">...Rosa Park fieldnotes.example</a></div>
      <p class="cap-row-detail">On Field notes: the spring survey: “...”</p>
      <span class="cap-row-meta"><time class="cap-time" datetime="...">...</time></span>
      <form class="cap-row-actions cap-mentions-act" method="post" action="/mentions" aria-label="Decide the mention from Rosa Park">
        <input type="hidden" name="ids" value="m-101"><input type="hidden" name="version" value="3">
        <button type="submit" name="intent" value="approve" data-cap-action="approve">Approve</button>
        <button type="submit" name="intent" value="reject" data-cap-action="reject">Reject</button>
        <button type="submit" name="intent" value="delete" data-cap-action="delete" data-variant="danger">Delete</button>
      </form>
      <div class="cap-mq-more">...open: the quote, From, Source as text, On, Received, Decided...</div>
    </li>
  </ul>
  <nav class="cap-mentions-pages" aria-label="Mentions pages">...First page, Next page...</nav>
  <form class="cap-mq-retention" method="post" action="/mentions"><p>...the site's retention...</p><button type="submit" name="intent" value="sweep">Remove 2 expired</button></form>
</section>
import { MentionsList } from "capsomer/react/mentions-list";
<MentionsList data={data} action="/mentions" Form={Form} result={useActionData()} submit={fetcherSubmit} />

Examples

A site with no Back to waiting (site-api v0.5): a decision on a waiting mention says it has no Undo

<div data-mount="v05"></div>

The page after a bulk post, with no script: the result with Undo, and each mention's outcome

<div data-mount="outcomes"></div>

A reader: no boxes and no decisions, and why, in words

<div data-mount="reader"></div>

The second page of All, with a mention opened through the address

<div data-mount="paged"></div>

Nothing waiting, so the list opens on All; and an empty tab

<div data-mount="empty-open"></div>
<div data-mount="empty-rejected"></div>

Delete and the sweep with no script: the server's confirmation pages

<div data-mount="confirm-delete"></div>
<div data-mount="confirm-sweep"></div>

The delivered HTML: what a server sends, before any script runs

<p>Rendered to a string and put in the page as it is, with nothing attached: the tabs and pages are links, a sender's name is a link that opens the mention through the address, each row's decisions are a form of submit buttons, and the bar's actions post the ticked boxes.</p>
<div id="mentions-static"></div>

API reference

MentionsList

PropTypeRequiredDoes
dataMentionsDataYesThe loader's view data: one page of one site's mentions.
actionstringYesWhere the forms post, and the list's own address: usually the route itself.
FormFormComponentThe host router's form component. Without it a plain <form> is rendered.
submitSubmitIntentThe script path: posts a form and resolves with the action's result (a useFetcher wrapper). With it, a decision happens in place with Undo in the message, and the keys decide.
resultIntentResult | nullThe last result from the action, for the page that comes back after a post with no script.
nownumberA fixed "now" for the times, for a test or a server's clock.

Functions

FunctionSignatureDoes
mentionsHref(base: string, q: MentionsQuery): stringThe list's address with a query (content.ts, queryHref).
withMentions(q: MentionsQuery, change: Partial<MentionsQuery>): MentionsQueryA tab change starts again at the first page with nothing open; opening a mention keeps the page it is on.
currentView(data: Pick<MentionsData, "query" | "counts">): ModViewThe tab shown: the one asked for, else Waiting, else All when nothing waits (Carrel and dustinedwards.info already agree on this).
mentionActions(data: Pick<MentionsData, "offers" | "can" | "query" | "counts">): { bulk: OfferedAction[]; withheld: string[]; }The bulk actions this person may run on this tab of this site, in the bar's order, and a sentence for each one held back.
countLine(data: Pick<MentionsData, "rows" | "query" | "counts">): string--------------------------------------------------------------------------------------- Words. "4 mentions", "Showing 50 of 212 mentions".
emptyWords(view: ModView): { kind: "nothing-yet" | "all-clear"; title: string; text: string; }
sweepLabel(expiring: { failed: number; rejected: number; }): { n: number; label: string; }The sweep's button: "Remove 3 expired".
kitMentionsSearch(search: URLSearchParams): URLSearchParamsThe kit's query from the list's address: the list names its tab view, the kit's filter is status. The host hands the answer to site-api's readMentionsQuery.
mentionsDataOfKit(kit: KitMentionsData, search: URLSearchParams): MentionsDataThe kit's page as the list renders it: each mention in the queue's words (the sender's name, the source's host as text, never a link), the counts with All, and what the site offers. Carrel and each site's own admin draw the same page from it.

Parts and data attributes

ClassIs
.cap-mentionsthe root
.cap-mentions-acta part
.cap-mentions-counta part
.cap-mentions-pagesa part
.cap-mentions-withhelda part

Accessibility

KeyDoes
j, kMove between the rows
aApproves the focused row, or the whole selection when the row is part of it
rRejects it
dDeletes it, after the confirm dialog with the count to type
xSelects or unselects the focused row
zUndo (the message region's key)
EscClears the selection, from a row or the bulk bar

With script, as the queue's (single keys can be turned off):

The keys do nothing in a text field, with Ctrl, Alt or Meta held, in an open dialog, or when single-key shortcuts are off (the shortcuts switch, data-cap-single-keys="off" on <html>; z is the message region's and follows it too); the hints and aria-keyshortcuts are shown only while the keys work.

  • The list is a region named by its heading ("Mentions on example.com"); the tabs are a nav of links, the current one with aria-current="page".
  • Each row's decisions are a form named for its sender ("Decide the mention from Rosa Park"), and each button names the sender too.
  • The live line is a polite status; the result box and the bar's outcome list are the content components' own.
  • A status is a shape, a word and a color. Text reaches 4.5:1 and edges 3:1 in both themes.