howdoc 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 168c62956710423757404d82987844f3b33d64ebdc112f9c5c0354cd336c0944
-  data.tar.gz: 842bebc8325f407a398af4f87e050819325cdafea0d26ab568a694c91f3c765f
+  metadata.gz: 87dfef0ef3ca14057c666eaa64c003057f7b7f8ba17cb1f992375c4add7358e6
+  data.tar.gz: 5a3f3ecfccd3e57262e00b434ba69d79874251d25e74b527e8a6d03754e5c0ef
 SHA512:
-  metadata.gz: 139dfdadfe51e236abfb19bff5cb95bd28d6cb8ddd7e817b1ca9cb93362cd5cb3b9b83313544c3b9d35423f58a1385d2db807794dd2723f1e0fd4287732f34ac
-  data.tar.gz: 57d7cc5bafa03b0b103204e3a13a04015d5676445050a621cbca7b8be6e2290b01fd39bd4dd8db30377030277b66c01f57780b8462358a9a23a3b05be179159d
+  metadata.gz: 80ffc63f82dd61163966cd9afa236ff758b29ad02bf1dcf54486d41db1fcdee943bcbd337d0966a9a6c69aae624355d43b732164ac31425483dabc9c395812d0
+  data.tar.gz: 756e73c34a33a1a4b5cdb0b41f4cf2143414c3b97bc30096e62511d38961ff8cc07b44ba9e35c2956b0cb0e942bd9d669bb8574ec2d578a6dba368c8dce5135d

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.5.0
+
+The menu now fits a phone. Twenty guides listed above the page filled the
+screen before the guide a reader had come for began, so a narrow screen folds
+the list away behind a line they can tap, and a wide one, which has room for it
+beside the page, shows it exactly as before.
+
+- The menu on a narrow screen is a slim bar carrying the name of the
+  documentation set, the languages and one line to open the guides
+  (`howdoc.nav.guides`). It follows the reader down the page while the list is
+  folded, and steps out of the way while it is open.
+- The index is the one page whose menu is the page, so there the list is open
+  from the start and follows the heading that says what the guides are for
+  instead of pushing it under twenty links.
+- Only `shared/html/nav.haml` and the stylesheet changed, so an application
+  with a menu template of its own keeps what it has.
+
+## 0.4.0
+
+Screenshots can now show what the step is about, the way a guide made by hand
+does: an arrow on the button being pressed, a highlight around the words being
+looked for.
+
+- The marker is drawn in the browser between sizing the window and taking the
+  picture, and removed again straight after -- including when the picture could
+  not be taken, so nothing is left pointing at what has since moved.
+- An arrow's tip goes on the middle of a button, and below anything small
+  enough that the arrow would cover it.
+- A highlight measures the words themselves, through a range around the match,
+  rather than the paragraph that happens to hold them.
+- `config.illustrate_actions` illustrates every action rather than only the
+  moments a reader arrives somewhere. That is what makes the pointer worth
+  having: a picture per click, each one marked.
+- `config.marker`, `config.marker_colour`, `config.marker_dim` and
+  `config.marker_size` decide whether and how it is drawn.
+
 ## 0.3.1
 
 - The menu pass left a blank line behind every time it ran. A suite that builds

data/README.md

@@ -114,6 +114,31 @@ By default `visit` and `assert_text` are illustrated and the action verbs are
 not, on the grounds that a picture is worth showing when the reader arrives
 somewhere, not every time they press a button.
 
+## Showing where to look
+
+A screenshot of a busy page does not say which of forty things on it the step is
+about, so howdoc draws the mark a person would draw by hand:
+
+* an arrow with its tip on the button about to be pressed, on the field about to
+  be filled, on the menu about to be chosen from
+* a highlight around the words an assertion was looking for
+
+It is drawn in the browser between sizing the window and taking the picture, and
+taken off again straight after, so the page the test goes on driving is the page
+it was. There is no cursor in a headless screenshot to photograph -- the arrow is
+drawn, and its tip moves below anything too small for it to sit on without
+covering.
+
+By default only the moments a reader arrives somewhere are illustrated. A guide
+that shows every click is one line of configuration:
+
+```ruby
+config.illustrate_actions = true    # a picture per action, each one marked
+config.marker_colour = '#e11d48'    # the arrow and the highlight
+config.marker_dim = true            # dim the rest of the page around the mark
+config.marker = false               # or draw nothing at all
+```
+
 ## Your own helpers
 
 Real suites have helpers Capybara has no verb for -- a custom editor, a menu
