@markout-lang/bootstrap-kit 0.2.0

package/parts/breadcrumb.htm

@@ -0,0 +1,44 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    The first of the kit's list-driven components. Where a component repeats
+    one shape over a list, its API is an array rather than a slot: the caller
+    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.
+  -->
+  <:define tag="bs-breadcrumb:nav"
+    aria-label="breadcrumb"
+    class=${extra}
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :items=${[
+      { name: 'Home', link: '#' },
+      { name: 'Library', link: '#' },
+      { name: 'Data' },
+    ]}
+    :divider=${null}
+
+    /*
+      Bootstrap reads the separator from a CSS custom property, and
+      `:style-` writes ordinary CSS properties — so this one goes
+      through the plain `style` attribute.
+    */
+    style=${divider ? `--bs-breadcrumb-divider: '${divider}'` : null}
+  >
+    <ol class="breadcrumb mb-0">
+      <li class="breadcrumb-item"
+        :for-each=${items}
+        :for-as="item"
+        :class-active=${!item.link}
+        aria-current=${item.link ? null : 'page'}>
+        <a href=${item.link ?? null}>${item.name}</a>
+      </li>
+    </ol>
+  </:define>
+
+</lib>

package/parts/button.htm

@@ -0,0 +1,162 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    Bootstrap's button, as a real `<button>`.
+
+    `: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:
+
+      <bs-button :toggle="modal" :target="#signup">Sign up</bs-button>
+      <bs-button :dismiss="modal" :variant="secondary">Close</bs-button>
+
+    Note the two spellings of "conditional attribute" used throughout the kit:
+    a plain `name=${expr}` sets a VALUE and removes the attribute when the
+    expression is `null`, while `:attr-name=${expr}` toggles PRESENCE, which
+    is what `disabled` and friends need.
+  -->
+  <:define tag="bs-button:button"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :variant=${'primary'}
+    :outline=${false}
+    :size=${null}
+    :active=${false}
+    :disabled=${false}
+    :type=${'button'}
+    :toggle=${null}
+    :target=${null}
+    :dismiss=${null}
+
+    // private
+    :_class=${[
+      'btn',
+      variant ? `btn-${outline ? 'outline-' : ''}${variant}` : '',
+      size ? `btn-${size}` : '',
+      extra,
+    ].filter(s => s).join(' ')}
+
+    class=${_class}
+    type=${type}
+    :class-active=${active}
+    :attr-disabled=${disabled}
+    aria-pressed=${active ? 'true' : null}
+    data-bs-toggle=${toggle}
+    data-bs-target=${target}
+    data-bs-dismiss=${dismiss}
+  >
+    <:slot />
+  </:define>
+
+  <!---
+    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`.
+  -->
+  <:define tag="bs-link:a"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :href=${'#'}
+    :variant=${null}
+    :outline=${false}
+    :size=${null}
+    :active=${false}
+    :disabled=${false}
+    :button=${false}
+    :toggle=${null}
+    :target=${null}
+
+    // private
+    :_class=${[
+      button ? 'btn' : '',
+      button && variant ? `btn-${outline ? 'outline-' : ''}${variant}` : '',
+      button && size ? `btn-${size}` : '',
+      !button && variant ? `link-${variant}` : '',
+      extra,
+    ].filter(s => s).join(' ') || null}
+
+    class=${_class}
+    href=${href}
+    role=${button ? 'button' : null}
+    :class-active=${active}
+    :class-disabled=${disabled}
+    aria-disabled=${disabled ? 'true' : null}
+    data-bs-toggle=${toggle}
+    data-bs-target=${target}
+  >
+    <:slot />
+  </:define>
+
+  <!---
+    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.
+  -->
+  <:define tag="bs-button-group:div"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${'Button group'}
+    :size=${null}
+    :vertical=${false}
+
+    // private
+    :_class=${[
+      vertical ? 'btn-group-vertical' : 'btn-group',
+      size ? `btn-group-${size}` : '',
+      extra,
+    ].filter(s => s).join(' ')}
+
+    class=${_class}
+    role="group"
+    aria-label=${label}
+  >
+    <:slot />
+  </:define>
+
+  <!---
+    A toolbar of groups: Bootstrap spaces groups apart differently to the
+    buttons inside one, and this is the wrapper that says so.
+  -->
+  <:define tag="bs-button-toolbar:div"
+    class="btn-toolbar ${extra ?? ''}"
+    role="toolbar"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${'Toolbar'}
+    :gap=${2}
+
+    aria-label=${label}
+    :class-gap-1=${gap === 1}
+    :class-gap-2=${gap === 2}
+    :class-gap-3=${gap === 3}
+  >
+    <:slot />
+  </:define>
+
+  <!---
+    The dismiss "×". Nothing but `class="btn-close"`, but it carries an
+    accessible name and the dismissal target, both of which are easy to leave
+    off when writing it by hand.
+  -->
+  <:define tag="bs-close:button"
+    type="button"
+    class="btn-close ${extra ?? ''}"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${'Close'}
+    :dismiss=${null}
+    :disabled=${false}
+
+    aria-label=${label}
+    :attr-disabled=${disabled}
+    data-bs-dismiss=${dismiss}
+  />
+
+</lib>

