Skip to content

Posts list

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

<p>With script: a row's Unpublish or Duplicate runs at once and the message offers Undo (<kbd>z</kbd>); tags show each post's outcome in the bar; Delete asks first and lists every post, with the count to type. The site here refuses a tag on a post with no front matter, as Carrel's does.</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/posts-list.css";
import { inDays, contentStatus, rowStatus } from "capsomer/behavior/posts-list";

Usage

<section class="cap-posts" data-cap="posts-list" aria-label="Posts">
  <nav class="cap-tabs-list cap-posts-tabs" aria-label="Posts by status">
    <a class="cap-tab" aria-current="page" href="/posts">All<span class="cap-tab-count">6</span></a>
    <a class="cap-tab" href="/posts?status=draft">Drafts<span class="cap-tab-count">2</span></a> ...
    <a class="cap-tab" href="/posts?trashed=1">Trash<span class="cap-tab-count">2</span></a> <!-- with offers.trash -->
  </nav>
  <form class="cap-field-row" role="search" aria-label="Find posts" method="get" action="/posts">
    <div class="cap-field cap-field-wide"><label class="cap-field-label" for="q">Search</label><input class="cap-input" type="search" id="q" name="q"></div>
    <!-- Kind (with more than one kind), Tag (when rows carry tags), Author (name="author", with offers.filters "author"), Sort by: native selects in .cap-select-wrap[data-native] -->
    <!-- Published from and to (with offers.filters "published"): .cap-field each, <input class="cap-input" type="date" name="from"> and name="to" -->
    <!-- In the Trash: <input type="hidden" name="trashed" value="1"> -->
    <button type="submit" class="cap-btn">Show</button>
    <a class="cap-btn" data-variant="quiet" href="/posts">Clear filters</a> <!-- once a filter is set -->
  </form>
  <div class="cap-posts-bar">
    <p class="cap-posts-count">6 posts</p>
    <div class="cap-posts-tools"><form class="cap-posts-extra" method="post" action="/posts">...host actions...</form><a class="cap-btn" data-variant="primary" href="/editor/new">New post</a></div>
  </div>
  <p class="cap-posts-trash-note">Posts in Trash are deleted for good 30 days after they were moved there.</p> <!-- in the Trash -->
  <ul class="cap-posts-withheld"><li>Delete is not offered: this site cannot delete posts.</li></ul>
  <div class="cap-message cap-content-result" role="status" aria-label="Results and failures">...the last result, Undo as form.cap-content-undo...</div>
  <div class="cap-posts-preview" role="status" aria-label="Preview link"> <!-- with offers.previewLinks; empty until a link is made -->
    <label class="cap-field-label" for="url">Preview link for Why the uptime strip counts gaps</label>
    <div class="cap-posts-preview-row"><input class="cap-input" id="url" readonly value="https://..." aria-describedby="until"><button type="button" class="cap-btn">Copy</button></div>
    <p class="cap-field-description" id="until">Anyone with the link can read the post until <time class="cap-time" datetime="...">...</time>.</p>
  </div>
  <form id="bulk" method="post" action="/posts" class="cap-posts-bulk-form"></form>
  <div class="cap-bulk" data-cap="bulk-bar" role="region" aria-label="Bulk actions on posts" data-position="top">
    ...the bulk bar in form mode: submit buttons with form="bulk", the tag field, and .cap-bulk-results after a post...
  </div>
  <div class="cap-table-wrap cap-posts-wrap" role="region" aria-labelledby="cap" tabindex="0">
    <table class="cap-table cap-posts-table">
      <caption id="cap" class="cap-sr-only">Posts on example.com</caption>
      <thead><tr><th class="cap-posts-check">...</th><th>Title</th><th>Status</th><th>Updated</th><th><span class="cap-sr-only">Actions</span></th></tr></thead>
      <tbody>
        <tr data-status="scheduled">
          <td class="cap-posts-check"><label class="cap-check"><input type="checkbox" name="ids" value="uptime-strip" form="bulk"><span class="cap-sr-only">Select Why the uptime strip counts gaps</span></label></td>
          <th scope="row" class="cap-posts-title"><a class="cap-table-open" href="/editor/uptime-strip">Why the uptime strip counts gaps</a>
            <span class="cap-posts-meta"><span class="cap-posts-path">Not on the site yet</span><span class="cap-posts-kind">post</span><span class="cap-posts-authors">By Alex Rivera with Sam Lee</span></span>
            <span class="cap-posts-excerpt">A gap is not a zero: ...</span>
            <span class="cap-posts-notes"><span class="cap-pill" data-tone="info">...</span></span></th>
          <td class="cap-posts-status"><span class="cap-status" data-tone="info">[glyph]Scheduled</span> <span class="cap-posts-when">in 3 days</span></td>
          <td class="cap-posts-updated"><time class="cap-time" datetime="...">4 hours ago</time></td>
          <td class="cap-posts-actions"><details class="cap-menu-form" data-cap="menu-form">...Edit, Unpublish, Duplicate, Rename…, Get a preview link, Move to Trash (or Delete); in the Trash, Restore and Delete for good...</details></td>
        </tr>
      </tbody>
    </table>
  </div>
  <nav class="cap-posts-pages" aria-label="Posts pages"><a class="cap-btn" href="/posts?cursor=c-2">Next page</a></nav>