@@ -238,6 +263,11 @@ an empty placeholder and the index pass -- which has just read every page back
 
 Both are optional. A template that carries neither is left exactly as it is.
 
+Above the page rather than beside it -- a phone, a narrow window -- the list of
+guides folds away behind a line the reader taps, so the guide begins where the
+screen begins. The stylesheet unfolds it again where there is room beside the
+page, and the index, whose menu is the page, is open from the start.
+
 The menu also links the same guide in every other language the application
 publishes. Guides are matched by their identifier rather than their file name,
 because a translated heading gives a translated file name, and each language

data/config/locales/howdoc.en.yml

@@ -21,6 +21,8 @@ en:
       follow_steps: 'Follow these steps:'
     languages:
       en: English
+    nav:
+      guides: All guides
     pager:
       next: Next
       previous: Previous

data/config/locales/howdoc.et.yml

@@ -21,6 +21,8 @@ et:
       follow_steps: 'Palun jälgige järgnevaid samme:'
     languages:
       et: Eesti
+    nav:
+      guides: Kõik juhendid
     pager:
       next: Järgmine
       previous: Eelmine

data/lib/howdoc/capybara_actions.rb

@@ -30,7 +30,10 @@ module Howdoc
     def fill_in(locator = nil, with:, currently_with: nil, fill_options: {}, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(fill_in_action(locator), doc, field: howdoc_field_label(locator), value: with)
+      narrate(
+        fill_in_action(locator), doc,
+        target: [:fillable_field, locator], field: howdoc_field_label(locator), value: with
+      )
 
       super(locator, with:, currently_with:, fill_options:, **options)
     end
@@ -38,7 +41,7 @@ module Howdoc
     def select(value = nil, from: nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:select, doc, value:, field: howdoc_field_label(from))
+      narrate(:select, doc, target: [:select, from], value:, field: howdoc_field_label(from))
 
       super(value, from:, **options)
     end
@@ -46,7 +49,7 @@ module Howdoc
     def check(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:check, doc, field: howdoc_field_label(locator))
+      narrate(:check, doc, target: [:checkbox, locator], field: howdoc_field_label(locator))
 
       super(locator, **options)
     end
@@ -54,7 +57,7 @@ module Howdoc
     def uncheck(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:uncheck, doc, field: howdoc_field_label(locator))
+      narrate(:uncheck, doc, target: [:checkbox, locator], field: howdoc_field_label(locator))
 
       super(locator, **options)
     end
@@ -62,7 +65,7 @@ module Howdoc
     def choose(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:choose, doc, field: howdoc_field_label(locator))
+      narrate(:choose, doc, target: [:radio_button, locator], field: howdoc_field_label(locator))
 
       super(locator, **options)
     end
@@ -70,7 +73,7 @@ module Howdoc
     def click_button(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:click_button, doc, locator:)
+      narrate(:click_button, doc, target: [:button, locator], locator:)
 
       super(locator, **options)
     end
@@ -78,7 +81,7 @@ module Howdoc
     def click_link(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:click_link, doc, locator:)
+      narrate(:click_link, doc, target: [:link, locator], locator:)
 
       super(locator, **options)
     end
@@ -86,7 +89,7 @@ module Howdoc
     def click_on(locator = nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:click_on, doc, locator:)
+      narrate(:click_on, doc, target: [:link_or_button, locator], locator:)
 
       super(locator, **options)
     end
@@ -95,7 +98,7 @@ module Howdoc
     def attach_file(locator = nil, paths, make_visible: nil, **options)
       doc = Howdoc.extract_options!(options)
 
-      narrate(:attach_file, doc, field: howdoc_field_label(locator))
+      narrate(:attach_file, doc, target: [:file_field, locator], field: howdoc_field_label(locator))
 
       super(locator, paths, make_visible:, **options)
     end
@@ -107,7 +110,10 @@ module Howdoc
       doc = Howdoc.extract_options!(options)
       result = super(locator, **options)
 
-      narrate(:assert_text, doc, capture: true, arrival: true, text: locator)
+      narrate(
+        :assert_text, doc,
+        capture: true, arrival: true, text: locator, target: locator.to_s, marker_mode: :highlight
+      )
       result
     end
 
@@ -138,19 +144,48 @@ module Howdoc
       host.nil? ? visit_uri.to_s : "https://#{host}#{visit_uri}"
     end
 
-    def narrate(action, doc_options, capture: false, arrival: false, **payload)
+    def narrate(action, doc_options, capture: false, arrival: false, target: nil,
+                marker_mode: :pointer, **payload)
       step = Howdoc.record(action, arrival:, nodoc: doc_options[:nodoc], **payload)
       return nil if step.nil?
 
-      illustrate = doc_options.fetch(:screenshot, capture)
+      illustrate = doc_options.fetch(:screenshot, capture || illustrated_action?(target))
       return step unless illustrate
 
       Howdoc.capture(
         page,
         full_page: doc_options[:full_page] || false,
-        no_screenshot: doc_options[:no_screenshot] || false
+        no_screenshot: doc_options[:no_screenshot] || false,
+        marker: howdoc_marker(target), marker_mode:
       )
       step
     end
+
+    # An action is illustrated only when the application asked for every click
+    # to be shown; a picture after each button is a lot of pictures, and worth
+    # it only when they are marked.
+    def illustrated_action?(target)
+      !target.nil? && Howdoc.config.illustrate_actions?
+    end
+
+    # What the marker should point at. A string is the words an assertion was
+    # looking for, which the browser finds for itself; anything else names a
+    # Capybara selector and is resolved here, in whatever scope the test is in,
+    # exactly as the action about to happen would resolve it.
+    #
+    # Never waits: the action itself is entitled to wait, but a picture is not
+    # worth holding a suite up for, and a marker nobody could place is simply
+    # not drawn.
+    def howdoc_marker(target)
+      return nil if target.nil? || !Howdoc.config.marker?
+      return target if target.is_a?(String)
+
+      kind, locator = target
+      return nil if locator.nil?
+
+      page.find(kind, locator, match: :first, wait: 0)
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/howdoc/configuration.rb

@@ -35,6 +35,29 @@ module Howdoc
     # page, so that guides do not mix wildly different image proportions.
     attr_accessor :screenshot_height
 
+    # Whether a screenshot points at what the step is about: an arrow on the
+    # button being pressed, a highlight around the words being looked for. Off
+    # leaves the pictures exactly as the browser rendered them.
+    attr_accessor :marker
+
+    # The colour of that arrow and highlight. Red by convention, because a guide
+    # is read at a glance and red is the one colour an interface rarely uses for
+    # anything else.
+    attr_accessor :marker_colour
+
+    # Dims the rest of the page around what is marked. Emphatic, and worth it
+    # for a crowded screen; off by default because it changes every picture.
+    attr_accessor :marker_dim
+
+    # How tall the drawn pointer is, in CSS pixels.
+    attr_accessor :marker_size
+
+    # Whether an action -- a click, a choice, something typed -- is illustrated
+    # as well as narrated. Off by default: a picture belongs where the reader
+    # arrives somewhere new, not after every button. Turning it on is what makes
+    # the pointer worth having, so a guide shows every click.
+    attr_accessor :illustrate_actions
+
     # Files in the output directory that the clean task must leave alone,
     # typically hand-maintained landing pages.
     attr_accessor :preserved_files
@@ -53,19 +76,28 @@ module Howdoc
     attr_reader :locale_paths
 
     def initialize
+      reset_defaults
+      @template_paths = []
+      @locale_paths = []
+      @field_label = nil
+      @sort_key = nil
+      @group_label = nil
+    end
+
+    def reset_defaults
       @root = 'doc/howdoc'
       @enabled = false
       @host = nil
       @formats = %i[html]
       @locales = nil
       @screenshot_height = 940
+      @marker = true
+      @marker_colour = '#e11d48'
+      @marker_dim = false
+      @marker_size = 52
+      @illustrate_actions = false
       @preserved_files = %w[index.html .keep]
       @install_assets = true
-      @template_paths = []
-      @locale_paths = []
-      @field_label = nil
-      @sort_key = nil
-      @group_label = nil
     end
 
     def register_template_path(path)
@@ -105,5 +137,13 @@ module Howdoc
     def enabled?
       !!@enabled
     end
+
+    def marker?
+      !!@marker
+    end
+
+    def illustrate_actions?
+      !!@illustrate_actions
+    end
   end
 end

data/lib/howdoc/marker.js

@@ -0,0 +1,113 @@
+// Drawn over the page for as long as it takes to photograph it: an arrow on
+// what is about to be clicked, a highlight around the words that were looked
+// for. Called with no target, it takes off whatever it drew last time.
+var MARKER = 'howdoc-marker';
+var POINTER =
+  // The arrow, in a 24x32 box with its tip at 0,0 -- the shape every operating
+  // system has drawn since 1981, so a reader knows it without being told.
+  'M0 0 L0 22.6 L5.6 17.4 L9.4 25.9 L13.6 23.9 L9.8 15.7 L17.6 15.4 Z';
+
+var target = arguments[0];
+var options = arguments[1] || {};
+
+var previous = document.getElementById(MARKER);
+if (previous) { previous.parentNode.removeChild(previous); }
+if (!target) { return null; }
+
+var element = target;
+var rect = null;
+
+if (typeof target === 'string') {
+  // The words themselves, not the paragraph holding them: a range around
+  // the match measures what a reader would underline with a finger, where
+  // the element around it is as wide as the page.
+  var wanted = target.replace(/\\s+/g, ' ').trim();
+  var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
+  var node = null;
+  element = null;
+
+  while ((node = walker.nextNode())) {
+    var at = node.data.indexOf(wanted);
+    if (at === -1 || !node.parentElement || !node.parentElement.getClientRects().length) {
+      continue;
+    }
+
+    var range = document.createRange();
+    range.setStart(node, at);
+    range.setEnd(node, at + wanted.length);
+    rect = range.getBoundingClientRect();
+    element = node.parentElement;
+    break;
+  }
+}
+
+if (!element || !element.getClientRects().length) { return null; }
+if (!rect) { rect = element.getBoundingClientRect(); }
+
+// A field dressed by a widget -- select2 and its like -- leaves the real
+// <select> hidden and all but sizeless in a corner of what the reader actually
+// sees. Point at the thing on the screen: the nearest ancestor that is really
+// laid out.
+if (rect.width < 8 || rect.height < 8) {
+  var holder = element.parentElement;
+
+  while (holder && holder !== document.body) {
+    var box = holder.getBoundingClientRect();
+
+    if (box.width >= 8 && box.height >= 8) { element = holder; rect = box; break; }
+
+    holder = holder.parentElement;
+  }
+}
+var left = rect.left + window.scrollX;
+var top = rect.top + window.scrollY;
+var colour = options.colour || '#e11d48';
+var padding = 6;
+
+var layer = document.createElement('div');
+layer.id = MARKER;
+layer.style.cssText = 'position:absolute;left:0;top:0;width:0;height:0;' +
+  'z-index:2147483647;pointer-events:none;';
+
+var ring = document.createElement('div');
+ring.style.cssText = 'position:absolute;box-sizing:border-box;' +
+  'left:' + (left - padding) + 'px;top:' + (top - padding) + 'px;' +
+  'width:' + (rect.width + padding * 2) + 'px;' +
+  'height:' + (rect.height + padding * 2) + 'px;' +
+  'border:3px solid ' + colour + ';border-radius:8px;' +
+  (options.mode === 'highlight' ? 'background:' + colour + '1f;' : '') +
+  (options.dim ? 'box-shadow:0 0 0 9999px rgba(15,23,42,0.45);' : '');
+layer.appendChild(ring);
+
+if (options.mode !== 'highlight') {
+  var size = options.size || 52;
+
+  // The tip goes on the middle of a button, where a hand would put it, and a
+  // little below the middle on a field or a select: there the value is read
+  // along the top of the box, and an arrow through the middle of it sits in
+  // the way of the very thing the reader is meant to see.
+  //
+  // On something small -- a link in a table, a word in a row -- the arrow would
+  // cover what it points at whatever we do, so it hangs below instead.
+  var small = rect.width < 120 || rect.height < 32;
+  var tipLeft = left + rect.width / 2;
+  var tipTop = small ? top + rect.height - 2 : top + rect.height * 0.62;
+  var arrow = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  arrow.setAttribute('viewBox', '0 0 24 32');
+  arrow.setAttribute('width', size);
+  arrow.setAttribute('height', size * 32 / 24);
+  arrow.style.cssText = 'position:absolute;left:' + tipLeft + 'px;top:' + tipTop + 'px;' +
+    'filter:drop-shadow(0 2px 3px rgba(15,23,42,0.45));';
+
+  var path = document.createElementNS('http://www.w3.org/2000/svg', 'path');
+  path.setAttribute('d', POINTER);
+  path.setAttribute('fill', '#ffffff');
+  path.setAttribute('stroke', colour);
+  path.setAttribute('stroke-width', '2.2');
+  path.setAttribute('stroke-linejoin', 'round');
+  arrow.appendChild(path);
+  layer.appendChild(arrow);
+}
+
+document.body.appendChild(layer);
+return true;

data/lib/howdoc/marker.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Howdoc
+  # Shows the reader where to look.
+  #
+  # A screenshot of a busy page does not say which of forty things on it the
+  # step is about. A guide made by hand solves that with a red circle drawn over
+  # the button; this draws the same thing, in the browser, in the moment between
+  # the window being sized and the picture being taken -- and takes it off again
+  # afterwards, so the page the test goes on driving is the page it was.
+  #
+  # There is no cursor in a headless screenshot to photograph, so the pointer is
+  # drawn: an arrow with its tip on whatever is about to be clicked. An assertion
+  # gets no arrow, because nobody is pointing at anything -- the words the reader
+  # should see are highlighted instead.
+  #
+  # The drawing itself is JavaScript, and lives in JavaScript: marker.js beside
+  # this file. Asked to draw nothing, it takes off what it drew last time, which
+  # is how the marker is removed.
+  module Marker
+    SCRIPT = File.read(File.expand_path('marker.js', __dir__)).freeze
+
+    module_function
+
+    # Draws the marker, runs the block, and takes it off again -- including when
+    # the block raised, because a marker left behind would appear in the next
+    # picture, pointing at something that is no longer there.
+    def around(page, target, mode:)
+      return yield if target.nil? || !Howdoc.config.marker?
+
+      drawn = draw(page, target, mode:)
+
+      begin
+        yield
+      ensure
+        draw(page, nil, mode:) if drawn
+      end
+    end
+
+    def draw(page, target, mode:)
+      page.execute_script(SCRIPT, target, options(mode))
+      true
+    rescue StandardError
+      # A marker is a courtesy. A page that will not take one -- a frame gone, an
+      # element detached between finding it and drawing on it -- still has a
+      # picture worth taking.
+      false
+    end
+
+    def options(mode)
+      {
+        'mode' => mode.to_s,
+        'colour' => Howdoc.config.marker_colour,
+        'dim' => Howdoc.config.marker_dim,
+        'size' => Howdoc.config.marker_size
+      }
+    end
+  end
+end

data/lib/howdoc/recorder.rb

@@ -54,7 +54,7 @@ module Howdoc
     # Illustrates the step recorded most recently. Separate from +record+
     # because a screenshot has to be taken while the browser is still on the
     # page, whereas the sentence can be composed at any time.
-    def capture(page, full_page: false, no_screenshot: false)
+    def capture(page, full_page: false, no_screenshot: false, marker: nil, marker_mode: :pointer)
       return nil if no_screenshot || !recording?
 
       step = current.last_step || current.new_step
@@ -64,7 +64,7 @@ module Howdoc
         page,
         path: File.join(current.image_dir, filename),
         height: Howdoc.config.screenshot_height,
-        full_page:
+        full_page:, marker:, marker_mode:
       )
 
       step.screenshot = filename