package/parts/card.htm

@@ -0,0 +1,103 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    A card: parameters for the chrome, the slot for the content. Every region
+    other than the body is optional and only appears when its parameter is
+    given, which is the kit's general shape — a caller writes what the card
+    HAS, not the markup that produces it.
+
+      <bs-card :title="Card title" :footer="2 days ago">
+        <p class="card-text">Some quick example text.</p>
+      </bs-card>
+
+    The body is the one region a caller cannot reach with `:extra`, which
+    goes on the card itself -- hence `:bodyExtra`, for the padding Bootstrap
+    leaves to a utility class: `p-0` for a table or a code surface that runs
+    to the edges, `p-4` for a card that is mostly one paragraph.
+  -->
+  <:define tag="bs-card:div"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :bodyExtra=${null}  // extra classes for the body: `p-0`, `p-4`, `d-flex`
+    :title=${null}
+    :subtitle=${null}
+    :header=${null}
+    :footer=${null}
+    :image=${null}
+    :imageAlt=${''}
+    :imageBottom=${false}
+    :variant=${null}       // colours the whole card, e.g. 'primary'
+    :border=${null}        // colours only the border
+    :align=${null}         // 'center' | 'end'
+
+    // private
+    :_class=${[
+      'card',
+      variant ? `text-bg-${variant}` : '',
+      border ? `border-${border}` : '',
+      align ? `text-${align}` : '',
+      extra,
+    ].filter(s => s).join(' ')}
+
+    class=${_class}
+  >
+    <img class="card-img-top"
+      :if=${image && !imageBottom}
+      src=${image}
+      alt=${imageAlt}>
+
+    <!---
+      A named slot inside an optional region: the header appears only when
+      there is one, and a caller can put markup in it rather than a string.
+      Both halves had to be built for this: a `<:slot>` cannot sit inside a
+      `:for-each`, and filling one nested inside a component's own scope used
+      to leave the fallback's binding pointing at markup that was gone.
+    -->
+    <div class="card-header"
+      :if=${header}><:slot name="header">${header}</:slot></div>
+
+    <div class=${bodyExtra ? `card-body ${bodyExtra}` : 'card-body'}>
+      <h5 class="card-title"
+        :if=${title}>${title}</h5>
+
+      <h6 class="card-subtitle mb-2 text-body-secondary"
+        :if=${subtitle}>${subtitle}</h6>
+
+      <:slot />
+    </div>
+
+    <div class="card-footer text-body-secondary"
+      :if=${footer}>${footer}</div>
+
+    <img class="card-img-bottom"
+      :if=${image && imageBottom}
+      src=${image}
+      alt=${imageAlt}>
+  </:define>
+
+  <!---
+    Equal-height, equal-width cards in a grid. Bootstrap wants the row
+    classes on a wrapper; this is that wrapper, named.
+  -->
+  <:define tag="bs-card-group:div"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :cols=${3}
+    :gap=${4}
+    :attached=${false}     // a seamless strip instead of separate cards
+
+    // private
+    :_class=${attached
+      ? 'card-group'
+      : `row row-cols-1 row-cols-md-${cols} g-${gap}`}
+    :_groupClass=${extra ? `${_class} ${extra}` : _class}
+
+    class=${_groupClass}
+  >
+    <:slot />
+  </:define>
+
+</lib>

package/parts/carousel.htm

