@charcuterie/ui 3.0.0 → 3.1.0

package/src/DatePicker/plainDate.ts

@@ -0,0 +1,465 @@
+/**
+ * A calendar date, and deliberately not an instant.
+ *
+ * ### The bug this file exists to make impossible
+ *
+ * A due date is not a moment. "This is due on the 19th" is true in
+ * Denver and true in Tokyo, and it does not become the 18th because
+ * a laptop crossed a meridian. The classic date-picker defect is
+ * that the value is a `Date` — which is an instant, a count of
+ * milliseconds — and every read of it goes through the *browser's*
+ * timezone. Pick the 19th at 23:30 in Denver, store
+ * `new Date("2026-08-19").toISOString()`, and the server, the next
+ * device, and the same device after a flight all disagree about
+ * which day you meant. It is a one-day error, it only appears near
+ * midnight or after travel, and it is invisible in every test
+ * written at noon.
+ *
+ * So the value here is a **plain date**: a year, a month, and a day,
+ * with no time, no offset, and no zone. It is stored as an ISO
+ * `YYYY-MM-DD` string — which is exactly `<input type="date">`'s own
+ * `value` format, so a consumer can move between this component and
+ * the native control without a migration.
+ *
+ * ### There is no `Date` arithmetic in here at all
+ *
+ * Not "carefully-written `Date` arithmetic" — none. Every operation
+ * below is integer maths on a **day number**: the count of days
+ * since 1970-01-01, computed with Howard Hinnant's `days_from_civil`
+ * / `civil_from_days` (public domain, the algorithm C++20's
+ * `<chrono>` and Rust's `chrono` both use). Adding a day is `+ 1`.
+ * That is a proleptic Gregorian calendar with no DST, no leap
+ * seconds, and no zone, which is what a calendar date actually is.
+ *
+ * A `Date` appears in exactly two places, both of them named and
+ * both of them fenced:
+ *
+ *  - `getLocalPlainDate`, which is the **one** conversion from an
+ *    instant to a calendar date, and which requires you to say
+ *    which zone's calendar you mean.
+ *  - `formatPlainDate` and its callers, which hand `Intl` a date
+ *    built at UTC midnight and format it with `timeZone: "UTC"`, so
+ *    the formatter cannot shift the day either.
+ *
+ * `plainDate.test.ts` re-runs the whole suite under four `TZ`
+ * values, including UTC+14 and UTC-11, and asserts every answer is
+ * byte-identical.
+ *
+ * ### Why not `Temporal`
+ *
+ * `Temporal.PlainDate` is this type, done properly, and it is
+ * available in the Node this repo builds on. It is not available in
+ * every browser a published package has to run in, and the polyfill
+ * is ~50 KB gz — an order of magnitude more than this entire
+ * component. The functions below are the ~80 lines of it a date
+ * picker needs. When `Temporal` is baseline, this file becomes a
+ * thin adapter and the public API — ISO strings — does not change,
+ * which is the reason the API is ISO strings.
+ */
+
+/** Year, month (1-12), day (1-31). No time, no zone. */
+export type PlainDate = {
+  day: number
+  month: number
+  year: number
+}
+
+/**
+ * A start and an end, either of which may be absent — because a
+ * half-picked range is a real state a user spends time in, not an
+ * error. `start` with a null `end` is "I have clicked once".
+ */
+export type DateRange = {
+  end: null | string
+  start: null | string
+}
+
+const MONTH_LENGTHS = [
+  31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31,
+]
+
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/
+
+export const getIsLeapYear = (year: number): boolean =>
+  (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0
+
+export const getDaysInMonth = (
+  year: number,
+  month: number,
+): number =>
+  month === 2 && getIsLeapYear(year)
+    ? 29
+    : (MONTH_LENGTHS[month - 1] ?? 30)
+
+export const getIsValidPlainDate = ({
+  day,
+  month,
+  year,
+}: PlainDate): boolean =>
+  Number.isInteger(year) &&
+  Number.isInteger(month) &&
+  Number.isInteger(day) &&
+  year >= 1 &&
+  year <= 9999 &&
+  month >= 1 &&
+  month <= 12 &&
+  day >= 1 &&
+  day <= getDaysInMonth(year, month)
+
+/**
+ * Days since 1970-01-01, by Hinnant's `days_from_civil`.
+ *
+ * Every other operation in this file is expressed through this and
+ * its inverse, which is why "add a month, then add 40 days, then
+ * ask what weekday it is" cannot drift: there is one representation
+ * and it is an integer.
+ */
+export const getDayNumber = ({
+  day,
+  month,
+  year,
+}: PlainDate): number => {
+  const shiftedYear = year - (month <= 2 ? 1 : 0)
+
+  const era = Math.floor(shiftedYear / 400)
+
+  const yearOfEra = shiftedYear - era * 400
+
+  const dayOfYear =
+    Math.floor(
+      (153 * (month + (month > 2 ? -3 : 9)) + 2) / 5,
+    ) +
+    day -
+    1
+
+  const dayOfEra =
+    yearOfEra * 365 +
+    Math.floor(yearOfEra / 4) -
+    Math.floor(yearOfEra / 100) +
+    dayOfYear
+
+  return era * 146097 + dayOfEra - 719468
+}
+
+/** The inverse — Hinnant's `civil_from_days`. */
+export const getPlainDateFromDayNumber = (
+  dayNumber: number,
+): PlainDate => {
+  const shifted = dayNumber + 719468
+
+  const era = Math.floor(shifted / 146097)
+
+  const dayOfEra = shifted - era * 146097
+
+  const yearOfEra = Math.floor(
+    (dayOfEra -
+      Math.floor(dayOfEra / 1460) +
+      Math.floor(dayOfEra / 36524) -
+      Math.floor(dayOfEra / 146096)) /
+      365,
+  )
+
+  const dayOfYear =
+    dayOfEra -
+    (365 * yearOfEra +
+      Math.floor(yearOfEra / 4) -
+      Math.floor(yearOfEra / 100))
+
+  const monthPrime = Math.floor((5 * dayOfYear + 2) / 153)
+
+  const day =
+    dayOfYear - Math.floor((153 * monthPrime + 2) / 5) + 1
+
+  const month = monthPrime + (monthPrime < 10 ? 3 : -9)
+
+  return {
+    day,
+    month,
+    year: yearOfEra + era * 400 + (month <= 2 ? 1 : 0),
+  }
+}
+
+export const addDays = (
+  date: PlainDate,
+  days: number,
+): PlainDate =>
+  getPlainDateFromDayNumber(getDayNumber(date) + days)
+
+/**
+ * Month arithmetic clamps the day rather than overflowing, which is
+ * the answer every calendar app gives and the one `Date` does not:
+ * `new Date(2026, 0, 31)` plus a month is **3 March**, because 31
+ * February rolls forward. One month after 31 January is 28
+ * February.
+ */
+export const addMonths = (
+  date: PlainDate,
+  months: number,
+): PlainDate => {
+  const monthIndex =
+    date.year * 12 + (date.month - 1) + months
+
+  const year = Math.floor(monthIndex / 12)
+
+  const month = monthIndex - year * 12 + 1
+
+  return {
+    day: Math.min(date.day, getDaysInMonth(year, month)),
+    month,
+    year,
+  }
+}
+
+export const comparePlainDates = (
+  first: PlainDate,
+  second: PlainDate,
+): number => getDayNumber(first) - getDayNumber(second)
+
+export const getIsSameDay = (
+  first: PlainDate,
+  second: PlainDate,
+): boolean => comparePlainDates(first, second) === 0
+
+/**
+ * Whole days from `from` to `to`. Docket's staleness threshold is
+ * counted in days, and this is the subtraction that counts it —
+ * with no hour-of-day and no DST to make "14 days" occasionally mean
+ * 13.958.
+ */
+export const getDaysBetween = (
+  from: PlainDate,
+  to: PlainDate,
+): number => getDayNumber(to) - getDayNumber(from)
+
+export const clampPlainDate = (
+  date: PlainDate,
+  minimum?: PlainDate,
+  maximum?: PlainDate,
+): PlainDate => {
+  if (minimum && comparePlainDates(date, minimum) < 0) {
+    return minimum
+  }
+
+  if (maximum && comparePlainDates(date, maximum) > 0) {
+    return maximum
+  }
+
+  return date
+}
+
+export const getIsWithinRange = (
+  date: PlainDate,
+  minimum?: PlainDate,
+  maximum?: PlainDate,
+): boolean =>
+  (!minimum || comparePlainDates(date, minimum) >= 0) &&
+  (!maximum || comparePlainDates(date, maximum) <= 0)
+
+/**
+ * 0 is Sunday, 6 is Saturday — the numbering `Intl`'s `weekday`
+ * option and `Date.prototype.getDay` both use, so the two never
+ * need reconciling at a call site.
+ *
+ * Day number 0 (1970-01-01) was a Thursday, which is the `+ 4`.
+ */
+export const getWeekday = (date: PlainDate): number => {
+  const dayNumber = getDayNumber(date)
+
+  return ((((dayNumber % 7) + 7) % 7) + 4) % 7
+}
+
+const pad = (value: number, length: number) =>
+  String(value).padStart(length, "0")
+
+export const toIsoDate = (date: PlainDate): string =>
+  `${pad(date.year, 4)}-${pad(date.month, 2)}-${pad(date.day, 2)}`
+
+/**
+ * `null` rather than a throw, and `null` rather than a "best
+ * effort" date. A string that is not a calendar date has no nearest
+ * calendar date, and inventing one is the silent-guess failure this
+ * component is built to avoid.
+ */
+export const parseIsoDate = (
+  isoDate: null | string | undefined,
+): null | PlainDate => {
+  if (!isoDate) {
+    return null
+  }
+
+  const match = ISO_DATE_PATTERN.exec(isoDate)
+
+  if (!match) {
+    return null
+  }
+
+  const date = {
+    day: Number(match[3]),
+    month: Number(match[2]),
+    year: Number(match[1]),
+  }
+
+  return getIsValidPlainDate(date) ? date : null
+}
+
+/**
+ * A `Date` pinned at UTC midnight, for `Intl` and for nothing else.
+ *
+ * `Date.UTC` is not used, because it maps years 0-99 onto 1900-1999
+ * — a two-digit year silently becomes the twentieth century inside
+ * the formatter, which is a bug the *parser* takes an explicit
+ * position on and the formatter has no business re-deciding.
+ */
+const toUtcInstant = (date: PlainDate) => {
+  const instant = new Date(0)
+
+  instant.setUTCFullYear(
+    date.year,
+    date.month - 1,
+    date.day,
+  )
+  instant.setUTCHours(0, 0, 0, 0)
+
+  return instant
+}
+
+export type PlainDateFormatOptions =
+  Intl.DateTimeFormatOptions & {
+    locale?: string
+  }
+
+/**
+ * `timeZone: "UTC"` is forced, and it is not configurable.
+ *
+ * The instant above is UTC midnight, so formatting it in any other
+ * zone renders the previous or the next day — which is the same
+ * one-day error as storing an instant, arriving through the display
+ * layer instead. There is no legitimate reason to format a calendar
+ * date in a zone: the date *is* the answer.
+ */
+export const formatPlainDate = (
+  date: PlainDate,
+  { locale, ...options }: PlainDateFormatOptions = {},
+): string =>
+  new Intl.DateTimeFormat(locale, {
+    ...options,
+    timeZone: "UTC",
+  }).format(toUtcInstant(date))
+
+/**
+ * The one instant-to-calendar-date conversion in the library, and it
+ * makes you name the zone.
+ *
+ * Defaulting `timeZone` to the device's own resolved zone is right
+ * for "what is today on this screen"; passing one explicitly is
+ * right for "what is today for this household". Either way the
+ * question is asked out loud, which is the difference between this
+ * and `new Date().toISOString().slice(0, 10)` — a line that appears
+ * in three of the fleet's repos and is wrong for everybody west of
+ * Greenwich after 17:00.
+ */
+export const getLocalPlainDate = (
+  now: Date,
+  timeZone?: string,
+): PlainDate => {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    day: "2-digit",
+    month: "2-digit",
+    timeZone,
+    year: "numeric",
+  }).formatToParts(now)
+
+  const read = (type: string) =>
+    Number(
+      parts.find((part) => part.type === type)?.value ??
+        "0",
+    )
+
+  return {
+    day: read("day"),
+    month: read("month"),
+    year: read("year"),
+  }
+}
+
+/**
+ * Which weekday a calendar starts on, from the locale rather than
+ * from a guess.
+ *
+ * `Intl.Locale.prototype.getWeekInfo` is the platform's own answer
+ * (Monday in most of the world, Sunday in the US and Japan, Saturday
+ * in much of the Middle East) and it is the whole reason this
+ * component does not ship a `isMondayFirst` boolean. It is not in
+ * TypeScript's `lib.es*` yet, so the shape is stated here and the
+ * absence is handled — a runtime without it falls back to Sunday,
+ * which is `Date.prototype.getDay`'s own origin and therefore the
+ * least surprising default.
+ */
+type LocaleWithWeekInfo = {
+  getWeekInfo?: () => { firstDay?: number }
+  weekInfo?: { firstDay?: number }
+}
+
+export const getFirstDayOfWeek = (
+  locale?: string,
+): number => {
+  const resolved = new Intl.Locale(
+    locale ??
+      new Intl.DateTimeFormat().resolvedOptions().locale,
+  ) as Intl.Locale & LocaleWithWeekInfo
+
+  const firstDay =
+    resolved.getWeekInfo?.().firstDay ??
+    resolved.weekInfo?.firstDay
+
+  // `getWeekInfo` numbers Monday 1 through Sunday 7; this file
+  // numbers Sunday 0 through Saturday 6.
+  return firstDay === undefined ? 0 : firstDay % 7
+}
+
+/**
+ * The seven weekday names, rotated so index 0 is the locale's own
+ * first day. A fixed sample week is formatted rather than a
+ * hand-written table, so every locale the browser knows is covered
+ * and nothing here needs translating.
+ */
+export const getWeekdayNames = ({
+  firstDayOfWeek,
+  locale,
+  weekday,
+}: {
+  firstDayOfWeek: number
+  locale?: string
+  weekday: "long" | "narrow" | "short"
+}): string[] => {
+  // 2026-08-16 is a Sunday, so `+ index` walks Sunday to Saturday.
+  const sundayDayNumber = getDayNumber({
+    day: 16,
+    month: 8,
+    year: 2026,
+  })
+
+  return Array.from({ length: 7 }, (_unused, index) =>
+    formatPlainDate(
+      getPlainDateFromDayNumber(
+        sundayDayNumber + ((firstDayOfWeek + index) % 7),
+      ),
+      { locale, weekday },
+    ),
+  )
+}
+
+/** January-first month names, for the parser and the header. */
+export const getMonthNames = ({
+  locale,
+  month,
+}: {
+  locale?: string
+  month: "long" | "short"
+}): string[] =>
+  Array.from({ length: 12 }, (_unused, index) =>
+    formatPlainDate(
+      { day: 1, month: index + 1, year: 2026 },
+      { locale, month },
+    ),
+  )