data/lib/howdoc/screenshot.rb

@@ -7,7 +7,10 @@ module Howdoc
   module Screenshot
     module_function
 
-    def capture(page, path:, height:, full_page: false)
+    # The marker is drawn after the window has been sized and not before: a
+    # resize lays the page out again, and an arrow placed by the old layout
+    # would point at where the button used to be.
+    def capture(page, path:, height:, full_page: false, marker: nil, marker_mode: :pointer)
       FileUtils.mkdir_p(File.dirname(path))
 
       width, current_height = page.current_window.size
@@ -15,7 +18,10 @@ module Howdoc
 
       page.current_window.resize_to(width, target) unless target == current_height
 
-      page.save_screenshot(path, full: true)
+      Marker.around(page, marker, mode: marker_mode) do
+        page.save_screenshot(path, full: true)
+      end
+
       path
     end
 

data/lib/howdoc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Howdoc
-  VERSION = '0.3.1'
+  VERSION = '0.5.0'
 end

data/lib/howdoc.rb

@@ -9,6 +9,7 @@ require_relative 'howdoc/narrator'
 require_relative 'howdoc/step'
 require_relative 'howdoc/edition'
 require_relative 'howdoc/document'
+require_relative 'howdoc/marker'
 require_relative 'howdoc/screenshot'
 require_relative 'howdoc/recorder'
 require_relative 'howdoc/templates'

