@gjermundgaraba-designs/pixel-paper 0.11.0 → 0.12.0

package/src/field/field.ts

@@ -1,8 +1,33 @@
 import { Input as UiInput } from "@foldkit/ui";
-import type { Html, HtmlBuilder } from "foldkit/html";
+import type { Html, HtmlBuilder, TextareaAttribute } from "foldkit/html";
 
 import type { Attributes } from "../attributes/attributes.ts";
 
+// ERROR
+
+const errorId = (id: string): string => `${id}-error`;
+
+/** The red sentence under a field's control that says why it failed, given an error. */
+export const errorView = <Message>(
+  id: string,
+  error: string | undefined,
+  h: HtmlBuilder<Message>,
+): ReadonlyArray<Html> =>
+  error === undefined ? [] : [h.p([h.Id(errorId(id)), h.Class("field-error")], [error])];
+
+/** Points the control at its error, then at its help line when it has one. After the
+ *  `@foldkit/ui` attributes, whose `aria-describedby` names the help line alone; every
+ *  `@foldkit/ui` control names that line `<id>-description`, as Input does. */
+export const describedByError = <Message>(
+  id: string,
+  error: string | undefined,
+  hasHelp: boolean,
+  h: HtmlBuilder<Message>,
+): ReadonlyArray<TextareaAttribute<Message>> =>
+  error === undefined
+    ? []
+    : [h.AriaDescribedBy(hasHelp ? `${errorId(id)} ${UiInput.descriptionId(id)}` : errorId(id))];
+
 // VIEW
 
 /** Configuration for rendering a text field with `view`. */
