@gjermundgaraba-designs/pixel-paper 0.13.0 → 0.14.0

package/src/emptyState/emptyState.ts

@@ -7,10 +7,12 @@ import type { Html, HtmlBuilder } from "foldkit/html";
 export type ViewConfig = Readonly<{
   /** Pixel caps: what is missing (`"Nothing queued"`). */
   title: string;
-  /** Makes the title a heading at this level, for an empty state that is the page's or the
-   *  section's main content (a gate, a missing page); a `strong` when not given. It looks the
-   *  same either way. */
-  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** The title's element, which looks the same either way. A heading at this level where the
+   *  empty state is the page's or a section's main content: `3` inside a Panel, whose title is
+   *  an `h2`; `1` for a gate or a missing page. `"Strong"` where it is not (a chart with no
+   *  data, a picture of the state). Required, because the two look alike and only the outline
+   *  tells them apart. */
+  headingLevel: 1 | 2 | 3 | 4 | 5 | 6 | "Strong";
   /** One sentence: how it gets filled. */
   body?: ReadonlyArray<Html | string>;
   /** What fills it: a button under the sentence. */
@@ -24,7 +26,7 @@ export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html
   return h.div(
     [h.Class("empty")],
     [
-      headingLevel === undefined
+      headingLevel === "Strong"
         ? h.strong([h.Class("empty-title")], [title])
         : h[`h${headingLevel}`]([h.Class("empty-title")], [title]),
       ...Array.match(body, { onEmpty: () => [], onNonEmpty: (sentence) => [h.p([], sentence)] }),

package/src/errorSummary/errorSummary.ts

@@ -39,7 +39,7 @@ const headline = (count: number): string =>
  * busy) is a failed submit like any other: render the summary from it and focus it.
  *
  * Each link is a fragment link to its field; a Foldkit application's fragment handler moves
- * focus there (see `SkipLink.focusFragment`).
+ * focus there (`SkipLink.ScrollToFragment`).
  */
 export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html => {
   const { id, errors } = config;

package/src/index.ts

@@ -46,6 +46,7 @@ export * as LineChart from "./lineChart/index.ts";
 export * as LineDiff from "./lineDiff/index.ts";
 export * as LinkButton from "./linkButton/index.ts";
 export * as LinkState from "./linkState/index.ts";
+export * as LiveRegion from "./liveRegion/index.ts";
 export * as Loading from "./loading/index.ts";
 export * as Mark from "./mark/index.ts";
 export * as Media from "./media/index.ts";
@@ -64,6 +65,7 @@ export * as Prose from "./prose/index.ts";
 export * as QueryChip from "./queryChip/index.ts";
 export * as RadioChoices from "./radioChoices/index.ts";
 export * as Rail from "./rail/index.ts";
+export * as Remote from "./remote/index.ts";
 export * as Rows from "./rows/index.ts";
 export * as Scheme from "./scheme/index.ts";
 export * as Secret from "./secret/index.ts";
@@ -72,6 +74,7 @@ export * as SelectAll from "./selectAll/index.ts";
 export * as SelectField from "./selectField/index.ts";
 export * as Sheet from "./sheet/index.ts";
 export * as SkipLink from "./skipLink/index.ts";
+export * as Sortable from "./sortable/index.ts";
 export * as Stack from "./stack/index.ts";
 export * as Stage from "./stage/index.ts";
 export * as Stat from "./stat/index.ts";

package/src/lineChart/lineChart.ts

@@ -221,6 +221,6 @@ const chartView = <Message>(
  */
 export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html =>
   Array.match(config.labels, {
-    onEmpty: () => EmptyState.view({ title: "nothing to chart" }, h),
+    onEmpty: () => EmptyState.view({ title: "nothing to chart", headingLevel: "Strong" }, h),
     onNonEmpty: (labels) => chartView(config, labels, h),
   });

package/src/liveRegion/index.ts

@@ -0,0 +1,2 @@
+export { place, view } from "./liveRegion.ts";
+export type { DialogEntry, Placement, ViewConfig } from "./liveRegion.ts";

package/src/liveRegion/liveRegion.ts

@@ -0,0 +1,75 @@
+import { Array, Option, pipe } from "effect";
+import type { Html, HtmlBuilder } from "foldkit/html";
+
+import * as Announcer from "../announcer/announcer.ts";
+
+// PLACE
+
+/** A dialog that can host the page's live parts: its name in the application, and whether it
+ *  is open now. */
+export type DialogEntry<Host extends string> = readonly [host: Host, isOpen: boolean];
+
+/** Where the page's live parts go on this render. */
+export type Placement<Host extends string> = Readonly<{
+  /** The `toLiveRegionView` to give the dialog `host`: the parts while it is the topmost open
+   *  dialog, `undefined` while it is not. */
+  toDialogView: (host: Host) => (() => Html) | undefined;
+  /** The parts for the end of the body while no dialog is open, nothing while one is. */
+  toPageView: () => ReadonlyArray<Html>;
+}>;
+
+/**
+ * Places the page's live parts by the hosting rule: an open Dialog makes the page outside it
+ * inert and hidden from screen readers, so they render inside the topmost open dialog, and at
+ * the end of the body while none is open, exactly once either way. Neither renders them
+ * until called, so a Submodel among the parts (the toast stack) is built once. `dialogs` lists every dialog
+ * that can host them from the bottom of the stack to the top: one that opens from another
+ * (a confirm from a form) comes after it, so of the open ones the last is the topmost. Call it
+ * on every render, from the application's Model, so the parts move as dialogs open and close.
+ *
+ * ```ts
+ * const placement = LiveRegion.place([
+ *   ["Rename", Dialog.isOpen(model.rename)],
+ *   ["Delete", ConfirmDialog.isOpen(model.deleteConfirm)],
+ * ], () => LiveRegion.view({ toasts: toastsView(model, h) }, h));
+ * // the rename dialog's view inputs: toLiveRegionView: placement.toDialogView("Rename")
+ * // the body: [...content, ...placement.toPageView()]
+ * ```
+ */
+export const place = <Host extends string>(
+  dialogs: ReadonlyArray<DialogEntry<Host>>,
+  toView: () => Html,
+): Placement<Host> => {
+  const maybeTopmost = pipe(
+    Array.findLast(dialogs, ([, isOpen]) => isOpen),
+    Option.map(([host]) => host),
+  );
+
+  return {
+    toDialogView: (host) =>
+      Option.exists(maybeTopmost, (topmost) => topmost === host) ? toView : undefined,
+    toPageView: () => (Option.isNone(maybeTopmost) ? [toView()] : []),
+  };
+};
+
+// VIEW
+
+/** Configuration for rendering the page's live parts with `view`. */
+export type ViewConfig = Readonly<{
+  /** The page's Toast stack (its `h.submodel`), when it has one. */
+  toasts?: Html;
+  /** The Banner in force, when one is: it stays in reach while a dialog is open. */
+  banner?: Html;
+}>;
+
+/** The page's live parts together, for `place`: the Announcer's region, then the toast stack
+ *  and the banner the application gives. */
+export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html =>
+  h.div(
+    [],
+    [
+      Announcer.view(h),
+      ...(config.toasts === undefined ? [] : [config.toasts]),
+      ...(config.banner === undefined ? [] : [config.banner]),
+    ],
+  );

package/src/loading/loading.ts

@@ -1,25 +1,31 @@
 import type { Html, HtmlBuilder } from "foldkit/html";
 
+import type { Attributes } from "../attributes/attributes.ts";
+
 // VIEW
 
 /** Configuration for rendering a loading line with `view`. */
-export type ViewConfig = Readonly<{
+export type ViewConfig<Message> = Readonly<{
   /** Whether the content is on its way. Done, the line empties and leaves the flow, so it
    *  takes no room and no gap, but stays in place, so the next wait is heard. */
   isLoading: boolean;
   /** What is on its way, in pixel caps (`"loading the items"`). `"loading"` by default. */
   label?: string;
+  /** Attributes for the line, such as the id and `tabindex="-1"` that make it a place to
+   *  send focus. */
+  attributes?: Attributes<Message>;
 }>;
 
 /** What a panel says while its content is on the way, centred where the content will be, with
  *  the working cursor. A polite status that stays in place with its words swapped, as a live
  *  region must be for a screen reader to hear it: render it before the content, from before
- *  the wait starts, and set `isLoading`. */
-export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html => {
-  const { isLoading, label = "loading" } = config;
+ *  the wait starts, and set `isLoading`. It is not the page's live region (the Announcer's,
+ *  marked `data-pixel-paper-announcer`), so a test that counts live regions counts that. */
+export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
+  const { isLoading, label = "loading", attributes = [] } = config;
 
   return h.div(
-    [h.Role("status"), h.Class(isLoading ? "loading" : "loading-idle")],
+    [...attributes, h.Role("status"), h.Class(isLoading ? "loading" : "loading-idle")],
     isLoading ? [label, h.span([h.Class("cursor"), h.AriaHidden(true)])] : [],
   );
 };

package/src/meter/meter.ts

@@ -76,6 +76,9 @@ export type MeterConfig = Readonly<{
   /** Replaces the printed numbers and what screen readers hear:
    *  `"41,200 of 50,000 requests"`. */
   valueText?: string;
+  /** Prints the numbers line (the default). Leave it out where it would repeat the
+   *  percentage (`valueText: "62% used"`); screen readers still hear `valueText`. */
+  hasNumbers?: boolean;
   /** In a red chip once the value reaches `max`. The percentage by default. */
   full?: string;
   /** The last reading failed: the cells print muted, the numbers are the last known, and
@@ -117,7 +120,16 @@ const percentView = <Message>(
 };
 
 const meterView = <Message>(config: MeterConfig, h: HtmlBuilder<Message>): Html => {
-  const { id, label, value, max, detail = [], foot = [], isStale = false } = config;
+  const {
+    id,
+    label,
+    value,
+    max,
+    detail = [],
+    foot = [],
+    isStale = false,
+    hasNumbers = true,
+  } = config;
   const share = max > 0 ? Math.min(1, Math.max(0, value / max)) : 0;
   const isFull = value >= max;
   const numbers = config.valueText ?? numbersText(value, max, config.unit);
@@ -152,7 +164,7 @@ const meterView = <Message>(config: MeterConfig, h: HtmlBuilder<Message>): Html
                   cellRowView(METER_CELLS, scaled(share, METER_CELLS, isFull), h),
                 ),
                 percentView(config, scaled(share, PERCENT, isFull), isFull, h),
-                h.span([h.Class("meter-num tnum")], [numbers]),
+                ...(hasNumbers ? [h.span([h.Class("meter-num tnum")], [numbers])] : []),
               ],
             ),
             ...slotView("div", "meter-foot", foot, h),
@@ -177,6 +189,8 @@ export type ListViewConfig = Readonly<{
  */
 export const listView = <Message>(config: ListViewConfig, h: HtmlBuilder<Message>): Html =>
   h.ul(
-    [h.Class("meters")],
+    // NOTE: Safari takes list semantics from a list printed without markers, so the list
+    // says it is one
+    [h.Role("list"), h.Class("meters")],
     Array.map(config.meters, (meter) => meterView(meter, h)),
   );

package/src/pixel-paper.css

@@ -32,8 +32,7 @@ body {
   line-height: 1.45;
   color: var(--ink);
   caret-color: var(--ink);
-  background-color: var(--ground);
-  background-image: var(--dither);
+  background: var(--dither);
 }
 
 fieldset {
@@ -380,16 +379,20 @@ button.tag > span {
 }
 
 /* the right-hand tools wrap as one group, never one control per line */
+/* a bar of tools wider than the window wraps onto lines of its own, at the right */
 .topbar-tools {
   display: flex;
+  flex-wrap: wrap;
+  justify-content: flex-end;
   align-items: center;
-  gap: 16px;
+  gap: 8px 16px;
+  min-width: 0;
   margin-left: auto;
 }
 
 @media (max-width: 600px) {
   .topbar-tools {
-    gap: 12px;
+    gap: 8px 12px;
   }
 
   .topbar-tools .btn {
@@ -515,7 +518,7 @@ a.textbtn {
 
   /* the phone bar: wordmark and tools on one line, the page nav as a full-width strip
      under them. Where the two do not fit side by side the tools wrap under the wordmark,
-     which never clips. Sign out and the connection word move to the palette; offline stays */
+     which never clips. Every tool stays: a session action may have nowhere else to live */
   .topbar {
     gap: 8px 12px;
     padding: 8px 12px;
@@ -532,11 +535,6 @@ a.textbtn {
     text-align: center;
   }
 
-  .topbar .topbar-tools .textbtn,
-  .topbar .link-state:not(.offline, .reconnecting) {
-    display: none;
-  }
-
   .deck {
     padding: 20px 12px 64px;
   }
@@ -2634,8 +2632,7 @@ dialog.veil:focus {
 .veil-backdrop {
   position: fixed;
   inset: 0;
-  background-color: var(--veil);
-  background-image: var(--veil-grain);
+  background: var(--veil-grain), var(--veil);
   animation: veilIn var(--motion-veil) steps(3, end);
 }
 
@@ -3329,6 +3326,143 @@ dialog.veil:focus {
   flex: 1;
 }
 
+/* ---------- sortable: items the reader puts in order, as rows or tiles ---------- */
+
+.sortable-items {
+  list-style: none;
+}
+
+/* a row: the grip, then the item, between 1px rules, edge to edge in a flush panel */
+.sortable-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  min-width: 0;
+  padding: 8px var(--pad) 8px 10px;
+  position: relative;
+  background: var(--paper);
+  border-bottom: var(--hair) solid var(--rule);
+}
+
+.sortable-items > .sortable-item:last-child {
+  border-bottom: 0;
+}
+
+.sortable-body {
+  flex: 1;
+  min-width: 0;
+}
+
+.sortable-item.movable {
+  cursor: grab;
+}
+
+.sortable-item [data-sortable-grip] {
+  flex: none;
+}
+
+.sortable-item.movable [data-sortable-grip] {
+  cursor: grab;
+  /* the grip is where a finger drags; the rest of the item scrolls the page */
+  touch-action: none;
+}
+
+.sortable-item.movable:hover {
+  background: var(--head);
+}
+
+.sortable-item.drag-dim {
+  opacity: 0.4;
+}
+
+/* where a pointer would drop the held item: a 2px dashed ink line beside the item it lands
+   next to, drawn over the layout so nothing moves under the pointer */
+.sortable-item:is(.drop-before, .drop-after)::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  border-top: var(--line) dashed var(--ink);
+  pointer-events: none;
+}
+
+.sortable-item.drop-before::before {
+  top: -1px;
+}
+
+.sortable-item.drop-after::before {
+  bottom: -1px;
+}
+
+.sortable.grid .sortable-item:is(.drop-before, .drop-after)::before {
+  top: -2px;
+  bottom: -2px;
+  left: auto;
+  right: auto;
+  border-top: 0;
+  border-left: var(--line) dashed var(--ink);
+}
+
+.sortable.grid .sortable-item.drop-before::before {
+  left: -9px;
+}
+
+.sortable.grid .sortable-item.drop-after::before {
+  right: -9px;
+}
+
+/* the held copy, following the pointer or where the keyboard would drop it: lifted onto the
+   card shadow and tinted, as a board's is; the held item keeps its own print */
+.sortable-item.lifted {
+  border: var(--line) solid var(--ink);
+  background: var(--head);
+  box-shadow: var(--shadow-card);
+  cursor: grabbing;
+}
+
+.sortable-slot {
+  list-style: none;
+  padding: 6px;
+}
+
+.sortable-lift {
+  width: var(--lift-width, 320px);
+  translate: var(--lift-x, 0) var(--lift-y, 0);
+}
+
+/* tiles: paper slips on the 3px print shadow that wrap, 180px and up */
+.sortable.grid .sortable-items {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(180px, 1fr));
+  gap: 12px;
+  padding: 12px;
+}
+
+.sortable.grid .sortable-item {
+  align-items: flex-start;
+  height: 100%;
+  padding: 9px 11px 9px 6px;
+  border: var(--line) solid var(--ink);
+  box-shadow: var(--shadow-button);
+}
+
+.sortable.grid .sortable-item.lifted {
+  box-shadow: var(--shadow-card);
+}
+
+.sortable.grid .sortable-slot {
+  padding: 0;
+}
+
+/* while a pointer carries an item, the page grabs and selects nothing */
+:root[data-pixel-paper-dragging] {
+  user-select: none;
+}
+
+:root[data-pixel-paper-dragging] * {
+  cursor: grabbing !important;
+}
+
 /* ---------- cells: a reading printed as ink squares in a box ---------- */
 
 .cells {
@@ -3355,15 +3489,19 @@ dialog.veil:focus {
   height: 8px;
 }
 
+/* meters in a list step down by their column instead (below) */
 @media (max-width: 600px) {
-  .cells:not(.short) .cell {
+  .cells:not(.short, .meters *) .cell {
     width: 8px;
   }
 }
 
 /* ---------- meters: a named reading, its cells, the numbers and a foot line ---------- */
 
+/* the list is the container its rows measure: they stack and their cells narrow by the
+   column they are placed in, not by the window */
 .meters {
+  container: meters / inline-size;
   list-style: none;
 }
 
@@ -3393,7 +3531,7 @@ dialog.veil:focus {
   align-items: center;
 }
 
-@media (max-width: 700px) {
+@container meters (width < 560px) {
   .meter-row {
     grid-template-columns: minmax(0, 1fr);
   }
@@ -3401,12 +3539,38 @@ dialog.veil:focus {
   .meter-head {
     grid-row: auto;
     flex-direction: row;
+    flex-wrap: wrap;
     align-items: baseline;
-    gap: 12px;
+    gap: 2px 12px;
+  }
+
+  .meter-num {
+    width: 100%;
+  }
+}
+
+/* twenty cells take 246px at 10px each; in a narrower column they step down whole pixels,
+   never to a fraction, so a meter fits a column of 160px and up */
+@container meters (width < 280px) {
+  .meters .cells .cell {
+    width: 8px;
+  }
+}
+
+@container meters (width < 240px) {
+  .meters .cells .cell {
+    width: 6px;
+  }
+}
+
+@container meters (width < 200px) {
+  .meters .cells .cell {
+    width: 4px;
   }
 }
 
 .meter-name {
+  overflow-wrap: anywhere;
   font-family: var(--font-px);
   font-size: var(--type-name);
   text-transform: uppercase;
@@ -3462,12 +3626,6 @@ dialog.veil:focus {
   color: var(--red);
 }
 
-@media (max-width: 600px) {
-  .meter-num {
-    width: 100%;
-  }
-}
-
 /* a history list of checks: when, what was checked, what it read */
 .history-list.checks {
   border-top: 0;
@@ -4760,16 +4918,14 @@ dialog.veil:focus {
     height: 100dvh;
     max-height: none;
     padding: 12px 16px var(--gap) 12px;
-    background-color: var(--ground);
-    background-image: var(--dither);
+    background: var(--dither);
     border-right: var(--line) solid var(--ink);
     box-shadow: var(--shadow-card);
     animation: railIn var(--motion-card) steps(3, end);
   }
 
   .rail[popover]::backdrop {
-    background-color: var(--veil);
-    background-image: var(--veil-grain);
+    background: var(--veil-grain), var(--veil);
   }
 
   .rail-head {
@@ -4840,8 +4996,7 @@ dialog.veil:focus {
   display: grid;
   place-items: center;
   padding: 24px;
-  background-color: var(--veil);
-  background-image: var(--veil-grain);
+  background: var(--veil-grain), var(--veil);
 }
 
 .stage-paused > .notice {

package/src/remote/index.ts

@@ -0,0 +1,2 @@
+export { view } from "./remote.ts";
+export type { ViewConfig } from "./remote.ts";

package/src/remote/remote.ts

@@ -0,0 +1,76 @@
+import { AsyncData } from "foldkit";
+import type { Html, HtmlBuilder } from "foldkit/html";
+
+import * as Button from "../button/button.ts";
+import * as Loading from "../loading/loading.ts";
+import * as Notice from "../notice/notice.ts";
+
+// VIEW
+
+/** Configuration for rendering data that loads with `view`. */
+export type ViewConfig<Data, Error, Message> = Readonly<{
+  /** The loading line's id, unique in the document. Retry takes its button away with the
+   *  notice, so return `Focus.Focus({ id })` with the retry: focus lands on the line, which
+   *  says a first load and stays quiet over a refresh. */
+  id: string;
+  data: AsyncData.AsyncData<Data, Error>;
+  /** What loads, as a noun in the words around it: `"usage"` reads "loading usage", "Usage
+   *  not loaded" and "Usage not refreshed". */
+  label: string;
+  /** Why a load failed, in a sentence, under the notice's title. */
+  toErrorText: (error: Error) => string;
+  /** Loads it again: the notice's retry button, on a failure and on stale data alike. */
+  onRetry: Message;
+  /** The data, loaded or the last loaded (an EmptyState for none is the caller's). */
+  toDataView: (data: Data) => ReadonlyArray<Html>;
+}>;
+
+const capitalised = (label: string): string => `${label.charAt(0).toUpperCase()}${label.slice(1)}`;
+
+/**
+ * Data that loads, in each of Foldkit's `AsyncData` states, with the retry built in: a Loading
+ * line while it first loads (in place in every state, so its status is heard), an error
+ * Notice with retry when it failed with nothing to show, a warn Notice with retry above the
+ * last data when a refresh failed (stale), and the data itself once loaded or while it
+ * refreshes, quietly, so a page that polls is not heard each time. Spread it where the
+ * content goes.
+ */
+export const view = <Data, Error, Message>(
+  config: ViewConfig<Data, Error, Message>,
+  h: HtmlBuilder<Message>,
+): ReadonlyArray<Html> => {
+  const { id, data, label, toErrorText, onRetry, toDataView } = config;
+
+  const noticeView = (tone: "Error" | "Warn", title: string, error: Error): Html =>
+    Notice.view(
+      {
+        tone,
+        title,
+        body: [toErrorText(error)],
+        actions: [Button.view({ label: "retry", isSmall: true, onClick: onRetry }, h)],
+      },
+      h,
+    );
+
+  return [
+    Loading.view(
+      {
+        isLoading: AsyncData.isLoading(data),
+        label: `loading ${label}`,
+        attributes: [h.Id(id), h.Tabindex(-1)],
+      },
+      h,
+    ),
+    ...AsyncData.match(data, {
+      onIdle: () => [],
+      onLoading: () => [],
+      onFailure: (error) => [noticeView("Error", `${capitalised(label)} not loaded`, error)],
+      onStale: ({ error, data: lastData }) => [
+        noticeView("Warn", `${capitalised(label)} not refreshed`, error),
+        ...toDataView(lastData),
+      ],
+      onRefreshing: toDataView,
+      onSuccess: toDataView,
+    }),
+  ];
+};

package/src/skipLink/index.ts

@@ -1 +1 @@
-export { focusFragment, view } from "./skipLink.ts";
+export { ScrollToFragment, view } from "./skipLink.ts";