@@ -0,0 +1,87 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    A carousel from an array of slides. A slide is
+    `{ image, alt, title, text }`.
+
+    Controls and indicators both have to point at the carousel's id, which is
+    derived from `$id` — three places that have to agree, and the reason this
+    is worth a component at all.
+  -->
+  <:define tag="bs-carousel:div"
+    class="carousel slide ${extra ?? ''}"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :slides=${[]}
+    :controls=${true}
+    :indicators=${true}
+    :captions=${true}
+    :fade=${false}
+    :ride=${true}
+    :interval=${5000}
+    :dark=${false}
+
+    // private
+    :_id=${`bs-carousel-${$id}`}
+    :_selector=${`#bs-carousel-${$id}`}
+    /*
+      the position is needed three times per slide and `:for-each`
+      binds the item, not its index, so it is carried on the item
+    */
+    :_slides=${slides.map((slide, i) => ({ ...slide, index: i }))}
+
+    id=${_id}
+    :class-carousel-fade=${fade}
+    data-bs-ride=${ride ? 'carousel' : null}
+    data-bs-interval=${interval}
+    data-bs-theme=${dark ? 'dark' : null}
+  >
+    <div class="carousel-indicators" :if=${indicators}>
+      <button type="button"
+        :for-each=${_slides}
+        :for-as="slide"
+        data-bs-target=${_selector}
+        data-bs-slide-to=${slide.index}
+        :class-active=${slide.index === 0}
+        aria-current=${slide.index === 0 ? 'true' : null}
+        aria-label="Slide ${slide.index + 1}"></button>
+    </div>
+
+    <div class="carousel-inner">
+      <div class="carousel-item"
+        :for-each=${_slides}
+        :for-as="slide"
+        :class-active=${slide.index === 0}>
+        <img class="d-block w-100"
+          src=${slide.image}
+          alt=${slide.alt ?? ''}>
+        <div class="carousel-caption d-none d-md-block"
+          :if=${captions && (slide.title || slide.text)}>
+          <h5 :if=${slide.title}>${slide.title}</h5>
+          <p :if=${slide.text}>${slide.text}</p>
+        </div>
+      </div>
+    </div>
+
+    <button class="carousel-control-prev"
+      type="button"
+      :if=${controls}
+      data-bs-target=${_selector}
+      data-bs-slide="prev">
+      <span class="carousel-control-prev-icon" aria-hidden="true"></span>
+      <span class="visually-hidden">Previous</span>
+    </button>
+
+    <button class="carousel-control-next"
+      type="button"
+      :if=${controls}
+      data-bs-target=${_selector}
+      data-bs-slide="next">
+      <span class="carousel-control-next-icon" aria-hidden="true"></span>
+      <span class="visually-hidden">Next</span>
+    </button>
+  </:define>
+
+</lib>

package/parts/check.htm

@@ -0,0 +1,164 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    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.
+
+    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"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${null}
+    :type=${'checkbox'}   // 'checkbox' | 'radio' | 'switch'
+    :name=${null}
+    :value=${null}
+    :checked=${false}
+    :inline=${false}
+    :reverse=${false}
+    :disabled=${false}
+    :help=${null}
+
+    // private
+    :_id=${`bs-check-${$id}`}
+    :_helpId=${`bs-check-help-${$id}`}
+    :_type=${type === 'switch' ? 'checkbox' : type}
+
+    class="form-check ${extra ?? ''}"
+    :class-form-switch=${type === 'switch'}
+    :class-form-check-inline=${inline}
+    :class-form-check-reverse=${reverse}
+  >
+    <input class="form-check-input"
+      id=${_id}
+      type=${_type}
+      name=${name}
+      value=${value}
+      role=${type === 'switch' ? 'switch' : null}
+      aria-describedby=${help ? _helpId : null}
+      :attr-checked=${checked}
+      :attr-disabled=${disabled}
+      :on-change=${ev => checked = ev.target.checked}>
+
+    <label class="form-check-label"
+      for=${_id}>${label}</label>
+
+    <div class="form-text"
+      id=${_helpId}
+      :if=${help}>${help}</div>
+  </:define>
+
+  <!---
+    A whole group of radios or checkboxes from one array, sharing a name and
+    reporting the selection back through `:value`. Entries are strings or
+    `{ name, value, disabled }`, as in `bs-select`.
+  -->
+  <:define tag="bs-check-group:div"
+    class="mb-3 ${extra ?? ''}"
+    role="group"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :legend=${null}
+    :type=${'radio'}
+    :options=${[]}
+    :value=${null}
+    :inline=${false}
+    :disabled=${false}
+
+    // private
+    :_name=${`bs-check-group-${$id}`}
+    :_legendId=${`bs-check-group-legend-${$id}`}
+
+    aria-labelledby=${legend ? _legendId : null}
+    :_options=${options.map(o =>
+      typeof o === 'object' && o !== null
+        ? { name: o.name, value: o.value ?? o.name, disabled: !!o.disabled }
+        : { name: o, value: o, disabled: false })}
+  >
+    <!---
+      A `<div>` rather than `<fieldset>`/`<legend>`: Bootstrap floats a
+      legend, and a floated check input beside it wraps up onto the same
+      line. `role="group"` plus `aria-labelledby` says the same thing to a
+      screen reader without the float.
+    -->
+    <div class="form-label fs-6"
+      id=${_legendId}
+      :if=${legend}>${legend}</div>
+
+    <div class="form-check"
+      :for-each=${_options}
+      :for-as="option"
+      :class-form-switch=${type === 'switch'}
+      :class-form-check-inline=${inline}>
+      <input class="form-check-input"
+        id="${_name}-${option.value}"
+        type=${type === 'switch' ? 'checkbox' : type}
+        name=${_name}
+        value=${option.value}
+        :attr-checked=${option.value === value}
+        :attr-disabled=${disabled || option.disabled}
+        :on-change=${ev => value = ev.target.value}>
+      <label class="form-check-label"
+        for="${_name}-${option.value}">${option.name}</label>
+    </div>
+  </:define>
+
+  <!--- A range slider, with its label and its current value. -->
+  <:define tag="bs-range:div"
+    class="mb-3 ${extra ?? ''}"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${null}
+    :name=${null}
+    :min=${0}
+    :max=${100}
+    :step=${1}
+    :value=${50}
+    :disabled=${false}
+    :showValue=${false}
+
+    // private
+    :_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
+      label.
+
+      A row rather than a `<label>` wrapping both, so the readout stays out
+      of the accessible name -- a label whose text is "50" is worse than no
+      label, and the range input announces its own value anyway. The
+      readout keeps its place at the right when it is the only thing here --
+      by swapping the justification rather than adding to it, since
+      Bootstrap emits `justify-content-end` before `justify-content-between`
+      and the two together leave `between` winning.
+    -->
+    <div class="form-label d-flex"
+      :class-justify-content-between=${label}
+      :class-justify-content-end=${!label}
+      :if=${label || showValue}>
+      <label for=${_id}
+        :if=${label}>${label}</label>
+      <span class="text-body-secondary"
+        :if=${showValue}>${value}</span>
+    </div>
+
+    <input class="form-range"
+      id=${_id}
+      type="range"
+      name=${name}
+      min=${min}
+      max=${max}
+      step=${step}
+      value=${value}
+      :attr-disabled=${disabled}
+      :on-input=${ev => value = Number(ev.target.value)}>
+  </:define>
+
+</lib>

