Skip to content

Generated file

A panel for a file the server makes, showing its state, its download and a Generate button.

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

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/generated-file.css";
import { fileState, mayStart, fileMeta } from "capsomer/behavior/generated-file";

Usage

<section class="cap-panel cap-generated">
  <header class="cap-panel-head">
    <h2>Program PDF</h2>
    <p class="cap-panel-desc">Made from the schedule. It can take up to a minute.</p>
  </header>
  <div class="cap-panel-body">
    <div class="cap-generated-body" data-state="ready">
      <p class="cap-generated-status" role="status">
        <span class="cap-status" data-tone="ok">[ok glyph]Ready</span>
        <span class="cap-generated-says">Made <time class="cap-time" datetime="2027-02-19T21:04:00.000Z" data-format="exact">February 19, 2027, 9:04 PM UTC</time>.</span>
      </p>
      <p class="cap-generated-file"><a href="/program/download" data-link="file" download>Download the PDF</a> <span class="cap-link-meta">PDF, 2.4 MB</span></p>
    </div>
  </div>
  <footer class="cap-panel-foot">
    <div class="cap-generated-actions">
      <form method="post" class="cap-generated-form">
        <input type="hidden" name="intent" value="document-generate">
        <button type="submit" class="cap-btn">Regenerate the PDF</button>
      </form>
      [Publish to the archive]
    </div>
  </footer>
</section>
// On the server, before a run:
if (!mayStart(row && { status: row.genStatus, startedAt: row.updatedAt }, Date.now())) throw new ValidationError("A file is already being made.");
<GeneratedFile title="Program PDF" description="Made from the schedule. It can take up to a minute."
  record={{ status: doc.genStatus, startedAt: doc.updatedAt, generatedAt: doc.generatedAt, bytes: doc.size, changedAt: program.updatedAt }}
  downloadHref={`/admin/editions/${id}/program-document/download`}
  fields={{ intent: "document-generate" }} busy={navigation.state === "submitting"}
  renderForm={({ className, children }) => <Form method="post" className={className}>{children}</Form>}>
  [Publish to the archive]
</GeneratedFile>

Examples

Generating, first run

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

Regenerating, the earlier file kept

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

Ready, with its size and date, and a Publish action

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

Stale: the data changed after it was made

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

Failed, with the reason

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

A run that stopped without finishing

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

The form being sent

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

Made by another step, with no Generate button

<div data-mount="made-elsewhere"></div>

API reference

GeneratedFile

PropTypeRequiredDoes
titleReactNodeYesThe panel's heading: "Program PDF".
descriptionReactNodeWhat the file is made from and how long a run takes.
recordGeneratedRecord | null | undefinedYesWhat the store recorded; null when nothing has run.
nownumberA fixed now, for a report or a test.
lockMsnumberHow long a run holds the lock (default LOCK_MS, 5 minutes).
formatstringThe file's format, said beside the link with its size: "PDF".
downloadHrefstringYes
downloadLabelstring
generateLabelstringThe button's words before a first run, and after.
regenerateLabelstring
actionstringThe form: its action and hidden fields ({ intent: "document-generate" }), or a router's Form drawn by renderForm, which is given the class and the button.
fieldsRecord<string, string>
renderForm(props: GeneratedFileFormProps) => ReactNode
generatebooleanfalse: no Generate form, for a file another step makes (a book PDF made on publish); the panel then only says the state and offers the file.
busybooleanThe form is being sent: the button says so and takes no second press.
messagesPartial<Record<GeneratedState, ReactNode>>The sentence after a state's word, in the app's own words, in place of the default.
level2 | 3
childrenReactNodeMore of the file's actions, after Generate: Publish to the archive.

Functions

FunctionSignatureDoes
fileState(rec: GeneratedRecord | null | undefined, now?: number, lockMs?: number): GeneratedViewThe state a record is in, at now.
mayStart(rec: GeneratedRecord | null | undefined, now?: number, lockMs?: number): booleanThe server's rule before it starts a run: refuse a second one while a live run holds the lock.
fileMeta(format: string, bytes: number | null): string"PDF, 2.4 MB": what the download link's meta says.

Parts and data attributes

ClassIs
.cap-generated-actionsits own class
.cap-generated-bodyits own class
.cap-generated-filethe root
.cap-generated-formits own class
.cap-generated-saysits own class
.cap-generated-statusits own class

Accessibility

KeyDoes
Tab, Shift+TabMoves to the download link, the Generate button, then the file's other actions
EnterFollows the download link, or presses the focused button
SpacePresses the focused button
  • A panel (section with a heading at level). The status is a live region.
  • The state is a word with its glyph, never color alone; the sentence is --muted (4.5:1), the size --muted.
  • A disabled Generate says "Generating", so the reason it is disabled is on the button.