@gjermundgaraba-designs/pixel-paper 0.11.0 → 0.13.0

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;
 }
@@ -1398,6 +1401,20 @@ button.glyph {
   opacity: 1;
 }
 
+/* a treegrid's own cells around the parts the caller gives (the glyph, the actions): they hold
+   their parts as the row would, so a row lays out the same in a treegrid or out of one */
+.row > .cell {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  flex: none;
+}
+
+.row > .grow-cell {
+  flex: 1;
+  min-width: 0;
+}
+
 .row .slot {
   min-width: 58px;
   flex: none;
@@ -1526,7 +1543,7 @@ button.glyph {
   inset: 0;
 }
 
-.row > label.grow {
+.row label.grow {
   cursor: pointer;
 }
 
@@ -1611,6 +1628,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 +1881,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 +2995,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 +4006,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;

package/src/places/places.ts

@@ -7,8 +7,11 @@ import { slotView } from "../slot/slot.ts";
 
 // VIEW
 
-/** One place in Places: a button that shows it. */
-export type Place<Message> = Readonly<{
+/** One place in Places: a link to its address (`href`), or a button that shows it in the page
+ *  (`onSelect`). */
+export type Place<Message> = PlaceContent & PlaceTarget<Message>;
+
+type PlaceContent = Readonly<{
   /** Stable and unique among the places: the row's key, so two places that share a name stay
    *  apart. */
   id: string;
@@ -20,10 +23,20 @@ export type Place<Message> = Readonly<{
   count?: number;
   /** A quiet IconButton after it that acts on the place itself (remove a saved filter). */
   tools?: ReadonlyArray<Html>;
-  /** Shows the place. */
-  onSelect: Message;
 }>;
 
+type PlaceTarget<Message> =
+  | Readonly<{
+      /** The place's address: the line is a link, so it opens in a new tab and reads as one. */
+      href: string;
+      onSelect?: never;
+    }>
+  | Readonly<{
+      /** Shows the place without leaving the page: the line is a button. */
+      onSelect: Message;
+      href?: never;
+    }>;
+
 /** Configuration for rendering places with `view`. */
 export type ViewConfig<Message> = Readonly<{
   /** Names the navigation for screen readers ("Areas"). */
@@ -31,39 +44,39 @@ export type ViewConfig<Message> = Readonly<{
   places: ReadonlyArray<Place<Message>>;
 }>;
 
+const lineView = <Message>(place: Place<Message>, h: HtmlBuilder<Message>): Html => {
+  const { label, isCurrent = false, count } = place;
+  const current = isCurrent ? [h.AriaCurrent("page")] : [];
+  const content = [
+    h.span([h.Class("place-name")], [label]),
+    ...(count === undefined
+      ? []
+      : [" ", h.span([h.Class("place-count")], [count.toLocaleString(LOCALE)])]),
+  ];
+
+  return place.href === undefined
+    ? UiButton.view(
+        {
+          onClick: place.onSelect,
+          toView: (groups) => h.button([...groups.button, ...current], content),
+        },
+        h,
+      )
+    : h.a([h.Href(place.href), ...current], content);
+};
+
 const placeView =
   <Message>(h: HtmlBuilder<Message>) =>
-  (place: Place<Message>): Html => {
-    const { label, isCurrent = false, count, tools = [], onSelect } = place;
-
-    return h.keyed("li")(
+  (place: Place<Message>): Html =>
+    h.keyed("li")(
       place.id,
       [],
-      [
-        UiButton.view(
-          {
-            onClick: onSelect,
-            toView: (groups) =>
-              h.button(
-                [...groups.button, ...(isCurrent ? [h.AriaCurrent("page")] : [])],
-                [
-                  h.span([h.Class("place-name")], [label]),
-                  ...(count === undefined
-                    ? []
-                    : [" ", h.span([h.Class("place-count")], [count.toLocaleString(LOCALE)])]),
-                ],
-              ),
-          },
-          h,
-        ),
-        ...slotView("span", "place-tools", tools, h),
-      ],
+      [lineView(place, h), ...slotView("span", "place-tools", place.tools ?? [], h)],
     );
-  };
 
 /** A column of places to go (areas, collections, saved filters), flush in a rail panel: a
- *  navigation landmark named by its label, one line each a button built on `@foldkit/ui`'s
- *  Button, the one you are in `aria-current="page"` and printed inverted. */
+ *  navigation landmark named by its label, one line each a link to the place or a button built
+ *  on `@foldkit/ui`'s Button, the one you are in `aria-current="page"` and printed inverted. */
 export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
   const { label, places } = config;
 

package/src/radioChoices/radioChoices.ts

@@ -83,8 +83,8 @@ export type ViewInputs = Readonly<{
   options: ReadonlyArray<RadioOption>;
   /** The parent's selection. */
   selectedValue: Option.Option<string>;
-  /** The group is `aria-invalid` and its marks and names turn red; say why in an
-   *  ErrorSummary above the form. */
+  /** The group is `aria-invalid` and its marks and names turn red; say why in its
+   *  Fieldset's `error` and in an ErrorSummary above the form. */
   isInvalid?: boolean;
 }>;
 

package/src/rail/rail.ts

@@ -234,8 +234,8 @@ export type ViewInputs = Readonly<{
 
 /**
  * A column of panels beside the deck, fixed under the top bar and scrolling itself:
- * `div.railed > aside.rail[popover="auto"][aria-label]` and the deck. One element serves both
- * layouts, so nothing in it renders twice or loses its state. At 900px and under it leaves the
+ * `div.railed >` the deck, then `aside.rail[popover="auto"][aria-label]`. One element serves
+ * both layouts, so nothing in it renders twice or loses its state. At 900px and under it leaves the
  * page, and `span.rail-open > button.btn.small` at the top of the deck opens the same element as a
  * drawer over a veil, its head (the name and a close glyph) showing. Opening focuses its first
  * control; Escape, a press on the veil, the close glyph, focus leaving or the window growing
@@ -268,9 +268,12 @@ export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h
     ],
   );
 
+  // NOTE: the deck comes first so the page's main content, and its h1, precede the rail's
+  // panels in reading order; the stylesheet places the rail, fixed, at the left.
   return h.div(
     [h.Class("railed")],
     [
+      toDeckView(openButton),
       h.aside(
         [
           h.Id(model.id),
@@ -293,7 +296,6 @@ export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h
           ...toAsideView(),
         ],
       ),
-      toDeckView(openButton),
     ],
   );
 });

package/src/rows/index.ts

@@ -5,5 +5,6 @@ export type {
   RowSelect,
   TitleConfig,
   ToggleConfig,
+  TreegridPlace,
   ViewConfig,
 } from "./rows.ts";