@markout-lang/bootstrap-kit 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markout-lang/bootstrap-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Bootstrap 5.3 as Markout components: one part per component, with the id wiring, the ARIA attributes and the repetition written once",
   "repository": {
     "type": "git",

package/parts/alert.htm

@@ -7,7 +7,7 @@
     `role="alert"` so it is announced, and the `fade show` + close button
     combination that a dismissible one needs to animate out.
 
-    `:heading` and the dismiss button are optional REGIONS, and both are
+    `::heading` and the dismiss button are optional REGIONS, and both are
     `:if`: there is something to decide, not something to show. Truthiness
     is what is wanted of a heading — `:heading=""` is a heading nobody
     asked for, and `:for-data`'s `!= null` would have rendered the empty

package/parts/badge.htm

@@ -24,8 +24,6 @@
     ].filter(s => s).join(' ')}
 
     class=${_class}
-  >
-    <:slot />
-  </:define>
+  ><:slot /></:define>
 
 </lib>

package/parts/breadcrumb.htm

@@ -7,8 +7,11 @@
     describes the entries, the component owns the markup.
 
     An entry is `{ name, link }`. The one without a `link` is the current
-    page, and gets `active` plus `aria-current` — the `<a>` stays in place
-    either way, since an anchor without an `href` renders as plain text.
+    page, and gets `active` plus `aria-current`. It is also the one entry
+    with no `<a>` around it: an anchor with no `href` renders as plain text,
+    which is why it used to be left in place, but it is still an anchor to
+    everything that reads the document rather than looks at it. Bootstrap's
+    own markup for the current crumb is the text on its own, and so is this.
   -->
   <:define tag="bs-breadcrumb:nav"
     aria-label="breadcrumb"
@@ -34,7 +37,8 @@
         :for-as="item"
         :class-active=${!item.link}
         aria-current=${item.link ? null : 'page'}>
-        <a href=${item.link ?? null}>${item.name}</a>
+        <a :if=${item.link} href=${item.link}>${item.name}</a>
+        <:group :else>${item.name}</:group>
       </li>
     </ol>
   </:define>

package/parts/button.htm

@@ -4,7 +4,7 @@
   <!---
     Bootstrap's button, as a real `<button>`.
 
-    `:toggle`/`:target`/`:dismiss` write the `data-bs-*` triplet every
+    `::toggle`/`::target`/`::dismiss` write the `data-bs-*` triplet every
     JS-driven component in this kit is opened and closed by, so a trigger for
     a modal, an offcanvas or a collapse is this same tag rather than a
     component of its own:
@@ -51,8 +51,8 @@
 
   <!---
     The same styling on an `<a>`, for a link that is meant to look like a
-    button. Left as it is, it is an ordinary link; `:button` turns it into
-    one, and `:variant` then means what it means on `bs-button`.
+    button. Left as it is, it is an ordinary link; `::button` turns it into
+    one, and `::variant` then means what it means on `bs-button`.
   -->
   <:define tag="bs-link:a"
 
@@ -83,12 +83,10 @@
     aria-disabled=${disabled ? 'true' : null}
     data-bs-toggle=${toggle}
     data-bs-target=${target}
-  >
-    <:slot />
-  </:define>
+  ><:slot /></:define>
 
   <!---
-    A button group. `:label` is Bootstrap's requirement, not this kit's: the
+    A button group. `::label` is Bootstrap's requirement, not this kit's: the
     group needs an accessible name of its own, since the buttons inside only
     name themselves.
   -->

package/parts/check.htm

@@ -4,9 +4,9 @@
   <!---
     Checkbox, radio and switch are one component: in Bootstrap a switch IS a
     checkbox with `.form-switch` on the wrapper, and a radio differs only by
-    `type`. `:type` picks between them.
+    `type`. `::type` picks between them.
 
-    A group of radios shares one `:name`, as it does in plain HTML — that is
+    A group of radios shares one `::name`, as it does in plain HTML — that is
     what makes them exclusive, and the kit doesn't hide it.
   -->
   <:define tag="bs-check:div"
