components/posts-list/posts-list.ts

Functions

Imports

It imports components/content/content.ts, components/time/time.ts. Imported by components/posts-list/posts-list.react.tsx.

Source

1// The posts list's pure helpers: the status of a post in words, the addresses of its filters,
2// which actions a person is offered here and why the others are withheld, and the forms the
3// script path posts. No DOM; the React component and a server render use the same functions.
4import { DAY } from "../time/time.ts";
5import { queryHref, type ContentLabels, type ContentStatus, type PostRow, type PostsData, type PostsQuery, type PostSort } from "../content/content.ts";
6
7// ---------------------------------------------------------------------------------------
8// Status.
9
10export interface ContentStatusWords {
11  // The status component's tone: Published is ok (a tick), Scheduled is a notice (a square),
12  // Draft is no data yet (an empty circle with a bar). Shape, word and colour together.
13  tone: "ok" | "info" | "nodata";
14  word: string;
15  // For a scheduled post: when it goes out, "in 3 days", "today", "tomorrow", "due now".
16  when?: string;
17}
18
19const utcDay = (ms: number) => Math.floor(ms / DAY);
20
21// How far off a scheduled time is, in whole UTC days. Past it, the site has not published it yet.
22export function inDays(at: string, now: number): string {
23  const t = Date.parse(at);
24  if (!Number.isFinite(t)) return "";
25  if (t <= now) return "due now";
26  const days = utcDay(t) - utcDay(now);
27  if (days <= 0) return "today";
28  if (days === 1) return "tomorrow";
29  return `in ${days} days`;
30}
31
32// The one mapping from a content status to its words, for every list and editor that shows one
33// (Carrel wrote it inline six times).
34export function contentStatus(status: ContentStatus, publishAt: string | null = null, now: number = Date.now()): ContentStatusWords {
35  switch (status) {
36    case "published":
37      return { tone: "ok", word: "Published" };
38    case "scheduled":
39      return publishAt ? { tone: "info", word: "Scheduled", when: inDays(publishAt, now) } : { tone: "info", word: "Scheduled" };
40    case "draft":
41      return { tone: "nodata", word: "Draft" };
42  }
43}
44
45// ---------------------------------------------------------------------------------------
46// Words.
47
48export function nounsOf(labels: ContentLabels = {}): { noun: string; plural: string } {
49  const noun = labels.noun ?? "post";
50  return { noun, plural: labels.plural ?? `${noun}s` };
51}
52
53export const STATUS_TABS: ReadonlyArray<{ status: ContentStatus | undefined; label: string }> = [
54  { status: undefined, label: "All" },
55  { status: "draft", label: "Drafts" },
56  { status: "scheduled", label: "Scheduled" },
57  { status: "published", label: "Published" },
58];
59
60export const SORTS: ReadonlyArray<{ value: PostSort; label: string }> = [
61  { value: "updated", label: "Last updated" },
62  { value: "published", label: "Last published" },
63  { value: "title", label: "Title" },
64];
65
66// "12 posts", "Showing 50 of 120 posts", and a note when the site could only sort this page.
67export function countLine(data: Pick<PostsData, "rows" | "page">, labels?: ContentLabels): string {
68  const { noun, plural } = nounsOf(labels);
69  const n = data.rows.length;
70  const total = data.page.total;
71  const word = (k: number) => (k === 1 ? noun : plural);
72  const base = total != null && total > n ? `Showing ${n} of ${total} ${word(total)}` : `${n} ${word(n)}`;
73  return data.page.sortedOnPage ? `${base}, sorted on this page only` : base;
74}
75
76// Filters in the query other than the page and the order: what the empty state says is hiding rows.
77export function filtered(q: PostsQuery): boolean {
78  return !!(q.q || q.kind || q.tag);
79}
80
81// The empty state's title and line, naming what is not there.
82export function emptyWords(q: PostsQuery, labels?: ContentLabels): { kind: "nothing-yet" | "no-match"; title: string; text: string } {
83  const { plural } = nounsOf(labels);
84  if (filtered(q)) {
85    const what = [q.q ? `“${q.q}”` : null, q.kind ? `kind ${q.kind}` : null, q.tag ? `tag ${q.tag}` : null].filter(Boolean).join(", ");
86    return { kind: "no-match", title: `No ${plural} match ${what}`, text: "Clear the filters to see every one." };
87  }
88  switch (q.status) {
89    case "draft":
90      return { kind: "nothing-yet", title: "No drafts", text: `Every ${nounsOf(labels).noun} here is scheduled or published.` };
91    case "scheduled":
92      return { kind: "nothing-yet", title: "Nothing scheduled", text: "A scheduled post shows here until it goes out." };
93    case "published":
94      return { kind: "nothing-yet", title: "Nothing published yet", text: "Published posts show here." };
95    default:
96      return { kind: "nothing-yet", title: `No ${plural} yet`, text: `The first ${nounsOf(labels).noun} you start shows here.` };
97  }
98}
99
100// ---------------------------------------------------------------------------------------
101// Addresses.
102
103const QUERY_ORDER: ReadonlyArray<keyof PostsQuery> = ["q", "status", "kind", "tag", "sort", "cursor"];
104
105// The list's address with a query (content.ts, queryHref).
106export function postsHref(base: string, q: PostsQuery): string {
107  return queryHref(base, q, QUERY_ORDER);
108}
109
110// A filter link changes one thing and starts again at the first page.
111export function withFilter(q: PostsQuery, change: Partial<PostsQuery>): PostsQuery {
112  const next: PostsQuery = { ...q, ...change };
113  delete next.cursor;
114  for (const k of Object.keys(change) as Array<keyof PostsQuery>) if (change[k] === undefined) delete next[k];
115  return next;
116}
117
118// ---------------------------------------------------------------------------------------
119// What is offered.
120
121export type PostIntent = "add-tag" | "remove-tag" | "duplicate" | "unpublish" | "delete";
122
123export interface OfferedAction {
124  intent: PostIntent;
125  label: string;
126  destructive?: boolean;
127}
128
129// The bulk actions this person may run on this site, in the bar's order, and a sentence for each
130// one held back, so a missing button is never a mystery. An action shows only when the site
131// offers it (data.offers) and the person may run it (data.can).
132export function postActions(data: Pick<PostsData, "offers" | "can">, labels?: ContentLabels): { bulk: OfferedAction[]; withheld: string[] } {
133  const { plural } = nounsOf(labels);
134  const { offers, can } = data;
135  const bulk: OfferedAction[] = [];
136  const withheld: string[] = [];
137  if (can.edit && offers.tags) bulk.push({ intent: "add-tag", label: "Add tag" }, { intent: "remove-tag", label: "Remove tag" });
138  if (can.edit && offers.duplicate) bulk.push({ intent: "duplicate", label: "Duplicate" });
139  if (can.publish) bulk.push({ intent: "unpublish", label: "Unpublish" });
140  if (can.deleteContent && offers.delete) bulk.push({ intent: "delete", label: "Delete", destructive: true });
141  if (!can.edit) withheld.push(`You can read these ${plural}. Changing them needs an editor's role.`);
142  else if (!offers.tags) withheld.push(`Tags are not offered: this site keeps no tags on its ${plural}.`);
143  if (can.edit && !offers.duplicate) withheld.push(`Duplicate is not offered by this site.`);
144  if (can.edit && !can.publish) withheld.push(`Unpublishing needs a publisher's role.`);
145  if (can.deleteContent && !offers.delete) withheld.push(`Delete is not offered: this site cannot delete ${plural}.`);
146  return { bulk, withheld };
147}
148
149export interface RowAction {
150  label: string;
151  value: string;
152  href?: string;
153  danger?: boolean;
154}
155
156// One row's menu: Edit and View on the site go somewhere; the rest post an intent for this row.
157export function rowActions(row: PostRow, data: Pick<PostsData, "offers" | "can">): RowAction[] {
158  const { offers, can } = data;
159  const items: RowAction[] = [];
160  if (can.edit) items.push({ label: "Edit", value: "edit", href: row.href });
161  if (row.status === "published" && row.liveHref) items.push({ label: "View on the site", value: "view", href: row.liveHref });
162  if (can.publish && row.status !== "draft") items.push({ label: "Unpublish", value: "unpublish" });
163  if (can.edit && offers.duplicate) items.push({ label: "Duplicate", value: "duplicate" });
164  if (can.deleteContent && offers.delete) items.push({ label: "Delete", value: "delete", danger: true });
165  return items;
166}
167
168// ---------------------------------------------------------------------------------------
169// The script path's helpers live with the shared types; still exported from here.
170export { intentForm, outcomesOf } from "../content/content.ts";