@@ -13,8 +38,10 @@ export type ViewConfig<Message> = Readonly<{
   onInput: (value: string) => Message;
   /** A sans sentence under the control. */
   help?: string;
-  /** Red on the control's rule and on its label; say why in a Notice above the form. */
-  isInvalid?: boolean;
+  /** Why the value was refused: a red sentence under the control, which the control is
+   *  described by, with red on its rule and its label (`aria-invalid`). Say it again in an
+   *  ErrorSummary above the form. */
+  error?: string | undefined;
   /** The form is not sent without it: screen readers hear "required" (`aria-required`). */
   isRequired?: boolean;
   /** A 2px ink box: the field that is the whole job of its form. A date is always boxed. */
@@ -30,9 +57,9 @@ export type ViewConfig<Message> = Readonly<{
 }>;
 
 /** A labelled text input with its help line, built on `@foldkit/ui`'s `Input`: the label
- *  names the input, the help line describes it (`aria-describedby`), `isInvalid` sets
- *  `aria-invalid` and `isRequired` sets `aria-required`. The input is boxless, a dotted
- *  baseline that turns solid ink on focus. */
+ *  names the input, the help line describes it (`aria-describedby`), an `error` sets
+ *  `aria-invalid` and describes it before the help, and `isRequired` sets `aria-required`.
+ *  The input is boxless, a dotted baseline that turns solid ink on focus. */
 export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
   const {
     id,
@@ -40,7 +67,7 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
     value,
     onInput,
     help,
-    isInvalid = false,
+    error,
     isRequired = false,
     isBoxed = false,
     isMono = false,
@@ -53,7 +80,7 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
       id,
       value,
       onInput,
-      isInvalid,
+      isInvalid: error !== undefined,
       ...(type !== undefined && { type }),
       hasDescription: help !== undefined,
       toView: (groups) =>
@@ -65,8 +92,10 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
             h.input([
               ...inputAttributes,
               ...groups.input,
+              ...describedByError(id, error, help !== undefined, h),
               ...(isRequired ? [h.AriaRequired(true)] : []),
             ]),
+            ...errorView(id, error, h),
             ...(help === undefined
               ? []
               : [h.p([...groups.description, h.Class("field-help")], [help])]),

package/src/fieldset/fieldset.ts

@@ -1,6 +1,8 @@
 import { Fieldset as UiFieldset } from "@foldkit/ui";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
+import { describedByError, errorView } from "../field/field.ts";
+
 // VIEW
 
 /** Configuration for rendering a fieldset with `view`. */
@@ -11,15 +13,20 @@ export type ViewConfig = Readonly<{
   label: string;
   /** A sans sentence under the controls; it describes the group. */
   help?: string;
+  /** Why the choice was refused: a red sentence under the controls, which the group is
+   *  described by, before its help. Mark the control itself invalid too (RadioChoices'
+   *  `isInvalid`), which turns the legend red. Say it again in an ErrorSummary above the
+   *  form. */
+  error?: string | undefined;
   /** The controls: Choices, a Segmented. */
   body: ReadonlyArray<Html | string>;
 }>;
 
 /** A group of controls under one name, built on `@foldkit/ui`'s Fieldset: a `<fieldset>`
- *  named by its `<legend>` and described by its help line (`aria-describedby`). The legend
- *  turns red while a control in it is invalid. */
+ *  named by its `<legend>` and described by its error and its help line
+ *  (`aria-describedby`). The legend turns red while a control in it is invalid. */
 export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html => {
-  const { id, label, help, body } = config;
+  const { id, label, help, error, body } = config;
 
   return UiFieldset.view(
     {
@@ -27,10 +34,15 @@ export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html
       hasDescription: help !== undefined,
       toView: (groups) =>
         h.fieldset(
-          [...groups.fieldset, h.Class("field")],
+          [
+            ...groups.fieldset,
+            ...describedByError(id, error, help !== undefined, h),
+            h.Class("field"),
+          ],
           [
             h.legend([...groups.legend, h.Class("field-label")], [label]),
             ...body,
+            ...errorView(id, error, h),
             ...(help === undefined
               ? []
               : [h.p([...groups.description, h.Class("field-help")], [help])]),

package/src/lineDiff/diff.ts

@@ -1,30 +1,24 @@
-import { diffLines } from "diff";
+import { type StructuredPatchHunk, diffLines, parsePatch } from "diff";
 import { Array, Match, Option, Schema, pipe } from "effect";
 import { defineTaggedUnion } from "foldkit/schema";
 
-// LINES
+// ROWS
 
-/** What a line did between the two sides. */
-export const LineKind = Schema.Literals(["Same", "Added", "Removed"]);
-export type LineKind = typeof LineKind.Type;
-
-/** One line of a diff, numbered on the side or sides it is on. */
-export const DiffLine = Schema.Struct({
-  kind: LineKind,
-  text: Schema.String,
-  maybeOldNumber: Schema.Option(Schema.Number),
-  maybeNewNumber: Schema.Option(Schema.Number),
-});
-export type DiffLine = typeof DiffLine.Type;
-
-/** A row of a folded diff: a line, or a run of two or more unchanged lines folded into a
- *  count, with the run's first line. */
+/** A row of a diff: a line, numbered on the side or sides it is on, or a run of unchanged
+ *  lines folded into a count, known by its first line's old number. */
 export const DiffRow = defineTaggedUnion({
-  Line: { line: DiffLine },
-  Fold: { count: Schema.Number, firstLine: DiffLine },
+  Same: { text: Schema.String, oldNumber: Schema.Number, newNumber: Schema.Number },
+  Added: { text: Schema.String, newNumber: Schema.Number },
+  Removed: { text: Schema.String, oldNumber: Schema.Number },
+  Fold: { count: Schema.Number, firstOldNumber: Schema.Number },
 });
 export type DiffRow = typeof DiffRow.Type;
 
+type SameRow = Extract<DiffRow, Readonly<{ _tag: "Same" }>>;
+
+/** What a line did between the two sides. */
+export type LineKind = "Same" | "Added" | "Removed";
+
 type Numbers = Readonly<{ old: number; new: number }>;
 
 const withFinalNewline = (text: string): string => (text.endsWith("\n") ? text : `${text}\n`);
@@ -37,24 +31,27 @@ const changeKind = (change: Readonly<{ added: boolean; removed: boolean }>): Lin
     Match.orElse(() => "Same"),
   );
 
-const numberLine = (numbers: Numbers, kind: LineKind, text: string): [Numbers, DiffLine] => {
-  const hasOld = kind !== "Added";
-  const hasNew = kind !== "Removed";
-
-  return [
-    { old: hasOld ? numbers.old + 1 : numbers.old, new: hasNew ? numbers.new + 1 : numbers.new },
-    {
-      kind,
-      text,
-      maybeOldNumber: Option.liftPredicate(numbers.old, () => hasOld),
-      maybeNewNumber: Option.liftPredicate(numbers.new, () => hasNew),
-    },
-  ];
-};
+const numberLine = (numbers: Numbers, kind: LineKind, text: string): [Numbers, DiffRow] =>
+  Match.value(kind).pipe(
+    Match.withReturnType<[Numbers, DiffRow]>(),
+    Match.when("Same", () => [
+      { old: numbers.old + 1, new: numbers.new + 1 },
+      DiffRow.Same({ text, oldNumber: numbers.old, newNumber: numbers.new }),
+    ]),
+    Match.when("Added", () => [
+      { old: numbers.old, new: numbers.new + 1 },
+      DiffRow.Added({ text, newNumber: numbers.new }),
+    ]),
+    Match.when("Removed", () => [
+      { old: numbers.old + 1, new: numbers.new },
+      DiffRow.Removed({ text, oldNumber: numbers.old }),
+    ]),
+    Match.exhaustive,
+  );
 
 /** The line diff of two texts (Myers, through jsdiff), each line numbered on its side. A
  *  missing final newline is not a change. */
-export const diffLinesOf = (before: string, after: string): ReadonlyArray<DiffLine> =>
+export const diffRowsOf = (before: string, after: string): ReadonlyArray<DiffRow> =>
   pipe(
     diffLines(withFinalNewline(before), withFinalNewline(after)),
     Array.flatMap((change) =>
@@ -67,23 +64,82 @@ export const diffLinesOf = (before: string, after: string): ReadonlyArray<DiffLi
       Array.mapAccum(lines, { old: 1, new: 1 }, (numbers, { kind, text }) =>
         numberLine(numbers, kind, text),
       ),
-    ([, numbered]) => numbered,
+    ([, rows]) => rows,
+  );
+
+/** Whether a line was added or removed. */
+export const hasChanges = (rows: ReadonlyArray<DiffRow>): boolean =>
+  Array.some(rows, (row) => row._tag === "Added" || row._tag === "Removed");
+
+// PATCH
+
+type PatchState = Readonly<{ rows: ReadonlyArray<DiffRow>; numbers: Numbers }>;
+
+const LINE_KIND_BY_PREFIX: Readonly<Record<string, LineKind>> = {
+  " ": "Same",
+  "+": "Added",
+  "-": "Removed",
+};
+
+// a blank context line that lost its leading space on the way (a trimming editor, a mail) is
+// still a context line
+const kindOf = (line: string): Option.Option<LineKind> =>
+  line === "" ? Option.some("Same") : Option.fromUndefinedOr(LINE_KIND_BY_PREFIX[line.charAt(0)]);
+
+const readHunk = ({ rows, numbers }: PatchState, hunk: StructuredPatchHunk): PatchState => {
+  const gap = hunk.oldStart - numbers.old;
+  const gapRows = gap > 0 ? [DiffRow.Fold({ count: gap, firstOldNumber: numbers.old })] : [];
+
+  return Array.reduce(
+    hunk.lines,
+    { rows: [...rows, ...gapRows], numbers: { old: hunk.oldStart, new: hunk.newStart } },
+    (state: PatchState, line): PatchState =>
+      // "" starts with a "\", a prefix that draws no row
+      Option.match(kindOf(line), {
+        onNone: () => state,
+        onSome: (kind) => {
+          const [nextNumbers, row] = numberLine(state.numbers, kind, line.slice(1));
+          return { rows: [...state.rows, row], numbers: nextNumbers };
+        },
+      }),
+  );
+};
+
+const onlyHunksOf = <File extends Readonly<{ hunks: Array<StructuredPatchHunk> }>>(
+  files: ReadonlyArray<File>,
+): Option.Option<Array.NonEmptyReadonlyArray<StructuredPatchHunk>> =>
+  Array.match(files, {
+    onEmpty: () => Option.none(),
+    onNonEmpty: ([file, ...others]) =>
+      Array.isArrayEmpty(others) && Array.isArrayNonEmpty(file.hunks)
+        ? Option.some(file.hunks)
+        : Option.none(),
+  });
+
+/** The rows of one file's unified diff, numbered from its hunks' headers, with the unchanged
+ *  lines between hunks folded into a count. `None` unless it is one file with a hunk: text that
+ *  is not a diff, a binary change and several files have no lines to show. */
+export const diffRowsOfPatch = (patch: string): Option.Option<ReadonlyArray<DiffRow>> =>
+  pipe(
+    Option.liftThrowable(parsePatch)(patch.replaceAll("\r\n", "\n")),
+    Option.flatMap(onlyHunksOf),
+    Option.map(
+      (hunks) => Array.reduce(hunks, { rows: [], numbers: { old: 1, new: 1 } }, readHunk).rows,
+    ),
   );
 
-/** Whether anything changed. */
-export const hasChanges = (lines: ReadonlyArray<DiffLine>): boolean =>
-  Array.some(lines, ({ kind }) => kind !== "Same");
+// FOLD
 
 type FoldState = Readonly<{
   rows: ReadonlyArray<DiffRow>;
-  folded: ReadonlyArray<DiffLine>;
+  folded: ReadonlyArray<SameRow>;
 }>;
 
 // a run of one stays a line: a row that says "1 unchanged line" takes the same room as the line
-const foldRow = (run: Array.NonEmptyReadonlyArray<DiffLine>): DiffRow =>
+const foldRow = (run: Array.NonEmptyReadonlyArray<SameRow>): DiffRow =>
   run.length === 1
-    ? DiffRow.Line({ line: Array.headNonEmpty(run) })
-    : DiffRow.Fold({ count: run.length, firstLine: Array.headNonEmpty(run) });
+    ? Array.headNonEmpty(run)
+    : DiffRow.Fold({ count: run.length, firstOldNumber: Array.headNonEmpty(run).oldNumber });
 
 const flushFold = ({ rows, folded }: FoldState): ReadonlyArray<DiffRow> =>
   Array.match(folded, {
@@ -94,17 +150,17 @@ const flushFold = ({ rows, folded }: FoldState): ReadonlyArray<DiffRow> =>
 /** The diff's rows: every change with `context` unchanged lines around it, and each longer
  *  run of unchanged lines folded into one row that counts them (a run of one stays a line). */
 export const foldUnchanged = (
-  lines: ReadonlyArray<DiffLine>,
+  rows: ReadonlyArray<DiffRow>,
   context: number,
 ): ReadonlyArray<DiffRow> => {
   const isKept = (index: number): boolean =>
-    hasChanges(lines.slice(Math.max(0, index - context), index + context + 1));
+    hasChanges(rows.slice(Math.max(0, index - context), index + context + 1));
 
   return flushFold(
-    Array.reduce(lines, { rows: [], folded: [] }, (state: FoldState, line, index): FoldState =>
-      isKept(index)
-        ? { rows: [...flushFold(state), DiffRow.Line({ line })], folded: [] }
-        : { rows: state.rows, folded: [...state.folded, line] },
+    Array.reduce(rows, { rows: [], folded: [] }, (state: FoldState, row, index): FoldState =>
+      row._tag === "Same" && !isKept(index)
+        ? { rows: state.rows, folded: [...state.folded, row] }
+        : { rows: [...flushFold(state), row], folded: [] },
     ),
   );
 };

package/src/lineDiff/index.ts

@@ -1,2 +1,2 @@
-export { view } from "./lineDiff.ts";
-export type { ViewConfig } from "./lineDiff.ts";
+export { patchView, view } from "./lineDiff.ts";
+export type { PatchViewConfig, ViewConfig } from "./lineDiff.ts";

package/src/lineDiff/lineDiff.ts

@@ -1,12 +1,12 @@
-import { Array, Option } from "effect";
+import { Array, Option, String } from "effect";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
 import { LOCALE } from "../locale/locale.ts";
 import {
   DiffRow,
-  type DiffLine,
   type LineKind,
-  diffLinesOf,
+  diffRowsOf,
+  diffRowsOfPatch,
   foldUnchanged,
   hasChanges,
 } from "./diff.ts";
@@ -27,58 +27,73 @@ export type ViewConfig = Readonly<{
   context?: number;
 }>;
 
+/** Configuration for rendering a unified diff with `patchView`. */
+export type PatchViewConfig = Readonly<{
+  /** One file's unified diff, as `diff -u` or `git diff -- <path>` writes it. */
+  patch: string;
+  /** Names the two sides for screen readers: `"Version 3 against version 4"`. */
+  label: string;
+}>;
+
 const KIND: Record<LineKind, Readonly<{ className: string; sign: string; said: string }>> = {
   Same: { className: "same", sign: "", said: "unchanged" },
   Added: { className: "add", sign: "+", said: "added" },
   Removed: { className: "del", sign: "−", said: "removed" },
 };
 
-const numberText = (maybeNumber: Option.Option<number>): string =>
-  Option.match(maybeNumber, { onNone: () => "", onSome: (lineNumber) => `${lineNumber}` });
-
-const lineKey = (line: DiffLine): string =>
-  `${numberText(line.maybeOldNumber)}:${numberText(line.maybeNewNumber)}`;
-
-const lineView = <Message>(line: DiffLine, h: HtmlBuilder<Message>): Html => {
-  const { className, sign, said } = KIND[line.kind];
+const lineView = <Message>(
+  kind: LineKind,
+  numbers: Readonly<{ old: string; new: string }>,
+  text: string,
+  h: HtmlBuilder<Message>,
+): Html => {
+  const { className, sign, said } = KIND[kind];
 
   return h.keyed("tr")(
-    lineKey(line),
+    `${numbers.old}:${numbers.new}`,
     [h.Class(className)],
     [
-      h.td([h.Class("ln")], [numberText(line.maybeOldNumber)]),
-      h.td([h.Class("ln")], [numberText(line.maybeNewNumber)]),
+      h.td([h.Class("ln")], [numbers.old]),
+      h.td([h.Class("ln")], [numbers.new]),
       h.td([h.Class("sign"), h.AriaLabel(said)], [sign]),
-      h.td([h.Class("line")], [line.text === "" ? " " : line.text]),
+      h.td([h.Class("line")], [text === "" ? " " : text]),
     ],
   );
 };
 
-const foldView = <Message>(count: number, firstLine: DiffLine, h: HtmlBuilder<Message>): Html =>
+const foldView = <Message>(count: number, firstOldNumber: number, h: HtmlBuilder<Message>): Html =>
   h.keyed("tr")(
-    `fold-${lineKey(firstLine)}`,
+    `fold-${firstOldNumber}`,
     [h.Class("fold")],
-    [h.td([h.Colspan(COLUMN_COUNT)], [`${count.toLocaleString(LOCALE)} unchanged lines`])],
+    [
+      h.td(
+        [h.Colspan(COLUMN_COUNT)],
+        [`${count.toLocaleString(LOCALE)} unchanged ${count === 1 ? "line" : "lines"}`],
+      ),
+    ],
   );
 
 const rowView = <Message>(row: DiffRow, h: HtmlBuilder<Message>): Html =>
   DiffRow.match(row, {
-    Line: ({ line }) => lineView(line, h),
-    Fold: ({ count, firstLine }) => foldView(count, firstLine, h),
+    Same: ({ text, oldNumber, newNumber }) =>
+      lineView("Same", { old: `${oldNumber}`, new: `${newNumber}` }, text, h),
+    Added: ({ text, newNumber }) => lineView("Added", { old: "", new: `${newNumber}` }, text, h),
+    Removed: ({ text, oldNumber }) =>
+      lineView("Removed", { old: `${oldNumber}`, new: "" }, text, h),
+    Fold: ({ count, firstOldNumber }) => foldView(count, firstOldNumber, h),
   });
 
-/** A line diff as a ruled table: the old and new numbers, a sign, the line. Added lines sit on
- *  the head tint behind an ink +; removed lines go muted behind a red −, and each sign is
- *  named for screen readers. Two texts that are the same say so in a sentence. */
-export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html => {
-  const { before, after, label, context = DEFAULT_CONTEXT } = config;
-  const lines = diffLinesOf(before, after);
+const noteView = <Message>(note: string, h: HtmlBuilder<Message>): Html =>
+  h.p([h.Class("note-line")], [note]);
 
-  if (!hasChanges(lines)) {
-    return h.p([h.Class("note-line")], ["No difference: both sides hold the same text."]);
-  }
+const SAME_NOTE = "No difference: both sides hold the same text.";
 
-  return h.div(
+const tableView = <Message>(
+  rows: ReadonlyArray<DiffRow>,
+  label: string,
+  h: HtmlBuilder<Message>,
+): Html =>
+  h.div(
     [h.Class("diff-wrap")],
     [
       h.table(
@@ -86,10 +101,40 @@ export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html
         [
           h.tbody(
             [],
-            Array.map(foldUnchanged(lines, context), (row) => rowView(row, h)),
+            Array.map(rows, (row) => rowView(row, h)),
           ),
         ],
       ),
     ],
   );
+
+/** A line diff as a ruled table: the old and new numbers, a sign, the line. Added lines sit on
+ *  the head tint behind an ink +; removed lines go muted behind a red −, and each sign is
+ *  named for screen readers. Two texts that are the same say so in a sentence. */
+export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html => {
+  const { before, after, label, context = DEFAULT_CONTEXT } = config;
+  const rows = diffRowsOf(before, after);
+
+  return hasChanges(rows)
+    ? tableView(foldUnchanged(rows, context), label, h)
+    : noteView(SAME_NOTE, h);
+};
+
+/** A unified diff the caller already has (from a server, or `git diff -- <path>`) as `view`'s
+ *  table: its hunks' lines, numbered from their headers, and the unchanged lines between hunks
+ *  folded into a counted row. Lines past the last hunk are not in the patch, so nothing counts
+ *  them. An empty patch says there is no difference, as `view` does; anything but one file
+ *  with a hunk (text that is not a diff, a binary change, several files) says it cannot be
+ *  shown as lines. */
+export const patchView = <Message>(config: PatchViewConfig, h: HtmlBuilder<Message>): Html => {
+  const { patch, label } = config;
+
+  if (String.isEmpty(String.trim(patch))) {
+    return noteView(SAME_NOTE, h);
+  } else {
+    return Option.match(diffRowsOfPatch(patch), {
+      onNone: () => noteView("This diff cannot be shown as lines.", h),
+      onSome: (rows) => tableView(rows, label, h),
+    });
+  }
 };

package/src/passwordField/passwordField.ts

@@ -3,6 +3,7 @@ import { Match, Schema } from "effect";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
 import { pressedAttribute } from "../button/button.ts";
+import { describedByError, errorView } from "../field/field.ts";
 import * as IconButton from "../iconButton/iconButton.ts";
 import * as Meter from "../meter/meter.ts";
 
@@ -41,8 +42,10 @@ export type ViewConfig<Message> = Readonly<{
   onToggleShown: Message;
   /** A sans sentence under the box. */
   help?: string;
-  /** Red on the box and on its label; say why in an ErrorSummary above the form. */
-  isInvalid?: boolean;
+  /** Why the value was refused: a red sentence under the control, which the control is
+   *  described by, with red on its box and its label (`aria-invalid`). Say it again in an
+   *  ErrorSummary above the form. */
+  error?: string | undefined;
   /** The form is not sent without it: screen readers hear "required" (`aria-required`). */
   isRequired?: boolean;
   /** For a new password: four short cells and a word under the box (an empty box is "too
@@ -50,13 +53,16 @@ export type ViewConfig<Message> = Readonly<{
   strength?: Strength;
   /** `current-password` to sign in, `new-password` to set one. */
   autocomplete?: "current-password" | "new-password";
+  /** The show toggle's name, "Show password" when not given: give each of two fields in a
+   *  form its own, such as "Show password again". */
+  toggleLabel?: string;
 }>;
 
 /** A boxed password field with a show toggle inside its box, built on `@foldkit/ui`'s Input:
- *  named by its label, described by its help line, `aria-invalid` when it failed and
- *  `aria-required` when the form is not sent without it. The toggle is a button named "Show
- *  password", `aria-pressed` while the password shows. For a new password, its strength is a
- *  meter. */
+ *  named by its label, described by its help line, `aria-invalid` and described by its
+ *  `error` when it failed, and `aria-required` when the form is not sent without it. The
+ *  toggle is a button named `toggleLabel` ("Show password"), `aria-pressed` while the
+ *  password shows. For a new password, its strength is a meter. */
 export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
   const {
     id,
@@ -66,10 +72,11 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
     isShown,
     onToggleShown,
     help,
-    isInvalid = false,
+    error,
     isRequired = false,
     strength,
     autocomplete = "current-password",
+    toggleLabel = "Show password",
   } = config;
 
   return UiInput.view(
@@ -77,7 +84,7 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
       id,
       value,
       onInput,
-      isInvalid,
+      isInvalid: error !== undefined,
       type: isShown ? "text" : "password",
       hasDescription: help !== undefined,
       toView: (groups) =>
@@ -92,12 +99,13 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
                 h.input([
                   ...groups.input,
                   h.Autocomplete(autocomplete),
+                  ...describedByError(id, error, help !== undefined, h),
                   ...(isRequired ? [h.AriaRequired(true)] : []),
                 ]),
                 IconButton.view(
                   {
                     glyph: isShown ? "eye-off" : "eye",
-                    label: "Show password",
+                    label: toggleLabel,
                     isQuiet: true,
                     onClick: onToggleShown,
                     attributes: [pressedAttribute(isShown, h)],
@@ -106,6 +114,7 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
                 ),
               ],
             ),
+            ...errorView(id, error, h),
             ...(strength === undefined
               ? []
               : [

package/src/pixel-paper.css

@@ -924,7 +924,9 @@ a.textbtn {
   min-width: 0;
 }
 
-.panel {
+/* a sheet takes a panel's place on the page, so it prints as one */
+.panel,
+.sheet {
   background: var(--paper);
   border: var(--line) solid var(--ink);
   box-shadow: var(--shadow-panel);
@@ -1354,7 +1356,8 @@ button.glyph {
   margin: -4px;
 }
 
-/* an inline edit in a row shows its focus as its caret and its rule, not a ring */
+/* an inline edit in a row shows its focus as its caret and its rule, thickened below, not a
+   ring */
 .row .grow input.inline-input:focus-visible {
   outline: none;
 }
@@ -1611,6 +1614,17 @@ input.inline-input[aria-invalid="true"] {
   border-bottom-color: var(--red);
 }
 
+/* in a row, which takes its ring, focus doubles the rule to 2px, as a field's baseline does;
+   drawn inside the box, so the row keeps its height, and in the rule's own colour, so a
+   refused edit stays red */
+.row .grow input.inline-input:focus-visible {
+  box-shadow: inset 0 -1px 0 var(--ink);
+}
+
+.row .grow input.inline-input[aria-invalid="true"]:focus-visible {
+  box-shadow: inset 0 -1px 0 var(--red);
+}
+
 /* the flash word: a transient confirmation printed beside the action, then gone */
 .flash-word {
   font-family: var(--font-px);
@@ -1853,12 +1867,18 @@ textarea::-webkit-resizer {
   color: var(--red);
 }
 
-.field .field-help {
+.field .field-help,
+.field .field-error {
   margin-top: 4px;
   font: var(--type-control)/1.45 var(--font-body);
   color: var(--muted);
 }
 
+/* why the field failed, said in red ink under the control and before its help */
+.field .field-error {
+  color: var(--red);
+}
+
 .field-grid {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
@@ -2961,7 +2981,8 @@ dialog.veil:focus {
   justify-items: center;
 }
 
-.empty strong {
+.empty-title {
+  margin: 0;
   font-family: var(--font-px);
   font-size: var(--type-control);
   text-transform: uppercase;
@@ -3971,7 +3992,7 @@ dialog.veil:focus {
   outline-offset: 2px;
 }
 
-/* ---------- the reading sheet: an authored page inside a panel ---------- */
+/* ---------- the reading sheet: an authored page in a panel's place ---------- */
 
 .sheet {
   padding: 28px 32px 36px;