@gjermundgaraba-designs/pixel-paper 0.11.0 → 0.13.0

package/src/rows/rows.ts

@@ -14,14 +14,19 @@ export type ViewConfig = Readonly<{
   rows: ReadonlyArray<Html>;
   /** An outline: nested rows indent 26px and hang on a 1px rule guide. */
   isOutline?: boolean;
-  /** Names the list for screen readers. */
+  /** Names the list for screen readers; a treegrid needs it. */
   label?: string;
+  /** A keyboard-driven list, whose cursor the application moves (see Keys in DESIGN.md): a
+   *  `role="treegrid"`, so a screen reader hands it the arrow and letter keys. Give every row
+   *  its `treegrid` place. */
+  isTreegrid?: boolean;
 }>;
 
 /** A list of 34px rows. */
 export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html =>
   h.ul(
     [
+      ...(config.isTreegrid === true ? [h.Role("treegrid")] : []),
       ...(config.label === undefined ? [] : [h.AriaLabel(config.label)]),
       h.Class(config.isOutline === true ? "rows tree" : "rows"),
     ],
@@ -45,6 +50,20 @@ export type RowSelect<Message> = Readonly<{
   label?: string;
 }>;
 
+/** A row's place in a treegrid (`view`'s `isTreegrid`): its line is a `role="row"` and each
+ *  of its parts a `role="gridcell"`, while the list items around them step aside
+ *  (`role="none"`). */
+export type TreegridPlace = Readonly<{
+  /** Its depth, from 1 at the list's roots: `aria-level`. */
+  level: number;
+  /** Its place among its siblings, from 1: `aria-posinset`. */
+  position: number;
+  /** How many siblings it has, itself included: `aria-setsize`. */
+  setSize: number;
+  /** Whether the rows under it show, for a row that folds: `aria-expanded`. */
+  isExpanded?: boolean;
+}>;
+
 /** Configuration for rendering a row with `rowView`. */
 export type RowConfig<Message> = Readonly<{
   /** The row's stable id among its siblings. */
@@ -55,6 +74,10 @@ export type RowConfig<Message> = Readonly<{
   body: ReadonlyArray<Html | string>;
   /** Right-aligned chips, marks, counts, due days. */
   slot?: ReadonlyArray<Html | string>;
+  /** Further attributes for the slot's `span.slot`, such as an id the row's line is described
+   *  by (`aria-describedby`); there is no span, and so nothing to point at, while `slot` is
+   *  empty. Never a class. */
+  slotAttributes?: Attributes<Message>;
   /** Controls that belong to the row's job, before the tools (an approve and reject pair). */
   actions?: ReadonlyArray<Html | string>;
   /** Icon buttons at the row's right end, dimmed until the row is hovered or focused (full
@@ -68,12 +91,45 @@ export type RowConfig<Message> = Readonly<{
   isContext?: boolean;
   /** Makes the row selectable: a box at its left edge. */
   select?: RowSelect<Message>;
+  /** The row's place in a treegrid; every row of a treegrid has one. */
+  treegrid?: TreegridPlace;
   /** Further attributes for the row's line, the `div.row`, not its `li`: a keyboard list's
    *  cursor (`aria-current="true"`, which the stylesheet outlines, and a roving `tabindex`),
-   *  `role="group"` and a name, data attributes, key and focus handlers. Never a class. */
+   *  its name (with `role="group"` outside a treegrid, whose row is already a named `row`), data
+   *  attributes, key and focus handlers. Never a class. */
   attributes?: Attributes<Message>;
 }>;
 
+const cellRole = <Message>(
+  config: RowConfig<Message>,
+  h: HtmlBuilder<Message>,
+): Attributes<Message> => (config.treegrid === undefined ? [] : [h.Role("gridcell")]);
+
+const rowRole = <Message>(
+  place: TreegridPlace | undefined,
+  h: HtmlBuilder<Message>,
+): Attributes<Message> =>
+  place === undefined
+    ? []
+    : [
+        h.Role("row"),
+        h.AriaLevel(place.level),
+        h.AriaPosinset(place.position),
+        h.AriaSetsize(place.setSize),
+        ...(place.isExpanded === undefined ? [] : [h.AriaExpanded(place.isExpanded)]),
+      ];
+
+/** A part the caller gives (a glyph, the actions) in its own cell, in a treegrid. */
+const cellView = <Message>(
+  config: RowConfig<Message>,
+  className: string,
+  content: ReadonlyArray<Html | string>,
+  h: HtmlBuilder<Message>,
+): ReadonlyArray<Html | string> =>
+  config.treegrid === undefined
+    ? content
+    : slotView("span", className, content, h, cellRole(config, h));
+
 /** The row's text, with the words that say a context row is one. */
 const textOf = <Message>(
   config: RowConfig<Message>,
@@ -90,14 +146,21 @@ const lineView = <Message>(
   h: HtmlBuilder<Message>,
 ): Html =>
   h.div(
-    [...(config.attributes ?? []), h.Class(config.isContext === true ? "row context" : "row")],
+    [
+      ...(config.attributes ?? []),
+      ...rowRole(config.treegrid, h),
+      h.Class(config.isContext === true ? "row context" : "row"),
+    ],
     [
       ...box,
-      ...(config.glyph === undefined ? [] : [config.glyph]),
+      ...cellView(config, "cell", config.glyph === undefined ? [] : [config.glyph], h),
       text,
-      ...slotView("span", "slot", config.slot ?? [], h),
-      ...(config.actions ?? []),
-      ...slotView("span", "tools", config.tools ?? [], h),
+      ...slotView("span", "slot", config.slot ?? [], h, [
+        ...(config.slotAttributes ?? []),
+        ...cellRole(config, h),
+      ]),
+      ...cellView(config, "cell actions", config.actions ?? [], h),
+      ...slotView("span", "tools", config.tools ?? [], h, cellRole(config, h)),
     ],
   );
 
@@ -113,19 +176,25 @@ const selectableLineView = <Message>(
       onToggle: select.onToggle,
       toView: (groups) => {
         const boxView = (name: ReadonlyArray<Html>): Html =>
-          h.span([h.Class("row-check")], [h.button(groups.checkbox), ...name]);
+          h.span(
+            [...cellRole(config, h), h.Class("row-check")],
+            [h.button(groups.checkbox), ...name],
+          );
+        const label = h.label([...groups.label, h.Class("grow")], textOf(config, h));
 
         return select.label === undefined
           ? lineView(
               config,
               [boxView([])],
-              h.label([...groups.label, h.Class("grow")], textOf(config, h)),
+              config.treegrid === undefined
+                ? label
+                : h.span([...cellRole(config, h), h.Class("cell grow-cell")], [label]),
               h,
             )
           : lineView(
               config,
               [boxView([h.span([...groups.label, h.Class("sr-only")], [select.label])])],
-              h.div([h.Class("grow")], textOf(config, h)),
+              h.div([...cellRole(config, h), h.Class("grow")], textOf(config, h)),
               h,
             );
       },
@@ -135,18 +204,18 @@ const selectableLineView = <Message>(
 
 /** One 34px row: box, glyph, text, slot, actions, tools, and the rows nested under it. Hover
  *  and focus tint it head. The box of a selectable row is built on `@foldkit/ui`'s Checkbox:
- *  a `role="checkbox"` button (`aria-checked`) whose whole cell is its target. */
-export const rowView = <Message>(config: RowConfig<Message>, h: HtmlBuilder<Message>): Html =>
-  h.keyed("li")(
-    config.key,
-    [],
-    [
-      config.select === undefined
-        ? lineView(config, [], h.div([h.Class("grow")], textOf(config, h)), h)
-        : selectableLineView(config, config.select, h),
-      ...slotView("ul", "rows", config.nested ?? [], h),
-    ],
-  );
+ *  a `role="checkbox"` button (`aria-checked`) whose whole cell is its target. In a treegrid
+ *  the line is the `role="row"` and each part a `role="gridcell"`. */
+export const rowView = <Message>(config: RowConfig<Message>, h: HtmlBuilder<Message>): Html => {
+  const listRole = config.treegrid === undefined ? [] : [h.Role("none")];
+
+  return h.keyed("li")(config.key, listRole, [
+    config.select === undefined
+      ? lineView(config, [], h.div([...cellRole(config, h), h.Class("grow")], textOf(config, h)), h)
+      : selectableLineView(config, config.select, h),
+    ...slotView("ul", "rows", config.nested ?? [], h, listRole),
+  ]);
+};
 
 // GLYPH SLOT
 
@@ -162,13 +231,14 @@ export const glyphView = <Message>(config: GlyphConfig, h: HtmlBuilder<Message>)
 /** Configuration for rendering a fold toggle with `toggleView`. */
 export type ToggleConfig<Message> = Readonly<{
   isExpanded: boolean;
-  /** What folds: `"Fold Notes"` and `"Unfold Notes"` are built from it. */
+  /** What the nested rows hang under: the toggle is named `"Rows under Notes"` whether open
+   *  or not, and `aria-expanded` says which. */
   label: string;
   onToggle: Message;
 }>;
 
 /** The glyph slot as a fold toggle, built on `@foldkit/ui`'s Button: a ring, open or closed,
- *  `aria-expanded`, named for what it does next. */
+ *  `aria-expanded`, named for the rows it shows. */
 export const toggleView = <Message>(config: ToggleConfig<Message>, h: HtmlBuilder<Message>): Html =>
   UiButton.view(
     {
@@ -178,7 +248,7 @@ export const toggleView = <Message>(config: ToggleConfig<Message>, h: HtmlBuilde
           [
             ...groups.button,
             h.AriaExpanded(config.isExpanded),
-            h.AriaLabel(`${config.isExpanded ? "Fold" : "Unfold"} ${config.label}`),
+            h.AriaLabel(`Rows under ${config.label}`),
             h.Class("glyph"),
           ],
           [Glyph.view({ name: config.isExpanded ? "ring" : "ring-closed" }, h)],

package/src/selectField/selectField.ts

@@ -2,6 +2,8 @@ import { Select as UiSelect } from "@foldkit/ui";
 import { Array } from "effect";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
+import { describedByError, errorView } from "../field/field.ts";
+
 // VIEW
 
 /** One choice in a `SelectField`. */
@@ -31,8 +33,10 @@ export type ViewConfig<Message> = Readonly<{
   options: ReadonlyArray<SelectOption | SelectGroup>;
   /** A sans sentence under the control. */
   help?: string;
-  /** Red on the control's 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;
 }>;
@@ -56,27 +60,18 @@ const entryView =
       : optionView(h)(entry);
 
 /** A labelled select with its help line, built on `@foldkit/ui`'s `Select`: the label names
- *  the select, the help line describes it (`aria-describedby`), `isInvalid` sets
- *  `aria-invalid` and `isRequired` sets `aria-required`. The stylesheet draws the box, the
- *  caret and the picker. */
+ *  the select, the help line describes it (`aria-describedby`), an `error` sets
+ *  `aria-invalid` and describes it before the help, and `isRequired` sets `aria-required`.
+ *  The stylesheet draws the box, the caret and the picker. */
 export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
-  const {
-    id,
-    label,
-    value,
-    onChange,
-    options,
-    help,
-    isInvalid = false,
-    isRequired = false,
-  } = config;
+  const { id, label, value, onChange, options, help, error, isRequired = false } = config;
 
   return UiSelect.view(
     {
       id,
       value,
       onChange,
-      isInvalid,
+      isInvalid: error !== undefined,
       hasDescription: help !== undefined,
       toView: (groups) =>
         h.div(
@@ -85,9 +80,14 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
             h.label(groups.label, [label]),
             // NOTE: @foldkit/ui gap: Select has no required option, so the wrapper says it.
             h.select(
-              [...groups.select, ...(isRequired ? [h.AriaRequired(true)] : [])],
+              [
+                ...groups.select,
+                ...describedByError(id, error, help !== undefined, h),
+                ...(isRequired ? [h.AriaRequired(true)] : []),
+              ],
               Array.map(options, entryView(h)),
             ),
+            ...errorView(id, error, h),
             ...(help === undefined
               ? []
               : [h.p([...groups.description, h.Class("field-help")], [help])]),

package/src/sheet/sheet.ts

@@ -16,8 +16,9 @@ export type ViewConfig = Readonly<{
   body: ReadonlyArray<Html | string>;
 }>;
 
-/** An authored page inside a panel, in an `<article>` under its `h1`: the one place the
- *  system slows to reading pace. */
+/** An authored page, an `<article>` under its `h1` on its own sheet of paper, framed as a
+ *  panel is: the one place the system slows to reading pace. It stands in a panel's place,
+ *  never inside one, so its `h1` opens the page instead of following a panel's `h2`. */
 export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html => {
   const { title, byline = [], actions = [], body } = config;
 

package/src/slot/slot.ts

@@ -1,6 +1,8 @@
 import { Array } from "effect";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
+import type { Attributes } from "../attributes/attributes.ts";
+
 /** The elements a slot is wrapped in. */
 type SlotTag = "div" | "span" | "p" | "dd" | "ul";
 
@@ -11,8 +13,9 @@ export const slotView = <Message>(
   slotClass: string,
   slot: ReadonlyArray<Html | string>,
   h: HtmlBuilder<Message>,
+  attributes: Attributes<Message> = [],
 ): ReadonlyArray<Html> =>
   Array.match(slot, {
     onEmpty: () => [],
-    onNonEmpty: (content) => [h[tag]([h.Class(slotClass)], content)],
+    onNonEmpty: (content) => [h[tag]([...attributes, h.Class(slotClass)], content)],
   });

package/src/textareaField/textareaField.ts

@@ -1,5 +1,7 @@
 import { Textarea as UiTextarea } from "@foldkit/ui";
-import type { Html, HtmlBuilder } from "foldkit/html";
+import type { ChildAttribute, Html, HtmlBuilder, TextareaAttribute } from "foldkit/html";
+
+import { describedByError, errorView } from "../field/field.ts";
 
 // VIEW
 
@@ -11,32 +13,60 @@ 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 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 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;
+  /** Code and identifiers: the system monospace. */
+  isMono?: boolean;
   /** The lines it opens at; it grows with its text from there. */
   rows?: number;
+  /** Further attributes for the `<textarea>`, such as a placeholder or spelling off; never a
+   *  class, and never its text, which is `value`. */
+  textareaAttributes?: ReadonlyArray<TextareaAttribute<Message> | ChildAttribute>;
 }>;
 
 /** A labelled textarea with its help line, built on `@foldkit/ui`'s `Textarea`: the label
- *  names the textarea, the help line describes it (`aria-describedby`) and `isInvalid` sets
- *  `aria-invalid`. Boxless like a Field, on a dotted baseline, with an ink corner grip. */
+ *  names the textarea, the help line describes it (`aria-describedby`), an `error` sets
+ *  `aria-invalid` and describes it before the help, and `isRequired` sets `aria-required`.
+ *  Boxless like a Field, on a dotted baseline, with an ink corner grip. */
 export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
-  const { id, label, value, onInput, help, isInvalid = false, rows } = config;
+  const {
+    id,
+    label,
+    value,
+    onInput,
+    help,
+    error,
+    isRequired = false,
+    isMono = false,
+    rows,
+    textareaAttributes = [],
+  } = config;
 
   return UiTextarea.view(
     {
       id,
       value,
       onInput,
-      isInvalid,
+      isInvalid: error !== undefined,
       hasDescription: help !== undefined,
       ...(rows !== undefined && { rows }),
       toView: (groups) =>
         h.div(
-          [h.Class("field")],
+          [h.Class(`field${isMono ? " mono" : ""}`)],
           [
             h.label(groups.label, [label]),
-            h.textarea(groups.textarea),
+            // NOTE: @foldkit/ui gap: Textarea has no required option, so the wrapper says it.
+            h.textarea([
+              ...textareaAttributes,
+              ...groups.textarea,
+              ...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])]),