@gjermundgaraba-designs/pixel-paper 0.11.0 → 0.12.0

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/rows.ts

@@ -55,6 +55,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
@@ -95,7 +99,7 @@ const lineView = <Message>(
       ...box,
       ...(config.glyph === undefined ? [] : [config.glyph]),
       text,
-      ...slotView("span", "slot", config.slot ?? [], h),
+      ...slotView("span", "slot", config.slot ?? [], h, config.slotAttributes),
       ...(config.actions ?? []),
       ...slotView("span", "tools", config.tools ?? [], h),
     ],
@@ -162,13 +166,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 +183,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])]),