@@ -54,13 +54,13 @@
 
   <!---
     A whole group of radios or checkboxes from one array, sharing a name and
-    reporting the selection back through `:value`. Entries are strings or
+    reporting the selection back through `::value`. Entries are strings or
     `{ name, value, disabled }`, as in `bs-select`.
 
-    What `:value` HOLDS is decided by `:type`, because that is what the two
+    What `::value` HOLDS is decided by `::type`, because that is what the two
     controls mean: a radio group submits one value and a checkbox group
     submits every box that is ticked, under the same name. So a radio group's
-    `:value` is the selected value or `null`, and a checkbox or switch
+    `::value` is the selected value or `null`, and a checkbox or switch
     group's is an ARRAY, in the order the options were given rather than the
     order they were clicked — a summary sentence reading it should not
     reorder itself under the reader.
@@ -68,7 +68,7 @@
     It used to be one value either way, which made a checkbox group behave
     like a radio group that could not make up its mind: ticking a second box
     unticked the first, and unticking a box left it ticked. Not a shape
-    guessed from a value — `:type` is declared, and it is the same thing that
+    guessed from a value — `::type` is declared, and it is the same thing that
     already picks the input's type and the switch class.
   -->
   <:define tag="bs-check-group:div"
@@ -87,7 +87,7 @@
     :_name=${`bs-check-group-${$id}`}
     :_legendId=${`bs-check-group-legend-${$id}`}
     :_multi=${type !== 'radio'}
-    // a lone value read as a list of one, the way `:options` reads a lone
+    // a lone value read as a list of one, the way `::options` reads a lone
     // string as an entry: passing `:value="Slack"` to a checkbox group says
     // something unambiguous, and spreading a string into characters is not it
     :_selected=${!_multi ? [] : Array.isArray(value) ? value : value == null ? [] : [value]}
@@ -152,8 +152,8 @@
     :_id=${`bs-range-${$id}`}
   >
     <!---
-      The label row, which either half can be alone in: `:showValue` with no
-      `:label` used to render nothing at all, since the row was gated on the
+      The label row, which either half can be alone in: `::showValue` with no
+      `::label` used to render nothing at all, since the row was gated on the
       label.
 
       A row rather than a `<label>` wrapping both, so the readout stays out

package/parts/collapse.htm

@@ -4,12 +4,12 @@
   <!---
     A collapsible region. The trigger is deliberately not part of it —
     anything can open a collapse, and often several things do — so the region
-    takes a `:name` and a `bs-button` points at it:
+    takes a `::name` and a `bs-button` points at it:
 
       <bs-button ::toggle="collapse" ::target="#details">Details</bs-button>
       <bs-collapse ::name="details">…</bs-collapse>
 
-    `:horizontal` collapses width instead of height, in which case Bootstrap
+    `::horizontal` collapses width instead of height, in which case Bootstrap
     needs the content to have a width of its own.
   -->
   <:define tag="bs-collapse:div"

package/parts/dropdown.htm