data/templates/default/assets/howdoc.css

@@ -31,6 +31,12 @@ body.howdoc {
   padding: 3rem 1.25rem 6rem;
 }
 
+/* The index ends where its menu begins, so the space below it is the menu's
+   to give. */
+.howdoc-index {
+  padding-bottom: 1.5rem;
+}
+
 .howdoc h1 {
   margin: 0 0 1rem;
   font-size: 1.9rem;
@@ -68,7 +74,7 @@ body.howdoc {
 
 .howdoc-toc {
   list-style: none;
-  margin: 1.5rem 0 0;
+  margin: 1rem 0 0;
   padding: 0;
 }
 
@@ -96,19 +102,84 @@ body.howdoc {
   text-decoration: underline;
 }
 
-/* The menu sits beside the page it belongs to, and above it when there is no
-   room beside. A guide written before the index pass has an empty menu, and an
-   empty menu is no menu at all. */
+/* The menu sits beside the page it belongs to, and folded above it when there
+   is no room beside. A guide written before the index pass has an empty menu,
+   and an empty menu is no menu at all. */
 .howdoc-nav:empty,
 .howdoc-pager:empty {
   display: none;
 }
 
+/* Above the page, the menu is a slim bar the reader keeps within reach
+   wherever they have scrolled to, with the guides folded away behind a line
+   they can tap. Unfolded, the list is taller than the screen, so the bar stops
+   following along and scrolls away with the page like anything else. */
 .howdoc-nav {
-  padding: 1.5rem 1.25rem;
+  position: sticky;
+  top: 0;
+  z-index: 2;
+  background: var(--howdoc-bg);
+  padding: 0.9rem 1.25rem 1rem;
   border-bottom: 1px solid var(--howdoc-rule);
 }
 
+.howdoc-nav:has(.howdoc-nav-guides[open]) {
+  position: static;
+}
+
+/* The index is the one page whose menu is the page, so its menu is open and
+   there is nothing to fold. It comes after the heading that says what the
+   guides are for, rather than pushing that heading under twenty links. */
+body.howdoc {
+  display: flex;
+  flex-direction: column;
+}
+
+.howdoc-nav-index {
+  order: 1;
+}
+
+/* Nothing to fold on the index: the list is the page, so the line that would
+   fold it away is not offered there. */
+.howdoc-nav-index .howdoc-nav-summary {
+  display: none;
+}
+
+.howdoc-nav-summary {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.75rem;
+  margin-top: 0.75rem;
+  padding: 0.55rem 0.85rem;
+  border: 1px solid var(--howdoc-rule);
+  border-radius: 8px;
+  color: var(--howdoc-fg);
+  font-size: 0.95rem;
+  font-weight: 600;
+  cursor: pointer;
+  list-style: none;
+}
+
+.howdoc-nav-summary::-webkit-details-marker {
+  display: none;
+}
+
+/* The chevron that says the line can be tapped: down while the list is folded,
+   up while it is not. */
+.howdoc-nav-summary::after {
+  content: '';
+  width: 0.45rem;
+  height: 0.45rem;
+  border-right: 2px solid var(--howdoc-muted);
+  border-bottom: 2px solid var(--howdoc-muted);
+  transform: translateY(-0.15rem) rotate(45deg);
+}
+
+.howdoc-nav-guides[open] > .howdoc-nav-summary::after {
+  transform: translateY(0.15rem) rotate(-135deg);
+}
+
 @media (min-width: 60rem) {
   body.howdoc {
     display: grid;
@@ -116,15 +187,39 @@ body.howdoc {
     align-items: start;
   }
 
-  .howdoc-nav {
+  .howdoc-nav,
+  .howdoc-nav:has(.howdoc-nav-guides[open]) {
     position: sticky;
     top: 0;
+    z-index: auto;
     max-height: 100vh;
     overflow-y: auto;
     padding: 2rem 1.25rem 3rem;
     border-right: 1px solid var(--howdoc-rule);
     border-bottom: 0;
   }
+
+  .howdoc-nav-index {
+    order: 0;
+  }
+
+  /* Beside the page there is room for the whole list, so the fold is undone:
+     the line to tap goes away and every guide is shown whether the reader ever
+     tapped it or not. Two rules for two kinds of browser -- the older kind
+     folds content away by not displaying it, the newer kind through
+     ::details-content. */
+  .howdoc-nav-summary {
+    display: none;
+  }
+
+  .howdoc-nav-guides > *:not(summary) {
+    display: block;
+  }
+
+  .howdoc-nav-guides::details-content {
+    content-visibility: visible;
+    block-size: auto;
+  }
 }
 
 .howdoc-nav-head {

data/templates/default/shared/html/nav.haml

@@ -2,7 +2,7 @@
 -# no other guide exists yet -- so a guide leaves the empty <nav> below and the
 -# index pass fills it in once every guide is on disk. The index renders it
 -# directly, because by then it knows.
-%nav.howdoc-nav{ data: { howdoc_nav: true } }
+%nav.howdoc-nav{ class: ('howdoc-nav-index' if @current.nil?), data: { howdoc_nav: true } }
   .howdoc-nav-head
     %a.howdoc-nav-home{ href: './index.html' }= Howdoc::Narrator.phrase(:index, :title, locale: @locale)
     - if @languages.size > 1
@@ -13,13 +13,20 @@
               %a{ href: language[:href], lang: language[:code] }= language[:label]
             - else
               %span{ lang: language[:code] }= language[:label]
-  %ul.howdoc-toc
-    - previous_group = nil
-    - @records.each do |record|
-      - group = @config.group_label.call(record)
-      - if group && group != previous_group
-        %li.howdoc-toc-group= group
-        - previous_group = group
-      - current = @current && record.filename == @current.filename
-      %li.howdoc-toc-entry{ class: ('howdoc-current' if current) }
-        %a{ href: "./#{record.filename}", 'aria-current': (current ? 'page' : nil) }= record.heading
+  -# On a phone a list of twenty guides fills the screen before the guide the
+  -# reader came to read has begun, so the list is folded away behind a line
+  -# they can tap. A wide screen has room for it beside the page and unfolds it
+  -# again in the stylesheet. The index is the one page whose menu is the page,
+  -# so there it is open from the start.
+  %details.howdoc-nav-guides{ open: @current.nil? }
+    %summary.howdoc-nav-summary= Howdoc::Narrator.phrase(:nav, :guides, locale: @locale)
+    %ul.howdoc-toc
+      - previous_group = nil
+      - @records.each do |record|
+        - group = @config.group_label.call(record)
+        - if group && group != previous_group
+          %li.howdoc-toc-group= group
+          - previous_group = group
+        - current = @current && record.filename == @current.filename
+        %li.howdoc-toc-entry{ class: ('howdoc-current' if current) }
+          %a{ href: "./#{record.filename}", 'aria-current': (current ? 'page' : nil) }= record.heading

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: howdoc
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Priit Tark
@@ -59,6 +59,8 @@ files:
 - lib/howdoc/configuration.rb
 - lib/howdoc/document.rb
 - lib/howdoc/edition.rb
+- lib/howdoc/marker.js
+- lib/howdoc/marker.rb
 - lib/howdoc/minitest.rb
 - lib/howdoc/narrator.rb
 - lib/howdoc/navigation.rb