Skip to content

Writing progress

Today's writing in one panel, with words against target, streak, deadline pace and seven days.

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

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/writing-progress.css";
import { weekdayOf, dayTotals, writingDaysBetween } from "capsomer/behavior/writing-progress";

Usage

import { WritingProgress } from "capsomer/react/writing-progress";

<WritingProgress
  entries={entries}
  goal={goal}
  projectTarget={50000}
  deadline="2026-12-31"
  wordsNow={41200}
  zone={requestZone}
  canEdit
  Form={Form}
  error={result?.error}
  saved={result?.saved}
  goalNote={<>The target and deadline are in the <Link to={titlePage}>title page</Link>.</>}
/>

Examples

Target met, and the pace a deadline asks for

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

No target set, read only

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

The goal form refused, open on its answer

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

API reference

WritingProgress

PropTypeRequiredDoes
entriesSaveEntry[]YesThis writer's saves over the streak horizon: when, words typed, words removed.
goalGoalYes
projectTargetnumber | nullYesThe project's whole target and its deadline (YYYY-MM-DD), for a deadline's pace.
deadlinestringYes
wordsNownumberYesThe project's words now.
zonestringYesThe zone the server counted in (the request's, or UTC). The panel counts again in the device's.
canEditbooleanYesThe goal form is shown only to someone who may write here.
actionstringWhere the goal form posts, and the router's form. It posts intent=goal, mode, dailyTarget, writingDays (repeated) and allowNegative.
FormFormComponent
errorstring | nullThe goal form's answer: the refusal to show, or that it was saved.
savedboolean
goalNoteReactNodeA line in the goal form on where the project target and deadline are set.
noteReactNodeWhat counts as typed, under the figures.
sourcestringThe chart's source line.
titleReactNode
daysnumberHow many days the chart shows. Default 7.
nowDateA fixed "now", for a test or a specimen. Read once when the panel is drawn.

Functions

FunctionSignatureDoes
weekdayOf(day: string): numberThe weekday of a calendar day, 0 Sunday. Computed at noon UTC, which every zone shares as the same date.
dayTotals(entries: SaveEntry[], timeZone: string, allowNegative: boolean): Map<string, number>Words per local day: typed minus removed, held at zero unless the goal lets a day go negative.
writingDaysBetween(from: string, to: string, writingDays: number[]): numberWriting days from from to to, both included.
pace(input: { projectTarget: number | null; deadline: string; wordsNow: number; wordsToday: number; today: string; writingDays: number[]; }): PaceThe words a day needs to reach the project's target by its deadline: what was left when today began, spread over the writing days from today to the deadline. Today's own words do not lower today's target, so the number holds still while Dustin writes.
targetFor(goal: Goal, today: string, paced: Pace): number | nullToday's target, or null when there is none; a day off has none whatever the goal says.
streak(totals: Map<string, number>, today: string, target: number | null, writingDays: number[]): numberDays in a row the target was met, counting back from today. Today counts once it is met and does not break the run before then. A day off neither breaks the run nor adds to it, unless the target was met on it anyway. The target is today's: Carrel keeps no history of past targets.
recentDays(totals: Map<string, number>, today: string, n: number, writingDays: number[]): { day: string; words: number; writingDay: boolean; }[]The last n days, newest first, each with its words and whether it was a writing day.
parseWritingDays(stored: string): number[]"0123456" as stored, to weekday numbers; anything else in the string is dropped.
parseDailyTarget(typed: string): { ok: true; target: number | null; } | { ok: false; error: string; }A daily target as a person typed it: "1,500", "1 500" and "1500" are the same; empty is no target. Refused when it is not a whole number from 1 to MAX_DAILY_TARGET, with the sentence to show.
goalFromForm(input: { mode: string; dailyTarget: string; writingDays: string[]; allowNegative: boolean; }): { ok: true; goal: Goal; } | { ok: false; error: string; }A goal as a form posted it, checked: the mode, the target, at least one writing day.
untypedCount(value: unknown): numberAn untyped count a form posted: a whole number of words, 0 for anything else.
untypedTally(): { add(words: number): void; send(): number; settled(ok: boolean): void; reset(): void; readonly pending: number; }The words pasted or dropped into an editor and not yet reported: they reach the file but were not typed, so the day's count leaves them out. add on each paste or drop; send when a save posts (the count to send with it); settled(ok) when the save is done, which takes what it carried off only if the server has it; reset when the text is replaced (a discard, an AI draft taken).
weekdayName(day: string): stringThe weekday's name of a calendar day.
paceLine(paced: Pace, deadline: string): stringThe pace a deadline asks for, or why there is none, in a sentence.
weekSentence(days: readonly { day: string; words: number; writingDay: boolean; }[], target: number | null): stringThe sentence that says what the last days' chart shows, with its numbers. Days newest first.

Parts and data attributes

ClassIs
.cap-progress-bodythe root
.cap-progress-daysits own class
.cap-progress-formits own class
.cap-progress-lineits own class
.cap-progress-noteits own class
StateRead from
:emptythe platform

Accessibility

KeyDoes
TabThe chart's controls, then "Your target", then the goal form's fields in order
Enter or Space on "Your target"Opens or closes the goal form
Arrow keys in the modeChoose by hand or from the deadline
Space on a writing dayTicks or unticks it
  • The meter has its value in words (valueText: "320 of 500 words typed today."); the bar is never alone.
  • The chart is a sentence, a picture and a table (the chart frame).
  • The goal form's groups are fieldsets with legends; a refusal is an alert.
  • "Target met" is a status with its shape and word.