@@ -3,8 +3,17 @@
 
   <!---
     A dropdown. Entries are `{ name, link, active, disabled, header, divider,
-    select }`; the three shapes Bootstrap draws differently — a divider, a
-    header, an item — are three optional regions over the same list.
+    select }`; the shapes Bootstrap draws differently — a divider, a header,
+    an item — are optional regions over the same list.
+
+    An item comes out as an `<a>` when it has a `link` and a `<button>` when
+    it does not, which is the rule the whole kit follows: what navigates is a
+    link, what acts is a button, and what does neither is not an interactive
+    element at all. The alternative -- one `<a>` with the `href` dropped when
+    there is nowhere to go -- looks identical and is reachable only by mouse:
+    an anchor without an `href` takes no focus and reaches the accessibility
+    tree with no role, so `select` could be triggered by a click and by
+    nothing else. Bootstrap styles `.dropdown-item` on both elements.
 
     The menu is tied to its toggle by `aria-labelledby`, and the id for that
     comes from `$id`, which is unique per instance. That is the general
@@ -72,12 +81,26 @@
           :else-if=${item.header}>${item.header}</h6>
 
         <a class="dropdown-item"
-          :else
+          :else-if=${item.link}
           :class-active=${item.active}
           :class-disabled=${item.disabled}
-          href=${item.link ?? null}
+          href=${item.link}
           aria-current=${item.active ? 'true' : null}
+          aria-disabled=${item.disabled ? 'true' : null}
           :on-click=${() => item.select?.(item)}>${item.name}</a>
+
+        <!---
+          `disabled` rather than `.disabled`: on a button the attribute is
+          the real thing, and it takes the entry out of the tab order as
+          well as greying it. Bootstrap's CSS matches both.
+        -->
+        <button class="dropdown-item"
+          type="button"
+          :else
+          :class-active=${item.active}
+          :attr-disabled=${item.disabled}
+          aria-current=${item.active ? 'true' : null}
+          :on-click=${() => item.select?.(item)}>${item.name}</button>
       </li>
     </ul>
   </:define>

package/parts/input.htm

@@ -5,7 +5,7 @@
     A form control with its label, help text and validation state wired up
     rather than left to the caller.
 
-    `:value` is read AND written: the component keeps it in step with what is
+    `::value` is read AND written: the component keeps it in step with what is
     typed, so a page can name the instance and read it from anywhere else on
     the page —
 
@@ -16,8 +16,8 @@
     special to forms.
 
     The validity policy is this component's own, not Bootstrap's: a control is
-    invalid once it is non-empty and fails `:check`. Empty is neutral, so a
-    form doesn't open covered in errors. `:required` extends that to empty.
+    invalid once it is non-empty and fails `::check`. Empty is neutral, so a
+    form doesn't open covered in errors. `::required` extends that to empty.
 
     `:valid` is the other side of that, and what a form's own controls read —
 
@@ -27,7 +27,7 @@
     It is deliberately NOT the negation of the error state, which is the one
     thing about it worth knowing. An untouched field is not wrong — that is
     what keeps the form out of red — and it is also not something to submit.
-    So empty answers `false` here while showing nothing, and `:required` is
+    So empty answers `false` here while showing nothing, and `::required` is
     what makes empty an error as well as a gap.
 
     Floating labels are the same control with the label after the input
@@ -166,8 +166,8 @@
   </:define>
 
   <!---
-    An input group: text or markup either side of a control. `:prefix` and
-    `:suffix` cover the common case; anything richer goes in the slot as
+    An input group: text or markup either side of a control. `::prefix` and
+    `::suffix` cover the common case; anything richer goes in the slot as
     ordinary `.input-group-text` markup.
   -->
   <:define tag="bs-input-group:div"

package/parts/list-group.htm

@@ -6,10 +6,17 @@
     A list group, from `{ name, link, active, disabled, variant, badge, text }`
     entries.
 
-    Every entry is an `<a>`. Bootstrap only wants `.list-group-item-action`
-    (the hover and focus treatment) on the ones that actually go somewhere, so
-    that class follows `link` rather than being always on — and an anchor with
-    no `href` is inert, which is exactly what a non-link entry should be.
+    An entry with a `link` is an `<a>`; one without is a `<div>`. Both were
+    an `<a>` once, the second with its `href` dropped, which is inert and
+    looks right and is still a link as far as anything reading the document
+    is concerned. `.list-group-item-action` — Bootstrap's hover and focus
+    treatment — goes on the first alone, as it always did, and now it goes on
+    the element that can take focus.
+
+    The body is written twice because the element is what differs and markout
+    has no way to choose a tag name from an expression. Two branches of six
+    lines is the smaller cost: the alternative is a wrapper inside every
+    entry, on every page, to save repeating them here.
   -->
   <:define tag="bs-list-group:div"
 
@@ -31,26 +38,43 @@
 
     class=${_class}
   >
-    <a :for-each=${items}
-      :for-as="item"
-      class="list-group-item d-flex justify-content-between align-items-center"
-      :class-list-group-item-action=${!!item.link}
-      :class-active=${item.active}
-      :class-disabled=${item.disabled}
-      href=${item.link ?? null}
-      aria-current=${item.active ? 'true' : null}
-      aria-disabled=${item.disabled ? 'true' : null}>
-
-      <span>
-        <span :class-fw-bold=${!!item.text}>${item.name}</span>
-        <span class="d-block small opacity-75"
-          :if=${item.text}>${item.text}</span>
-      </span>
-
-      <bs-badge ::variant=${item.badge?.variant ?? 'secondary'}
-        ::pill
-        :if=${item.badge}>${item.badge?.name ?? item.badge}</bs-badge>
-    </a>
+    <:group :for-each=${items} :for-as="item">
+      <a :if=${item.link}
+        class="list-group-item list-group-item-action d-flex justify-content-between align-items-center"
+        :class-active=${item.active}
+        :class-disabled=${item.disabled}
+        href=${item.link}
+        aria-current=${item.active ? 'true' : null}
+        aria-disabled=${item.disabled ? 'true' : null}>
+
+        <span>
+          <span :class-fw-bold=${!!item.text}>${item.name}</span>
+          <span class="d-block small opacity-75"
+            :if=${item.text}>${item.text}</span>
+        </span>
+
+        <bs-badge ::variant=${item.badge?.variant ?? 'secondary'}
+          ::pill
+          :if=${item.badge}>${item.badge?.name ?? item.badge}</bs-badge>
+      </a>
+
+      <div :else
+        class="list-group-item d-flex justify-content-between align-items-center"
+        :class-active=${item.active}
+        :class-disabled=${item.disabled}
+        aria-current=${item.active ? 'true' : null}>
+
+        <span>
+          <span :class-fw-bold=${!!item.text}>${item.name}</span>
+          <span class="d-block small opacity-75"
+            :if=${item.text}>${item.text}</span>
+        </span>
+
+        <bs-badge ::variant=${item.badge?.variant ?? 'secondary'}
+          ::pill
+          :if=${item.badge}>${item.badge?.name ?? item.badge}</bs-badge>
+      </div>
+    </:group>
   </:define>
 
 </lib>

package/parts/modal.htm

@@ -13,7 +13,7 @@
     optional region: a `<:slot>` can't live inside a `:for-each`, and a
     fallback is the better answer here anyway.
 
-    `:open` is the other way in — a value the page owns, which lets the modal
+    `::open` is the other way in — a value the page owns, which lets the modal
     be driven by state rather than by a click. `:handle-open` is the door to
     the imperative half of the DOM: `show()` and `hide()` are verbs, so no
     amount of markup expresses them, and a handler is what runs them.

package/parts/nav.htm

@@ -8,6 +8,12 @@
     Entries are `{ name, link, active, disabled, target }`. For a tabbed
     interface set `:toggle="tab"` (or `"pill"`) and give each entry the
     `target` of its pane; `bs-tab-pane` below is the other half.
+
+    Three elements come out of that, one per kind of entry: a `<button>` when
+    the nav switches panes, an `<a>` when the entry has a `link`, and a
+    `<span>` when it has neither and is a label sitting among the links. The
+    third used to be an `<a>` with no `href`, which reads as a link to
+    anything that is not looking at the screen.
   -->
   <:define tag="bs-nav:ul"
 
@@ -53,16 +59,22 @@
         aria-selected=${item.active ? 'true' : 'false'}>${item.name}</button>
 
       <a class="nav-link"
-        :else
+        :else-if=${item.link}
         :class-active=${item.active}
         :class-disabled=${item.disabled}
-        href=${item.link ?? null}
+        href=${item.link}
         aria-current=${item.active ? 'page' : null}
         aria-disabled=${item.disabled ? 'true' : null}>${item.name}</a>
+
+      <span class="nav-link"
+        :else
+        :class-active=${item.active}
+        :class-disabled=${item.disabled}
+        aria-current=${item.active ? 'page' : null}>${item.name}</span>
     </li>
   </:define>
 
-  <!--- The panes a `:toggle`-ing `bs-nav` switches between. -->
+  <!--- The panes a `::toggle`-ing `bs-nav` switches between. -->
   <:define tag="bs-tab-content:div" class="tab-content">
     <:slot />
   </:define>

package/parts/navbar.htm

@@ -3,7 +3,7 @@
 
   <!---
     Bootstrap's navbar, driven by an array of entries rather than by writing
-    `<li><a class="nav-link">` per link. `:items` is this component's API, not
+    `<li><a class="nav-link">` per link. `::items` is this component's API, not
     something from the Bootstrap docs — see the default below for its shape;
     `button: true` turns an entry into a call to action.
 
@@ -70,14 +70,29 @@
       <div class="collapse navbar-collapse" id=${_id}>
         <ul class=${_navClass}>
           <li class="nav-item" :for-each=${items} :for-as="item">
+            <!---
+              An entry with no `link` is a label among the links rather than
+              a link that goes nowhere, and comes out as a `<span>`. See
+              `nav.htm`, which makes the same distinction for the same
+              reason.
+            -->
             <a class="nav-link"
+              :if=${item.link}
               :class-active=${item.active}
               :class-disabled=${item.disabled}
               :class-btn=${item.button}
               :class-btn-primary=${item.button}
-              href=${item.link ?? null}
+              href=${item.link}
               aria-current=${item.active ? 'page' : null}
               aria-disabled=${item.disabled ? 'true' : null}>${item.name}</a>
+
+            <span class="nav-link"
+              :else
+              :class-active=${item.active}
+              :class-disabled=${item.disabled}
+              :class-btn=${item.button}
+              :class-btn-primary=${item.button}
+              aria-current=${item.active ? 'page' : null}>${item.name}</span>
           </li>
         </ul>
 

package/parts/offcanvas.htm

@@ -4,7 +4,7 @@
 
   <!---
     An offcanvas panel: the same shape as `bs-modal`, opened by a trigger
-    naming it or by the `:open` value.
+    naming it or by the `::open` value.
 
       <bs-button ::toggle="offcanvas" ::target="#menu">Menu</bs-button>
       <bs-offcanvas ::name="menu" ::title="Menu">…</bs-offcanvas>

package/parts/pagination.htm

@@ -3,18 +3,26 @@
 
   <!---
     Pagination driven by a page number rather than by markup: give it the
-    `:current` page and the total `:pages` and it works out which entry is
+    `::current` page and the total `::pages` and it works out which entry is
     active and when the arrows are dead.
 
-    The current page is `:current` rather than `:page`, because `page` is
+    The current page is `::current` rather than `:page`, because `page` is
     already the name of `<html>`'s own scope — a parameter of that name would
     resolve to the scope instead of to the number.
 
-    `:link` and `:select` are the two ways to answer "what does a click do".
-    `:link` builds an href per page for a server-rendered list; `:select` is
+    `::link` and `::select` are the two ways to answer "what does a click do".
+    `::link` builds an href per page for a server-rendered list; `::select` is
     called with the page number for one that stays on the page. Both are
     ordinary function parameters — a callback the component calls, not a DOM
     event, so it is a value and not an `:on-` handler.
+
+    They also decide the element. `::link` yields an href, so those entries
+    are `<a>`; with `::select` alone — the default, and the mode a page that
+    never reloads uses — there is nowhere to go, and each entry is a
+    `<button>`. Written as an `<a>` with no `href` it looks right and pages
+    for a mouse alone: an anchor without an `href` takes no focus and carries
+    no role, so the whole control is unreachable from the keyboard. Bootstrap
+    styles `.page-link` on both.
   -->
   <:define tag="bs-pagination:nav"
 
@@ -41,11 +49,27 @@
     aria-label=${label}
   >
     <ul class=${_class}>
-      <li class="page-item" :class-disabled=${current <= 1}>
+      <!---
+        `_href` is declared on the `<li>` so the two branches inside read one
+        value rather than calling `link()` twice each. The `<li>` is a scope
+        like any element, which is what makes that the obvious place for it.
+      -->
+      <li class="page-item"
+        :class-disabled=${current <= 1}
+        :_href=${link(current - 1)}>
         <a class="page-link"
-          href=${link(current - 1)}
+          :if=${_href != null}
+          href=${_href}
           aria-label="Previous"
+          aria-disabled=${current <= 1 ? 'true' : null}
           :on-click=${() => current > 1 && select(current - 1)}>${prev}</a>
+
+        <button class="page-link"
+          type="button"
+          :else
+          :attr-disabled=${current <= 1}
+          aria-label="Previous"
+          :on-click=${() => select(current - 1)}>${prev}</button>
       </li>
 
       <li class="page-item"
@@ -53,17 +77,35 @@
         :for-as="n"
         :for-key=${n}
         :class-active=${n === current}
-        aria-current=${n === current ? 'page' : null}>
+        aria-current=${n === current ? 'page' : null}
+        :_href=${link(n)}>
         <a class="page-link"
-          href=${link(n)}
+          :if=${_href != null}
+          href=${_href}
           :on-click=${() => select(n)}>${n}</a>
+
+        <button class="page-link"
+          type="button"
+          :else
+          :on-click=${() => select(n)}>${n}</button>
       </li>
 
-      <li class="page-item" :class-disabled=${current >= pages}>
+      <li class="page-item"
+        :class-disabled=${current >= pages}
+        :_href=${link(current + 1)}>
         <a class="page-link"
-          href=${link(current + 1)}
+          :if=${_href != null}
+          href=${_href}
           aria-label="Next"
+          aria-disabled=${current >= pages ? 'true' : null}
           :on-click=${() => current < pages && select(current + 1)}>${next}</a>
+
+        <button class="page-link"
+          type="button"
+          :else
+          :attr-disabled=${current >= pages}
+          aria-label="Next"
+          :on-click=${() => select(current + 1)}>${next}</button>
       </li>
     </ul>
   </:define>

package/parts/progress.htm

@@ -4,9 +4,9 @@
   <!---
     Bootstrap 5.3 moved the ARIA onto the outer `.progress` and left
     `.progress-bar` as the visual fill, so a progress bar is two elements
-    whose values have to agree. Here they are derived from one `:value`.
+    whose values have to agree. Here they are derived from one `::value`.
 
-    `:label` is the text drawn inside the bar; leave it off for a bare bar.
+    `::label` is the text drawn inside the bar; leave it off for a bare bar.
   -->
   <:define tag="bs-progress:div"
     class="progress"

package/parts/scrollspy.htm

@@ -3,7 +3,7 @@
 
   <!---
     Scrollspy is behaviour rather than appearance: it marks the entry in a
-    nav that matches what is currently on screen. `:target` is the selector
+    nav that matches what is currently on screen. `::target` is the selector
     of that nav, and the element this sits on is the thing being scrolled.
 
       <bs-nav ::vertical id="toc" ::items=${sections} />

package/parts/table.htm

@@ -2,14 +2,14 @@
   <:import src="base.htm" />
 
   <!---
-    A table from `:columns` and `:rows`.
+    A table from `::columns` and `::rows`.
 
     A column is `{ key, name, class }`; a row is any object the columns can
     be read out of. That is the one place in this kit where markup is
     generated from data twice over — once per column, once per row — and it
     is the case where writing it by hand hurts most.
 
-    `:responsive` is a class on the same element rather than an extra
+    `::responsive` is a class on the same element rather than an extra
     wrapper: `.table-responsive` only sets `overflow-x`, so it costs nothing
     when off.
   -->