</section>
import { PostsList } from "capsomer/react/posts-list";
import type { PostsData, IntentResult } from "capsomer/content";

// A React Router route: the loader gives the kit's view data, the action runs the kit's intent.
<PostsList data={data} action="/posts" Form={Form} result={useActionData()} submit={(form) => fetcherSubmit(form)} />
import { PostScheduledUpdate } from "capsomer/react/posts-list";
import type { ScheduledUpdateView } from "capsomer/content";

<PostScheduledUpdate data={update} action="/posts" Form={Form} result={useActionData()} submit={(form) => fetcherSubmit(form)} liveSince={row.publishedAt} crumbs={[{ label: "Posts", href: "/posts" }, { label: update.title, href: update.editorHref }, { label: "Scheduled update" }]} />

Examples

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

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

A reader: no boxes, a menu only to view a published post, and why, in words

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

A site with no delete and no tags, one page of many, sorted on the page only

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

Scheduled updates: a live post with an update waiting

<p>On a site that keeps an update waiting on a live post (site-api v0.10.0) its status reads "Published · update in 2 days". The menu views the update, Reschedule… opens a small dialog with the time in your own zone (posted in UTC), and Cancel the update asks first. A scheduled post's menu reschedules it too.</p>
<div data-mount="updates"></div>

site-api v0.17.0: Trash, rename, preview links, authors and excerpts

<p>On a site that offers them, Move to Trash replaces Delete and Undo restores; Rename… asks for the new slug and says the old address will redirect; Get a preview link shows the link with Copy and when it stops working, in your own zone. The Author and Published filters show where the site applies them.</p>
<div data-mount="ideas"></div>

Filtered by author and published dates, as the address keeps them

<div data-mount="ideas-filtered"></div>

The Trash: Restore, and Delete for good behind the count to type

<div data-mount="ideas-trash"></div>
<div data-mount="ideas-link"></div>

The waiting update's page: a page head with its actions, then the update beside the live post

<div data-mount="update-view"></div>

The waiting update, for a reader: no actions, and why

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

Empty: no drafts, and no match for a search

<div data-mount="empty-drafts"></div>
<div data-mount="empty-match"></div>

Delete with no script: the server's confirmation page

<div data-mount="confirm"></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 filters are a GET form, a row's menu is a form of submit buttons and links, and the bar's actions are submit buttons that post the ticked boxes.</p>
<div id="posts-static"></div>

API reference

PostsList

PropTypeRequiredDoes
dataPostsDataYesThe loader's view data: one page of one site.
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, outcomes, Undo and the confirm dialog happen in place; without it every form posts and the page comes back with result.
resultIntentResult | nullThe last result from the action, for the page that comes back after a post with no script.
labelsContentLabels
nownumberA fixed "now" for the times and "in 3 days", for a test or a server's clock.

PostScheduledUpdate

