@gjermundgaraba-designs/pixel-paper 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba-designs/pixel-paper",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/pixel-paper.css

@@ -5630,6 +5630,54 @@ dialog.veil:focus {
   opacity: var(--fade-dragged);
 }
 
+/* under tabs, the reel is its tab list over the scroller, which takes the height left. The
+   list sits a gutter in from the reel's edges, as the windows do */
+.reel.tabbed {
+  display: flex;
+  flex-direction: column;
+}
+
+.reel.tabbed > .reel-view {
+  flex: 1 1 0;
+  height: auto;
+  min-height: 0;
+}
+
+.reel-tabs {
+  flex: none;
+  max-width: calc(100% - 2 * var(--reel-gutter));
+  margin: var(--reel-gutter) var(--reel-gutter) 0;
+}
+
+/* a tab holds a kind glyph before its words, and gives up width before the list overflows:
+   its words end in an ellipsis */
+.reel-tabs button {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.reel-tab-words {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* the one slot under tabs: the view less a gutter at every edge, every pane pinned to it */
+.reel-stage {
+  flex: 1 1 0;
+  height: calc(100cqh - 2 * var(--reel-gutter));
+  min-height: 0;
+  margin-inline: var(--reel-gutter);
+}
+
+/* a pane behind the selected tab keeps its place and its size, so what sizes itself by its
+   box (a terminal) is not resized as the tabs change; it is only not drawn */
+.reel-pane.behind {
+  visibility: hidden;
+}
+
 /* only the grips lift: a pane's text selects and its terminal takes the pointer */
 [data-reel-grip] {
   cursor: grab;

package/src/reel/index.ts

@@ -2,7 +2,9 @@ export { Layout, OutMessage, Pane, apply } from "./layout.ts";
 export {
   Action,
   AnnounceReel,
+  Arrangement,
   FocusPane,
+  FocusTab,
   Message,
   Model,
   RestoreFocus,

package/src/reel/reel.ts

@@ -86,6 +86,7 @@ const COPY = {
   widthLabel: "Width of column {column}",
   heightLabel: "Height of {pane}",
   focused: "{pane}, {where}.",
+  focusedTab: "{pane}, tab {tab} of {tabs}.",
   moved: "{subject} moved to {where}.",
   widened: "Column {column} takes {width}.",
   pickedUp: "Picked up {subject}.",
@@ -143,6 +144,12 @@ export const Model = Schema.Struct({
 });
 export type Model = typeof Model.Type;
 
+/** How a reel shows its panes: side by side in their columns (`Strip`), or one at a time at
+ *  the reel's full size under a tab per pane (`Tabs`). The application holds it and passes it
+ *  in; the layout is the same in both. */
+export const Arrangement = Schema.Literals(["Strip", "Tabs"]);
+export type Arrangement = typeof Arrangement.Type;
+
 // MESSAGE
 
 const PointerAt = Schema.Struct({
@@ -169,6 +176,8 @@ export const Message = defineMessageUnion({
   LeftGrip: {},
   PressedEscape: {},
   FocusedPane: { paneId: Schema.String },
+  PressedTab: { paneId: Schema.String },
+  SteppedTab: { paneId: Schema.String },
   PressedSplitter: {
     splitter: Splitter,
     pointerId: Schema.Number,
@@ -181,6 +190,7 @@ export const Message = defineMessageUnion({
   PressedSplitterKey: { splitter: Splitter, share: Schema.Number },
   CompletedAnnounceReel: {},
   CompletedFocusPane: {},
+  CompletedFocusTab: {},
   CompletedRestoreFocus: {},
   CompletedScrollIntoView: {},
   CompletedSizeLiftedPane: {},
@@ -238,6 +248,8 @@ const paneHook = (model: Model, paneId: string): string => `${model.id}/pane/${p
 
 const columnHook = (model: Model, columnId: string): string => `${model.id}/column/${columnId}`;
 
+const tabHook = (model: Model, paneId: string): string => `${model.id}/tab/${paneId}`;
+
 const scrollerOf = (reelHook: string): Option.Option<HTMLElement> =>
   Option.fromNullishOr(
     document.querySelector<HTMLElement>(`[data-reel="${CSS.escape(reelHook)}"] > .reel-view`),
@@ -286,6 +298,21 @@ export const FocusPane = Command.define("FocusPane", {
     }),
 });
 
+/** Focuses the tab `tabHook` names, for a tab the arrows step to: the keyboard stays in the
+ *  tab list until the reader goes into the pane. */
+export const FocusTab = Command.define("FocusTab", {
+  args: { tabHook: Schema.String },
+  messages: [Message.CompletedFocusTab],
+  execute: ({ tabHook: hook }) =>
+    Effect.gen(function* () {
+      yield* Render.afterCommit;
+      yield* Effect.sync(() => {
+        document.querySelector<HTMLElement>(`[data-reel-tab="${CSS.escape(hook)}"]`)?.focus();
+      });
+      return Message.CompletedFocusTab();
+    }),
+});
+
 /** Focuses the pane `paneHook` names only where focus was lost (it left with the pane that
  *  held it), so focus the reader put somewhere else stays there. */
 export const RestoreFocus = Command.define("RestoreFocus", {
@@ -327,8 +354,9 @@ export const ScrollIntoView = Command.define("ScrollIntoView", {
 // UPDATE
 
 /** What the reel reads from its parent as each Message arrives: the layout as the
- *  application holds it now. */
-export type UpdateContext = Readonly<{ layout: Layout }>;
+ *  application holds it now, and how the view shows it (`Strip` when not given), which
+ *  `perform` reads. */
+export type UpdateContext = Readonly<{ layout: Layout; arrangement?: Arrangement }>;
 
 type UpdateReturn = Update.ReturnWithOutMessage<Model, Message, OutMessage>;
 
@@ -497,6 +525,19 @@ const resizeSplitter = (
     },
   });
 
+/** Shows the pane `paneId` under its tab and moves the keyboard as `focus` says: into the
+ *  pane for a press, onto the tab for an arrow. */
+const selectTab = (
+  model: Model,
+  layout: Layout,
+  paneId: string,
+  focus: Command.Command<Message>,
+): UpdateReturn =>
+  Option.match(placeOf(layout, paneId), {
+    onNone: () => ({ model }),
+    onSome: (place) => ({ model: focusOn(model, place), commands: [focus] }),
+  });
+
 /** Processes a reel Message against the layout as the application holds it now, and returns
  *  the next Model, Commands and OutMessage. */
 export const update = (model: Model, message: Message, context: UpdateContext): UpdateReturn => {
@@ -542,6 +583,10 @@ export const update = (model: Model, message: Message, context: UpdateContext):
       Option.isSome(model.maybeResizing)
         ? { model: withResizing(model, Option.none()) }
         : whileHeld(model, (held) => cancel(model, layout, held)),
+    PressedTab: ({ paneId }) =>
+      selectTab(model, layout, paneId, FocusPane({ paneHook: paneHook(model, paneId) })),
+    SteppedTab: ({ paneId }) =>
+      selectTab(model, layout, paneId, FocusTab({ tabHook: tabHook(model, paneId) })),
     FocusedPane: ({ paneId }) =>
       Option.match(
         Option.filter(
@@ -578,6 +623,7 @@ export const update = (model: Model, message: Message, context: UpdateContext):
       }),
     CompletedAnnounceReel: () => ({ model }),
     CompletedFocusPane: () => ({ model }),
+    CompletedFocusTab: () => ({ model }),
     CompletedRestoreFocus: () => ({ model }),
     CompletedScrollIntoView: () => ({ model }),
     CompletedSizeLiftedPane: () => ({ model }),
@@ -700,6 +746,51 @@ const requestStep = (
     },
   );
 
+/** The panes in the order their tabs print: column by column, and down each column. */
+const readingOrder = (layout: Layout): ReadonlyArray<Pane> =>
+  Array.flatMap(layout, (column) => column.panes);
+
+/** How far each focus key steps through the tabs: left and up to the one before, right and
+ *  down to the one after. */
+const TAB_STEPS: Readonly<Partial<Record<Action, number>>> = {
+  FocusLeft: -1,
+  FocusUp: -1,
+  FocusRight: 1,
+  FocusDown: 1,
+};
+
+/** `perform` while the panes print as tabs: a focus key moves to the tab beside the focused
+ *  pane's, past neither end; there is no column to move or size. */
+const performTabbed = (model: Model, action: Action, layout: Layout): UpdateReturn => {
+  const panes = readingOrder(layout);
+  const maybeNext = Option.flatMap(
+    Option.all({
+      step: Option.fromUndefinedOr(TAB_STEPS[action]),
+      index: Option.flatMap(focusedPaneId(model, layout), (paneId) =>
+        Array.findFirstIndex(panes, (pane) => pane.id === paneId),
+      ),
+    }),
+    ({ step, index }) =>
+      Option.flatMap(Array.get(panes, index + step), (pane) =>
+        Option.map(placeOf(layout, pane.id), (place) => ({ place, tab: index + step + 1 })),
+      ),
+  );
+
+  return Option.match(
+    Option.filter(maybeNext, () => !isHolding(model)),
+    {
+      onNone: () => ({ model }),
+      onSome: ({ place, tab }) => ({
+        model: focusOn(model, place),
+        commands: [
+          FocusPane({ paneHook: paneHook(model, place.pane.id) }),
+          announce(fill(COPY.focusedTab, { pane: place.pane.label, tab, tabs: panes.length })),
+        ],
+      }),
+    },
+  );
+};
+
 const columnIdAt = (layout: Layout, index: number): Option.Option<string> =>
   Option.map(Array.get(layout, index), ({ id }) => id);
 
@@ -708,10 +799,15 @@ const columnIdAt = (layout: Layout, index: number): Option.Option<string> =>
  * layout as the application holds it: focus moves focus the pane and scroll the reel to it;
  * moves report their request as the OutMessage, which the application applies, with focus
  * kept on the pane. Each is said through the live region. Nothing happens while something is
- * held, or where there is nowhere to go.
+ * held, or where there is nowhere to go. Under tabs, only the focus keys act, stepping from tab
+ * to tab.
  */
 export const perform = (model: Model, action: Action, context: UpdateContext): UpdateReturn => {
-  const { layout } = context;
+  const { layout, arrangement = "Strip" } = context;
+
+  if (arrangement === "Tabs") {
+    return performTabbed(model, action, layout);
+  }
 
   return Option.match(
     Option.filter(focusedPlace(model, layout), () => !isHolding(model)),
@@ -1157,11 +1253,12 @@ export const SizeLiftedPane = Mount.define("SizeLiftedPane", {
 
 // VIEW
 
-/** What the reel hands `toPaneView` for each pane: put `grip` in the Window's `lead` and give
+/** What the reel hands `toPaneView` for each pane: put `lead` in the Window's `lead` and give
  *  it `id`. */
 export type PaneRender = Readonly<{
-  /** The pane's grip, for its title bar's `lead`: a quiet glyph button named "Move <label>". */
-  grip: Html;
+  /** The title bar's `lead`: the pane's grip, a quiet glyph button named "Move <label>", or
+   *  nothing under tabs, where a pane does not move. */
+  lead: ReadonlyArray<Html>;
   /** The window's id, unique in the document. */
   id: string;
 }>;
@@ -1173,15 +1270,21 @@ export type ViewInputs = Readonly<{
   layout: Layout;
   /** Names the reel for screen readers. */
   label: string;
-  /** Renders one pane, a `Window.view` with `render.grip` as its `lead` and `render.id` as its
+  /** Renders one pane, a `Window.view` with `render.lead` as its `lead` and `render.id` as its
    *  `id`. Mark the control focus should land on in it (a terminal's input) with
    *  `data-reel-focus`. */
   toPaneView: (pane: Pane, render: PaneRender) => Html;
+  /** How the panes print: in their columns (`Strip`, when not given), or one at a time under
+   *  their tabs (`Tabs`). Pass the same to `perform`. */
+  arrangement?: Arrangement;
+  /** What a pane's tab prints before its label: a kind glyph. Nothing when not given. */
+  toTabLeadView?: (pane: Pane) => ReadonlyArray<Html>;
 }>;
 
 type ReelInfo = Readonly<{
   model: Model;
   layout: Layout;
+  isTabbed: boolean;
   toPaneView: (pane: Pane, render: PaneRender) => Html;
   maybeFocusedId: Option.Option<string>;
   maybeMark: Option.Option<Target>;
@@ -1202,6 +1305,9 @@ const HELD_STEPS: Readonly<Record<string, Step>> = {
 
 const isDropKey = (key: string): boolean => key === " " || key === "Enter";
 
+/** The anchor every pane is pinned to under tabs: the one slot, the reel's full size. */
+const STAGE_ANCHOR = "--reel-stage";
+
 /** The anchor that pins a pane to its slot. Pane ids are the application's, so the name is
  *  the pane's place in the id order, which the slot and the pane read from one list. */
 const anchorName = (index: number): string => `--reel-${index}`;
@@ -1406,26 +1512,32 @@ const paneLayerView = (
 ): Html => {
   const { model } = info;
 
-  // NOTE: the panes keep one order in the page, by id, whatever the layout: a move changes
-  // only where each is anchored, so no pane's element is taken out and put back, which would
-  // drop focus, a terminal's scroll and whatever a Mount holds inside it.
+  // NOTE: the panes keep one order in the page, by id, whatever the layout or the arrangement:
+  // a move or a change to tabs changes only where each is anchored, so no pane's element is
+  // taken out and put back, which would drop focus, a terminal's scroll and whatever a Mount
+  // holds inside it. Under tabs the panes behind the focused one are hidden, not removed, and
+  // keep their size, so a terminal sized by its box is not resized as the tabs change.
   return h.div(
     [h.Class("reel-panes")],
     Array.map(panes, (pane) => {
       const isFocused = Option.contains(info.maybeFocusedId, pane.id);
       const isHeld = Option.contains(info.maybeCarriedId, pane.id);
+      const isBehind = info.isTabbed && !isFocused;
       return h.keyed("div")(
         pane.id,
         [
-          h.Class(`reel-pane${isFocused ? " focused" : ""}${isHeld ? " drag-dim" : ""}`),
+          h.Class(
+            `reel-pane${isFocused ? " focused" : ""}${isHeld ? " drag-dim" : ""}${isBehind ? " behind" : ""}`,
+          ),
           h.DataAttribute("reel-pane", paneHook(model, pane.id)),
           h.Style({ "--reel-anchor": anchors.get(pane.id) ?? "none" }),
           h.Tabindex(-1),
+          ...(isBehind ? [h.Inert(true)] : []),
           h.OnFocusEnter(Message.FocusedPane({ paneId: pane.id })),
         ],
         [
           info.toPaneView(pane, {
-            grip: gripView(model, pane, h),
+            lead: info.isTabbed ? [] : [gripView(model, pane, h)],
             id: `${model.id}-${pane.id}`,
           }),
         ],
@@ -1484,6 +1596,57 @@ const liftedCopyView = (info: ReelInfo, h: HtmlBuilder<Message>): ReadonlyArray<
   );
 };
 
+/** The tab list under tabs: a tab per pane in reading order, the focused pane's selected. A
+ *  press shows its pane and puts the keyboard in it; the side arrows (wrapping), Home and End
+ *  select as they move and keep the keyboard on the tabs, only the selected tab being in the
+ *  Tab order. A modified arrow is the application's. */
+const tabListView = (
+  info: ReelInfo,
+  label: string,
+  toTabLeadView: (pane: Pane) => ReadonlyArray<Html>,
+  h: HtmlBuilder<Message>,
+): Html => {
+  const { model, layout } = info;
+  const panes = readingOrder(layout);
+  const stepTo = (index: number): Option.Option<Message> =>
+    Option.map(Array.get(panes, (index + panes.length) % panes.length), ({ id }) =>
+      Message.SteppedTab({ paneId: id }),
+    );
+  const keyOf = (index: number, key: string): Option.Option<Message> =>
+    Match.value(key).pipe(
+      Match.when("ArrowLeft", () => stepTo(index - 1)),
+      Match.when("ArrowRight", () => stepTo(index + 1)),
+      Match.when("Home", () => stepTo(0)),
+      Match.when("End", () => stepTo(panes.length - 1)),
+      Match.orElse(() => Option.none()),
+    );
+
+  return h.div(
+    [h.Class("nav tabs reel-tabs"), h.Role("tablist"), h.AriaLabel(label)],
+    Array.map(panes, (pane, index) => {
+      const isSelected = Option.contains(info.maybeFocusedId, pane.id);
+      return h.keyed("button")(
+        pane.id,
+        [
+          h.Type("button"),
+          h.Role("tab"),
+          h.AriaSelected(isSelected),
+          h.AriaControls(`${model.id}-${pane.id}`),
+          h.Tabindex(isSelected ? 0 : -1),
+          h.DataAttribute("reel-tab", tabHook(model, pane.id)),
+          h.OnClick(Message.PressedTab({ paneId: pane.id })),
+          h.OnKeyDownPreventDefault((key, modifiers) =>
+            isPlain(modifiers) ? keyOf(index, key) : Option.none(),
+          ),
+        ],
+        [...toTabLeadView(pane), h.span([h.Class("reel-tab-words")], [pane.label])],
+      );
+    }),
+  );
+};
+
+const NO_TAB_LEAD = (): ReadonlyArray<Html> => [];
+
 /** The layout as it prints, with a dragged splitter's resize shown before it is asked for. */
 const previewed = (model: Model, layout: Layout): Layout =>
   Option.match(
@@ -1504,48 +1667,75 @@ const previewed = (model: Model, layout: Layout): Layout =>
  * panes), Space drops it, and Escape or Tab puts it back. A drop reports what it asks
  * of the layout as the OutMessage. Lift `subscriptions(keyPrefix)` into the application's, or
  * nothing follows the pointer, and call `reconcile` whenever the layout changes.
+ *
+ * Under tabs (`arrangement: "Tabs"`) the reel is `div.reel.tabbed`: a `div.nav.tabs.reel-tabs`
+ * tab list over the scroller, whose track holds one `div.reel-slot.reel-stage` at the reel's
+ * full size where the columns were. Every pane is pinned to it, the focused one shown and the
+ * others `.behind`, hidden and inert; there are no grips and no splitters.
  */
 export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h): Html => {
-  const { label, toPaneView } = viewInputs;
+  const { label, toPaneView, arrangement = "Strip", toTabLeadView = NO_TAB_LEAD } = viewInputs;
+  const isTabbed = arrangement === "Tabs";
   const layout = previewed(model, viewInputs.layout);
   const panes = Array.sort(
     Array.flatMap(layout, (column) => column.panes),
     byId,
   );
-  const anchors = new Map(Array.map(panes, (pane, index) => [pane.id, anchorName(index)] as const));
+  const anchors = new Map(
+    Array.map(
+      panes,
+      (pane, index) => [pane.id, isTabbed ? STAGE_ANCHOR : anchorName(index)] as const,
+    ),
+  );
   const info: ReelInfo = {
     model,
     layout,
+    isTabbed,
     toPaneView,
     maybeFocusedId: focusedPaneId(model, layout),
     maybeMark: markOf(model, layout),
     maybeCarriedId: carriedIdOf(model),
   };
 
+  const strip = (): ReadonlyArray<Html> => [
+    h.keyed("div")("gap:start", [
+      h.Class(
+        `reel-gap${
+          isGapMarked(
+            info,
+            Option.map(Array.head(layout), ({ id }) => id),
+          )
+            ? " drop-here"
+            : ""
+        }`,
+      ),
+    ]),
+    ...Array.flatMap(layout, (column, index) => columnView(info, anchors, column, index, h)),
+  ];
+
   return h.div(
-    [h.Class("reel"), h.Role("group"), h.AriaLabel(label), h.DataAttribute("reel", model.id)],
     [
+      h.Class(isTabbed ? "reel tabbed" : "reel"),
+      h.Role("group"),
+      h.AriaLabel(label),
+      h.DataAttribute("reel", model.id),
+    ],
+    [
+      ...(isTabbed ? [tabListView(info, label, toTabLeadView, h)] : []),
       h.div(
         [h.Class("reel-view")],
         [
           h.div(
             [h.Class("reel-track")],
             [
-              h.keyed("div")("gap:start", [
-                h.Class(
-                  `reel-gap${
-                    isGapMarked(
-                      info,
-                      Option.map(Array.head(layout), ({ id }) => id),
-                    )
-                      ? " drop-here"
-                      : ""
-                  }`,
-                ),
-              ]),
-              ...Array.flatMap(layout, (column, index) =>
-                columnView(info, anchors, column, index, h),
-              ),
+              ...(isTabbed
+                ? [
+                    h.div([
+                      h.Class("reel-slot reel-stage"),
+                      h.Style({ "--reel-anchor": STAGE_ANCHOR }),
+                    ]),
+                  ]
+                : strip()),
               paneLayerView(info, panes, anchors, h),
             ],
           ),