package/parts/collapse.htm

@@ -0,0 +1,31 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    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:
+
+      <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
+    needs the content to have a width of its own.
+  -->
+  <:define tag="bs-collapse:div"
+    class="collapse ${extra ?? ''}"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :name=${null}
+    :open=${false}
+    :horizontal=${false}
+
+    id=${name}
+    :class-show=${open}
+    :class-collapse-horizontal=${horizontal}
+  >
+    <:slot />
+  </:define>
+
+</lib>

package/parts/dropdown.htm

@@ -0,0 +1,86 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    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.
+
+    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
+    answer in this kit to "this widget needs an id": derive it, never ask the
+    caller for one, unless another component has to name it (see
+    `bs-accordion`).
+  -->
+  <:define tag="bs-dropdown:div"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${'Dropdown'}
+    :items=${[
+      { name: 'Action', link: '#' },
+      { name: 'Another action', link: '#' },
+      { divider: true },
+      { name: 'Something else here', link: '#' },
+    ]}
+    :variant=${'primary'}
+    :outline=${false}
+    :size=${null}
+    :split=${false}
+    :direction=${'down'}   // 'down' | 'up' | 'start' | 'end'
+    :align=${'start'}      // 'start' | 'end'
+    :dark=${false}
+
+    // private
+    :_id=${`bs-dropdown-${$id}`}
+    :_class=${[direction === 'down' ? 'dropdown' : `drop${direction}`, extra]
+              .filter(s => s).join(' ')}
+    :_btnClass=${[
+      'btn',
+      `btn-${outline ? 'outline-' : ''}${variant}`,
+      size ? `btn-${size}` : '',
+    ].filter(s => s).join(' ')}
+
+    class=${_class}
+    :class-btn-group=${split}
+  >
+    <!--- a split button keeps the label clickable on its own -->
+    <button type="button"
+      class=${_btnClass}
+      :if=${split}>${label}</button>
+
+    <button type="button"
+      id=${_id}
+      class=${_btnClass}
+      :class-dropdown-toggle
+      :class-dropdown-toggle-split=${split}
+      data-bs-toggle="dropdown"
+      aria-expanded="false">
+      <span :if=${!split}>${label}</span>
+      <span class="visually-hidden"
+        :else>Toggle dropdown</span>
+    </button>
+
+    <ul class="dropdown-menu"
+      :class-dropdown-menu-end=${align === 'end'}
+      data-bs-theme=${dark ? 'dark' : null}
+      aria-labelledby=${_id}>
+      <li :for-each=${items} :for-as="item">
+        <hr class="dropdown-divider"
+          :if=${item.divider}>
+
+        <h6 class="dropdown-header"
+          :else-if=${item.header}>${item.header}</h6>
+
+        <a class="dropdown-item"
+          :else
+          :class-active=${item.active}
+          :class-disabled=${item.disabled}
+          href=${item.link ?? null}
+          aria-current=${item.active ? 'true' : null}
+          :on-click=${() => item.select?.(item)}>${item.name}</a>
+      </li>
+    </ul>
+  </:define>
+
+</lib>