PropTypeRequiredDoes
dataScheduledUpdateViewYessite-api's loadScheduledUpdate(source, id): the update's source, the live one, the patch and the times.
actionstringYesWhere Reschedule and Cancel post: the posts list's action, which runs the kit's intents.
FormFormComponent
submitSubmitIntent
resultIntentResult | null
liveSincestring | nullWhen the live version went out (the row's publishedAt), for the live side's heading.
crumbsArray<{ label: string; href?: string }>The trail above the title: the posts list, then this post.
headingLevel"h1" | "h2" | "h3"The title's level: the page's h1 by default.
labelsContentLabels
nownumber

Functions

FunctionSignatureDoes
inDays(at: string, now: number): stringHow far off a scheduled time is, in whole UTC days. Past it, the site has not published it yet.
contentStatus(status: ContentStatus, publishAt?: string | null, now?: number): ContentStatusWordsThe one mapping from a content status to its words, for every list and editor that shows one (Carrel wrote it inline six times).
rowStatus(row: Pick<PostRow, "status" | "publishAt" | "scheduledUpdate">, now?: number): ContentStatusWords & { note?: string | undefined; }A row's status on one line: the status word, then what is due, after a middle dot: "Scheduled · in 3 days", "Published · update in 2 days".
trashLine(labels?: ContentLabels | undefined): stringThe Trash view's line: what happens to what is in it.
countLine(data: Pick<PostsData, "rows" | "page"> & { query?: PostsQuery | undefined; }, labels?: ContentLabels | undefined): string"12 posts", "Showing 50 of 120 posts", "3 posts in Trash", and a note when the site could only sort this page.
authorLine(authors: readonly string[] | undefined): stringA row's credits on one line, the primary name first: "By Alex Rivera", "By Alex Rivera with Sam Lee". "" for a post that credits no one.
filtered(q: PostsQuery): booleanFilters in the query other than the page, the order and the view: what the empty state says is hiding rows, and what Clear filters takes away.
emptyWords(q: PostsQuery, labels?: ContentLabels | undefined): { kind: "nothing-yet" | "no-match" | "all-clear"; title: string; text: string; }The empty state's title and line, naming what is not there.
postsHref(base: string, q: PostsQuery): stringThe list's address with a query (content.ts, queryHref).
withFilter(q: PostsQuery, change: Partial<PostsQuery>): PostsQueryA filter link changes one thing and starts again at the first page.
postActions(data: Pick<PostsData, "offers" | "can"> & { query?: PostsQuery | undefined; }, labels?: ContentLabels | undefined): { bulk: OfferedAction[]; withheld: string[]; }The bulk actions this person may run on this view of this site, in the bar's order, and a sentence for each one held back, so a missing button is never a mystery. An action shows only when the site offers it (data.offers) and the person may run it (data.can). Where the site has a Trash (site-api v0.17.0), Move to Trash is the normal way out, an editor's since Restore undoes it, and Delete for good is the delete role's, in the Trash only; elsewhere Delete stays as it was.
scheduledTime(row: Pick<PostRow, "status" | "publishAt" | "scheduledUpdate">): string | nullThe time a row's schedule goes out: its waiting update's on a live post, its own on a scheduled one. null when nothing is scheduled.
rowActions(row: PostRow, data: Pick<PostsData, "offers" | "can">): RowAction[]One row's menu: Edit and View on the site go somewhere; the rest post an intent for this row. With scheduled updates (site-api v0.10.0) a scheduled post or a live post's waiting update can be moved (reschedule, with publishAt), and a live post's update canceled (cancel-schedule, one-way, so it is a danger item); a scheduled post is canceled by Unpublish, as before. site-api v0.17.0 adds Rename… (a dialog with script, the editor without; a live post's address changes, so it needs a publisher), a preview link, and Move to Trash in place of Delete; a post in the Trash offers only Restore and Delete for good.

Parts and data attributes

ClassIs
.cap-poststhe root
.cap-posts-actionsa part
.cap-posts-bara part
.cap-posts-checka part
.cap-posts-counta part
.cap-posts-excerpta part
.cap-posts-extraa part
.cap-posts-extra-cella part
.cap-posts-metaa part
.cap-posts-nonea part
.cap-posts-notesa part
.cap-posts-pagesa part
.cap-posts-patha part
.cap-posts-previewa part
.cap-posts-preview-rowa part
.cap-posts-renamea part
.cap-posts-reschedulea part
.cap-posts-statusa part
.cap-posts-tablea part
.cap-posts-titlea part
.cap-posts-toolsa part
.cap-posts-trash-notea part
.cap-posts-update-sidea part
.cap-posts-update-side-whena part
.cap-posts-update-sidesa part
.cap-posts-update-viewa part
.cap-posts-updateda part
.cap-posts-whena part
.cap-posts-withhelda part
.cap-posts-wrapa part
AttributeValues
data-cap-partcancel-update
data-reflowpresent or absent
data-selectedpresent or absent
StateRead from
:emptythe platform
[open]an attribute

Accessibility

KeyDoes
TabThe status tabs, the filters, Show and Clear filters, the toolbar, the preview link and Copy (after one is made), the bulk bar (when something is ticked), the table, then each row's box, its title link and its menu, then the page links
Enter on a status tabShows that status (a link)
Space on a row's boxTicks or clears it; the bulk bar counts
Space on the header boxTicks or clears every post on the page
Esc, in the table or the barClears the selection
Enter on ActionsOpens the row's menu; the arrow keys move through it, Esc closes it
Enter on Rename…Opens the rename dialog with focus in it; Enter renames, Esc closes it
zUndo for the last action (the message region's key, or the list's own when the page has no region)
  • The list is a region named by its noun ("Posts"). The table is in a labeled, focusable scroll region whose caption names the site.
  • Each box and each row menu names its post ("Select Notes on the spring release", "Actions for Notes on the spring release"), so a column of them is not a column of the same name.
  • The bulk bar's count is a status; its outcome list is a group named by its line ("2 done, 1 not done."), each line a word and a shape.
  • The result is a status region; a failure is an alert. The confirm dialog is an alert dialog with focus on Cancel.
  • The preview link is a status region named "Preview link"; its field is named for the post and described by when the link stops working, and Copy says what it did there.
  • The rename dialog is a dialog named by its title ("Rename Notes on the spring release"), its field labeled "New slug" and described by what a slug may hold. The date fields are labeled "Published from" and "Published to".
  • After Move to Trash, Restore or Delete for good takes a post out of the list, focus goes to a defined place (above), never to the top of the page.
  • Status is never color alone. Text reaches 4.5:1 and edges 3:1 in both themes.