package/src/MarkdownEditor/MarkdownEditor.mdx

@@ -0,0 +1,189 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MarkdownEditorStories from "./MarkdownEditor.stories";
+
+<Meta of={MarkdownEditorStories} />
+
+# MarkdownEditor
+
+A live hybrid markdown editor whose stored value is markdown and **only** markdown.
+
+Docket asked for this one and its requirement is unusually sharp, because the tracker it
+replaces destroyed data by storing HTML in a field it later read back as text. So the
+constraint is not "prefer markdown" — it is that an HTML tag must not be *able* to reach the
+stored string.
+
+<Canvas of={MarkdownEditorStories.Default} />
+
+## Props
+
+<Controls />
+
+## No HTML can reach the value, by construction
+
+Four properties, and none of them is a rule somebody has to remember:
+
+- the editing surface is a `<textarea>`, which takes **`text/plain`** off the clipboard and
+  nothing else. Copy a styled paragraph out of a browser and the `text/html` flavour is
+  simply never read;
+- every command in `markdownCommands.ts` returns markdown. There is no serialiser and no
+  intermediate document model anywhere in the component;
+- the painted layer emits `{ kind, text }` spans that React renders as **text nodes**. No
+  `innerHTML`, no sanitiser, and nothing to get wrong — a `<script>` in the source is a
+  handful of coloured characters on screen;
+- image insertion escapes its alt text and brackets a dirty URL, so a filename with a `]` in
+  it cannot end the construct early.
+
+`markdownCommands.test.ts` runs every command over a value full of tags and entities and
+asserts each fragment survives **verbatim** — not "contains no `&lt;`", because the fixture
+deliberately contains `&lt;` as literal text and a naive absence check would pass on an
+escaped value and fail on a correct one.
+
+<Canvas of={MarkdownEditorStories.AllVariants} />
+
+## Why a `<textarea>` and not an editor core
+
+Charcuterie is published, so a dependency here is a permanent cost to every consumer.
+Measured on this machine — `esbuild --bundle --minify`, React external, gzip -9:
+
+| Candidate | minified | gzipped |
+| --- | --- | --- |
+| TipTap 3.30 + starter kit + `tiptap-markdown` | 720 KB | **238 KB** |
+| CodeMirror 6 (`basicSetup` + `lang-markdown`) | 609 KB | **206 KB** |
+| CodeMirror 6, hand-assembled minimum | 512 KB | **176 KB** |
+| Lexical 0.49 + markdown/list/link/code nodes | 449 KB | **148 KB** |
+| **This component** | — | **0 KB added** |
+
+The full argument, including what the choice gives up and what would justify reversing it,
+is in
+[`docs/decisions/2026-08-19-the-markdown-editor-is-a-textarea-with-a-painted-layer.md`](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-19-the-markdown-editor-is-a-textarea-with-a-painted-layer.md).
+
+The accessibility half of it is the half that is hard to buy back later. A `<textarea>`
+arrives with caret movement, word-wise selection, `Home`/`End`, IME composition, spellcheck,
+autocorrect, the platform's own undo stack, `role="textbox"` and `aria-multiline="true"` —
+all of it, in every browser, tested by the vendors. A `contenteditable` starts with none of
+those and re-earns each one, and the ones it never fully re-earns are IME and undo.
+
+## The painted layer, and the geometry that constrains it
+
+The surface is a real `<textarea>` with a painted layer behind it in the **same grid cell**.
+The textarea owns the caret, the selection, the undo stack and the IME; the layer owns the
+colour. Its text is transparent and its `caret-color` is not, which is what `caret-color`
+exists for.
+
+That only works while the two layers **lay out identically**, so:
+
+- the tokenizer keeps **every character**. It never trims, never normalises a tab, never
+  drops an unterminated marker. `markdownSpans.test.ts` joins every span back together and
+  asserts it reproduces the source byte for byte;
+- every span style is **metric-neutral**. Bold is faux bold — `text-shadow` at ±0.02em paints
+  the glyph twice, a hair apart, which thickens it and moves nothing. Italic is real, because
+  the surface is monospaced and a monospaced italic keeps the advance width by definition.
+  Headings get weight and colour rather than size. `MarkdownEditor.test.tsx` **measures** each
+  one against plain text and fails if any of them is wider.
+
+The honest limit follows from the same constraint: **markers are dimmed, not hidden.**
+Concealing `**` would change the line's width and there is no way to do it in this medium.
+So "raw syntax on the cursor's line" becomes a contrast change — muted markers everywhere,
+accent markers on the line the caret is on — and true concealment is the staged follow-up,
+which needs a decoration-capable surface (CodeMirror 6) and would arrive as an **optional
+subpath** so consumers that do not use it keep paying nothing.
+
+<Canvas of={MarkdownEditorStories.NoUpload} />
+
+## Uncontrolled, and that is not a shortcut
+
+`defaultValue` in, `onChange` out — the same contract as `Select`, and here it protects
+something specific. A controlled React `<textarea>` round-trips every keystroke through
+render, and any programmatic `value` assignment **wipes the browser's undo stack**: Ctrl+Z
+after a toolbar click then skips the paragraph you typed before it, or does nothing at all.
+
+So the textarea is never handed a `value`. Its text is mirrored into state for *painting*
+only, and every programmatic edit is applied as a range replacement through
+`document.execCommand("insertText")` — deprecated, and still the only API that appends to
+the native undo stack. `getMinimalEdit` is what turns a command's whole-string result back
+into that range, so a bold toggle is **one** undo step over four characters rather than a
+document-sized one.
+
+A consumer that must swap the whole document — Docket opening a different task — remounts
+with a `key`. That is one line, and it is honest about the fact that the old undo history
+belonged to the old document.
+
+## Paste an image at the cursor
+
+```tsx
+<MarkdownEditor
+  label="Description"
+  onUploadImage={async (file) => {
+    const { url } = await uploadToBlobStore(file)
+
+    return { alt: file.name, url }
+  }}
+/>
+```
+
+**The component owns no storage.** It hands you a `File`, waits, and inserts the URL you
+return as `![alt](url)` at the caret. Docket keeps its own blob storage precisely so the URL
+stays stable and theirs.
+
+While the request is in flight the document holds a **markdown placeholder** —
+`![Uploading rack.png](#uploading-1)` — rather than an overlay, because the user keeps typing
+during an upload and the insertion point has to move with what they type. It carries a
+counter so two files of the same name do not resolve into each other's slot, and a failed
+upload leaves a document the user can read and fix rather than a dangling widget.
+
+Omit `onUploadImage` and image paste is simply not offered. A `<textarea>` ignores a pasted
+image on its own, which is the correct fallback rather than a broken one.
+
+## Composition, and the one component that did not fit
+
+The toolbar is this package's `Toolbar`, so the row collapses into a **menu by measurement**
+rather than at a breakpoint — which is what the Narrow View actually needs, since a lane in a
+three-up board is narrow on a 4K display. `Field` wraps it through `SlotProps`, so a label, a
+description and an error wire themselves to the `<textarea>` rather than stopping at this
+component.
+
+`FileDropZone` does **not** wrap it, and that is the interesting one. That component is a
+`<label>` around a file input covering its whole area — correct for "drop a disc image here",
+and wrong for a text surface, where the drop has to land *at a character offset* and the area
+has to keep taking clicks as caret placement. So the editor handles its own drop, and
+`FileDropZone` stays the right answer for the attachment list beside it.
+
+<Canvas of={MarkdownEditorStories.Responsive} />
+
+## Keyboard
+
+| Key | Does |
+| --- | --- |
+| `Ctrl`/`Cmd` + `B` | Bold, and un-bold |
+| `Ctrl`/`Cmd` + `I` | Italic |
+| `Ctrl`/`Cmd` + `E` | Inline code |
+| `Ctrl`/`Cmd` + `K` | Link, caret parked in the destination |
+| `Ctrl`/`Cmd` + `]` / `[` | Indent / outdent the selected lines |
+| `Enter` | Continues a list, a task list or a quote — and **clears** an empty item |
+| `Tab` | Moves focus. Always. |
+
+**`Tab` is never captured**, at any time. Indenting with Tab is the convention in editors
+that own the whole page, and inside a form it is a keyboard trap: WCAG 2.1.2 wants focus to
+be able to leave every component with the standard gesture, and a multi-line field on a task
+form is exactly where somebody tabs onward.
+
+Enter returns *nothing to do* rather than an unchanged state when the caret is not in a list,
+so the keypress falls through to the browser and lands on the native undo stack as an
+ordinary typing step.
+
+<Canvas of={MarkdownEditorStories.AllStates} />
+
+## What this deliberately does not parse
+
+The tokenizer resolves **one line at a time**, carrying exactly one bit of cross-line state:
+whether we are inside a fenced code block. Painting re-runs on every keystroke, so the cost
+has to be linear in the line rather than in the document — and a mis-coloured marker is
+cosmetic while a mis-*placed* one is a broken editor.
+
+So these colour as plain text: setext headings (`Title` over `=====`), indented four-space
+code blocks, reference links (`[a][b]`), autolinks in angle brackets, and emphasis that spans
+a line break. They all still **store** correctly, because the stored value is the textarea's
+and not the tokenizer's.
+
+<Canvas of={MarkdownEditorStories.Interactive} />