components/content/content.ts

Functions

Imports

It imports components/bulk-bar/bulk-bar.ts, components/media/media.ts, components/moderation-queue/moderation-queue.ts. Imported by components/content/content.react.tsx, components/media-library/examples.tsx, components/media-library/media-library.react.tsx, components/media-library/media-library.ts, components/mentions-list/examples.tsx, components/mentions-list/mentions-list.react.tsx, components/mentions-list/mentions-list.ts, components/posts-list/examples.tsx, components/posts-list/posts-list.react.tsx, components/posts-list/posts-list.ts.

Source

1// capsomer/content: the view data the shared content components take, what their forms get back,
2// and the two pure helpers every one of them uses to post an intent and read its outcomes.
3//
4// The design (docs/design/design-content-components.md, sections 2.2 to 2.4) puts the server half,
5// the "content kit", in site-api (job "site-api: the content kit and localClient", S1). That kit
6// had not shipped when these were written, so they are defined here from the design and are to be
7// reconciled with S1's own types when it does. Where a name came from the site-api contract
8// (v0.5.0, src/contract.ts) it is kept: ContentStatus, MediaUse, MentionStatus, MentionCounts.
9import type { BulkOutcome } from "../bulk-bar/bulk-bar.ts";
10import type { MediaRecord } from "../media/media.ts";
11import type { Mention, ModState, ModView } from "../moderation-queue/moderation-queue.ts";
12
13// ---------------------------------------------------------------------------------------
14// Shared by every list.
15
16// A post's state on its site. The contract's own words.
17export type ContentStatus = "draft" | "scheduled" | "published";
18
19// What this person may do here, decided by the host (Carrel's roles, or a site admin signed in
20// through Access, who gets everything). The kit refuses an intent the person may not run, whatever
21// the form says; the component only hides what is refused.
22export interface ContentCan {
23  edit: boolean;
24  publish: boolean;
25  deleteContent: boolean;
26  deleteMedia: boolean;
27  decideMentions: boolean;
28}
29
30// A word under a row's title that only the host knows: "2 AI drafts waiting", "New draft",
31// "Held by a flag". A tone draws it as a status pill; without one it is a quiet pill.
32export interface RowNote {
33  text: string;
34  tone?: "info" | "ok" | "warn" | "crit";
35}
36
37// What a one-way action asks before it runs: the confirm dialog's title, lead and button, and the
38// word to type for what cannot be recovered.
39export interface ConfirmSpec {
40  title: string;
41  lead?: string;
42  action: string;
43  typeToConfirm?: string;
44}
45
46// A host's own toolbar action (dustinedwards.info's Ask index maintenance), posted as `intent`
47// and run by the host's own handler. Rendered in a fixed place with fixed markup.
48export interface ExtraAction {
49  intent: string;
50  label: string;
51}
52
53// A host's own column, already rendered to text by the kit: one cell per row id.
54export interface ExtraColumn {
55  id: string;
56  label: string;
57  cells: Record<string, string>;
58}
59
60// One page of a list, by cursor. `total` arrives with site-api v0.6; until then the count says
61// what is on the page.
62export interface PageInfo {
63  nextCursor: string | null;
64  prevCursor?: string | null;
65  total?: number;
66  // True while the site cannot sort (site-api v0.5): the kit sorted this page only, and the
67  // list says so.
68  sortedOnPage?: boolean;
69}
70
71// One place a file is used, as the site's reference check found it (site-api MediaUse).
72export interface MediaUse {
73  type: string;
74  id: string;
75  title: string;
76  detail: string;
77}
78
79// The fields a form posts, as the kit reads them back: `ids` repeats.
80export type IntentFields = Record<string, string | string[]>;
81
82// One item's outcome of an intent that acted on several. A refusal for one never stops the others.
83export interface IntentOutcome {
84  id: string;
85  ok: boolean;
86  message?: string;
87  // On a refused media delete: every place the file is used.
88  usedBy?: MediaUse[];
89}
90
91// The kit asks before a one-way intent: the component shows this as the confirm dialog (with
92// script) or the confirm page (without), and posting it again with `fields` performs it. The
93// typed word, when asked, is posted as `confirm`.
94export interface ConfirmRequest extends ConfirmSpec {
95  intent: string;
96  // Every item it will change, one line each. Never shortened.
97  items: string[];
98  fields: IntentFields;
99}
100
101// What a posted intent gives back, for the message region, the bulk bar's outcome list and Undo.
102export interface IntentResult {
103  ok: boolean;
104  // One sentence for the message region: "Unpublished 2 posts."
105  message: string;
106  outcomes?: IntentOutcome[];
107  // The inverse, versions included: posting it undoes this result. Absent where nothing can
108  // undo it (a first decision on a waiting mention before site-api v0.6, a duplicate on a site
109  // with no delete).
110  undo?: { intent: string; fields: IntentFields };
111  // The item changed since it was read: what the site holds now.
112  conflict?: { id: string; currentVersion: string | null };
113  // Asked before a one-way intent runs. Nothing has changed yet.
114  confirm?: ConfirmRequest;
115}
116
117// The script path: a host passes a function that posts the form and resolves with the action's
118// result (in React Router, a useFetcher wrapper). Without it the forms post and the page reloads
119// with `result`.
120export type SubmitIntent = (form: FormData) => Promise<IntentResult>;
121
122// Words a host needs to change: the thing the list holds ("post", "article") and its plural.
123export interface ContentLabels {
124  noun?: string;
125  plural?: string;
126}
127
128// ---------------------------------------------------------------------------------------
129// Posts.
130
131export type PostSort = "updated" | "published" | "title";
132
133export interface PostsQuery {
134  q?: string;
135  status?: ContentStatus;
136  kind?: string;
137  tag?: string;
138  sort?: PostSort;
139  cursor?: string;
140}
141
142// What the site supports, read from its capabilities by the kit.
143export interface PostOffers {
144  delete: boolean;
145  schedule: boolean;
146  tags: boolean;
147  duplicate: boolean;
148}
149
150export interface PostRow {
151  id: string;
152  title: string;
153  kind: string;
154  status: ContentStatus;
155  // The public path once published; null while never published.
156  path: string | null;
157  // Where the title links: Carrel's editor, or the site's own.
158  href: string;
159  // The live page, for "View on the site". Published posts only.
160  liveHref: string | null;
161  publishAt: string | null;
162  publishedAt: string | null;
163  updatedAt: string | null;
164  // Present from site-api v0.6; the kit reads each post before writing otherwise.
165  version?: string;
166  tags?: string[];
167  notes?: RowNote[];
168}
169
170export interface PostsData {
171  site: { name: string };
172  query: PostsQuery;
173  rows: PostRow[];
174  page: PageInfo;
175  // Across the whole site, not the page, for the status tabs.
176  counts?: Partial<Record<ContentStatus | "all", number>>;
177  kinds: string[];
178  offers: PostOffers;
179  can: ContentCan;
180  // "New post": the editor with a new id. Absent where the person may not write.
181  newHref?: string;
182  // Per-site additions, already rendered to data.
183  extra?: { columns?: ExtraColumn[]; toolbar?: ExtraAction[] };
184}
185
186// ---------------------------------------------------------------------------------------
187// Media.
188
189export interface MediaQuery {
190  q?: string;
191  tag?: string;
192  // The library, or the trash (with mediaTrash).
193  view?: "library" | "trash";
194  // Tiles or rows, kept in the address.
195  layout?: "grid" | "list";
196  // A host's lens (dustinedwards.info's unattached, duplicates): extensions until site-api v0.6.
197  lens?: string;
198  cursor?: string;
199  // The file the inspector is open on: the kit reads it with where it is used.
200  inspect?: string;
201  // Picker mode: the file chosen, waiting for its alt text.
202  pick?: string;
203}
204
205// What the site supports, read from its capabilities by the kit. `upload` is the site's own limits
206// (capabilities.mediaUpload), checked before any byte is sent; null where it takes no uploads.
207export interface MediaOffers {
208  upload: { maxBytes: number; types: string[] } | null;
209  alt: boolean;
210  tags: boolean;
211  trash: boolean;
212  delete: boolean;
213}
214
215export interface MediaData {
216  site: { name: string };
217  query: MediaQuery;
218  // One page of files, as the media component's records: `used` filled where the kit read it,
219  // `usedUnknown` where it did not (a list has no usedBy; the inspected file does).
220  rows: MediaRecord[];
221  page: PageInfo;
222  counts?: { library?: number; trash?: number };
223  // The tags in use, for the chip row, with how many files carry each where the kit knows.
224  tags: Array<{ tag: string; count?: number }>;
225  offers: MediaOffers;
226  can: ContentCan;
227  // The file in the inspector (?inspect=), read with every place it is used.
228  inspected?: MediaRecord | null;
229  // Per-site additions, already rendered to data: lenses (dustinedwards.info's unattached,
230  // duplicates, no alt), and toolbar actions.
231  extra?: { lenses?: Array<{ id: string; label: string; count?: number }>; toolbar?: ExtraAction[] };
232}
233
234// What the picker gives the host: the file and the alt text the person wrote for this use ("" when
235// they said it is decorative).
236export interface PickedMedia {
237  id: string;
238  url: string;
239  alt: string;
240}
241
242// ---------------------------------------------------------------------------------------
243// Mentions.
244
245// A mention's state, the contract's own words (site-api MentionStatus).
246export type MentionStatus = ModState;
247
248// How many mentions are in each state across the whole site, not the page (site-api
249// MentionCounts), with their sum.
250export type MentionCounts = Record<MentionStatus | "all", number>;
251
252export interface MentionsQuery {
253  // The tab. With none, the list opens on Waiting, or on All when nothing waits.
254  view?: ModView;
255  cursor?: string;
256  // The mention opened in place (its whole excerpt, its source, the exact times).
257  open?: string;
258}
259
260// What the site supports, read from its capabilities by the kit. `reset` is site-api v0.6's
261// decision "reset" (back to waiting): without it a decision on a waiting mention has no Undo.
262export interface MentionOffers {
263  reset: boolean;
264  delete: boolean;
265  sweep: boolean;
266}
267
268export interface MentionsData {
269  site: { name: string };
270  query: MentionsQuery;
271  // One page of mentions, newest first, each as the moderation queue's Mention.
272  rows: Mention[];
273  page: PageInfo;
274  counts: MentionCounts;
275  // What the next sweep removes, by the site's own retention (site-api MentionList.expiring).
276  expiring: { failed: number; rejected: number };
277  // The site's retention in words, from its rules: "A mention whose source was not found is
278  // removed after 30 days, a rejected one after 90."
279  retention?: string;
280  offers: MentionOffers;
281  can: ContentCan;
282}
283
284// ---------------------------------------------------------------------------------------
285// The script path, pure.
286
287// The form an IntentResult's undo, or a confirm request, posts: the intent and its fields, a list
288// value as one field per item.
289// A list's address with a query, its keys in one fixed order and the empty ones left out, so the
290// same view is always the same address. `base` is the route (any query on it is dropped).
291export function queryHref<Q extends object>(base: string, q: Q, order: ReadonlyArray<keyof Q>): string {
292  const params = new URLSearchParams();
293  for (const k of order) {
294    const v = q[k];
295    if (typeof v === "string" && v) params.set(String(k), v);
296  }
297  const path = base.split("?")[0] || "";
298  const s = params.toString();
299  return s ? `${path}?${s}` : path || "?";
300}
301
302export function intentForm(intent: string, fields: IntentFields = {}): FormData {
303  const form = new FormData();
304  form.set("intent", intent);
305  for (const [k, v] of Object.entries(fields)) {
306    if (k === "intent") continue;
307    for (const one of typeof v === "string" ? [v] : v) form.append(k, one);
308  }
309  return form;
310}
311
312// A result's outcomes as the bulk bar lists them, each named as the person knows it. An item that
313// is gone (deleted) keeps the name it had when the form was posted.
314export function outcomesOf(result: Pick<IntentResult, "outcomes">, names: ReadonlyMap<string, string>): BulkOutcome[] {
315  return (result.outcomes ?? []).map((o) => ({
316    id: o.id,
317    label: names.get(o.id) ?? o.id,
318    ok: o.ok,
319    message: o.message,
320    usedBy: o.usedBy?.map((u) => (u.detail ? `${u.title} (${u.detail})` : u.title)),
321  }));
322}