@markout-lang/bootstrap-kit 0.2.0

package/parts/image.htm

@@ -0,0 +1,46 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    An image that behaves: responsive by default, and with `alt` a parameter
+    that is always written rather than an attribute that is often forgotten.
+  -->
+  <:define tag="bs-image:img"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :src=${null}
+    :alt=${''}
+    :fluid=${true}
+    :thumbnail=${false}
+    :rounded=${false}
+
+    class=${extra}
+    src=${src}
+    alt=${alt}
+    :class-img-fluid=${fluid}
+    :class-img-thumbnail=${thumbnail}
+    :class-rounded=${rounded}
+  />
+
+  <!--- An image with its caption, as one thing. -->
+  <:define tag="bs-figure:figure"
+    class="figure ${extra ?? ''}"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :src=${null}
+    :alt=${''}
+    :caption=${null}
+    :align=${null}      // 'center' | 'end'
+  >
+    <img class="figure-img img-fluid rounded"
+      src=${src}
+      alt=${alt}>
+    <figcaption class="figure-caption"
+      :class-text-center=${align === 'center'}
+      :class-text-end=${align === 'end'}
+      :if=${caption}>${caption}</figcaption>
+  </:define>
+
+</lib>

package/parts/input.htm

@@ -0,0 +1,178 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    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
+    typed, so a page can name the instance and read it from anywhere else on
+    the page —
+
+      <bs-input :aka="email" :label="Email" :type="email" />
+      <bs-button :disabled=${!email.value}>Send</bs-button>
+
+    — which is `:aka` doing what it does everywhere else, not a mechanism
+    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.
+
+    Floating labels are the same control with the label after the input
+    instead of before it — Bootstrap's CSS keys off that order — so the two
+    layouts are two regions rather than one with a class toggled on it.
+  -->
+  <:define tag="bs-input:div"
+    class="mb-3 ${extra ?? ''}"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${null}
+    :type=${'text'}
+    :name=${null}
+    :value=${''}
+    :placeholder=${''}
+    :help=${null}
+    :size=${null}            // 'sm' | 'lg'
+    :disabled=${false}
+    :readonly=${false}
+    :required=${false}
+    :floating=${false}
+    :check=${(v) => true}
+    :message=${'Please check this value.'}
+
+    // private
+    :_id=${`bs-input-${$id}`}
+    :_helpId=${`bs-input-help-${$id}`}
+    :_empty=${value === '' || value == null}
+    :_invalid=${_empty ? required : !check(value)}
+    :_class=${['form-control', size ? `form-control-${size}` : '']
+              .filter(s => s).join(' ')}
+  >
+    <!--- plain layout: label, control, feedback -->
+    <div :if=${!floating}>
+      <label class="form-label"
+        for=${_id}
+        :if=${label}>${label}</label>
+
+      <input class=${_class}
+        id=${_id}
+        type=${type}
+        name=${name}
+        value=${value}
+        placeholder=${placeholder}
+        aria-describedby=${help ? _helpId : null}
+        :class-is-invalid=${_invalid}
+        :attr-disabled=${disabled}
+        :attr-readonly=${readonly}
+        :attr-required=${required}
+        :on-input=${ev => value = ev.target.value}>
+
+      <div class="form-text"
+        id=${_helpId}
+        :if=${help}>${help}</div>
+
+      <div class="invalid-feedback">${message}</div>
+    </div>
+
+    <!--- floating layout: control, then label -->
+    <div class="form-floating" :else>
+      <input class=${_class}
+        id=${_id}
+        type=${type}
+        name=${name}
+        value=${value}
+        placeholder=${placeholder || label || ' '}
+        :class-is-invalid=${_invalid}
+        :attr-disabled=${disabled}
+        :attr-readonly=${readonly}
+        :attr-required=${required}
+        :on-input=${ev => value = ev.target.value}>
+
+      <label for=${_id}>${label}</label>
+
+      <div class="invalid-feedback">${message}</div>
+    </div>
+  </:define>
+
+  <!---
+    The same shape for multi-line text. Kept separate rather than folded into
+    `bs-input` as `type="textarea"`: it is a different element with its own
+    `rows`, and a type that isn't one of HTML's would be a small lie.
+  -->
+  <:define tag="bs-textarea:div"
+    class="mb-3 ${extra ?? ''}"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :label=${null}
+    :name=${null}
+    :value=${''}
+    :placeholder=${''}
+    :rows=${3}
+    :help=${null}
+    :disabled=${false}
+    :readonly=${false}
+    :required=${false}
+    :check=${(v) => true}
+    :message=${'Please check this value.'}
+
+    // private
+    :_id=${`bs-textarea-${$id}`}
+    :_helpId=${`bs-textarea-help-${$id}`}
+    :_empty=${value === '' || value == null}
+    :_invalid=${_empty ? required : !check(value)}
+  >
+    <label class="form-label"
+      for=${_id}
+      :if=${label}>${label}</label>
+
+    <textarea class="form-control"
+      id=${_id}
+      name=${name}
+      rows=${rows}
+      placeholder=${placeholder}
+      aria-describedby=${help ? _helpId : null}
+      :class-is-invalid=${_invalid}
+      :attr-disabled=${disabled}
+      :attr-readonly=${readonly}
+      :attr-required=${required}
+      :on-input=${ev => value = ev.target.value}>${value}</textarea>
+
+    <div class="form-text"
+      id=${_helpId}
+      :if=${help}>${help}</div>
+
+    <div class="invalid-feedback">${message}</div>
+  </: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
+    ordinary `.input-group-text` markup.
+  -->
+  <:define tag="bs-input-group:div"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :prefix=${null}
+    :suffix=${null}
+    :size=${null}
+
+    // private
+    :_class=${['input-group', size ? `input-group-${size}` : '', extra]
+              .filter(s => s).join(' ')}
+
+    class=${_class}
+  >
+    <span class="input-group-text"
+      :if=${prefix}>${prefix}</span>
+
+    <:slot />
+
+    <span class="input-group-text"
+      :if=${suffix}>${suffix}</span>
+  </:define>
+
+</lib>

package/parts/list-group.htm

@@ -0,0 +1,58 @@
+<lib>
+  <:import src="base.htm" />
+  <:import src="badge.htm" />
+
+  <!---
+    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.
+  -->
+  <:define tag="bs-list-group:div"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :items=${[
+      { name: 'An item', active: true },
+      { name: 'A second item' },
+      { name: 'A disabled item', disabled: true },
+    ]}
+    :flush=${false}
+    :horizontal=${false}
+
+    // private
+    :_class=${[
+      'list-group',
+      flush ? 'list-group-flush' : '',
+      horizontal ? 'list-group-horizontal' : '',
+      extra,
+    ].filter(s => s).join(' ')}
+
+    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>
+  </:define>
+
+</lib>

package/parts/modal.htm

@@ -0,0 +1,119 @@
+<lib>
+  <:import src="base.htm" />
+  <:import src="button.htm" />
+
+  <!---
+    A modal. Opened the Bootstrap way, by a trigger naming it:
+
+      <bs-button :toggle="modal" :target="#signup">Sign up</bs-button>
+      <bs-modal :name="signup" :title="Sign up">…</bs-modal>
+
+    The footer is a named slot with a working default, so a modal that only
+    needs a Close button doesn't have to say so. That is also why it isn't an
+    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
+    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.
+  -->
+  <:define tag="bs-modal:div"
+    class="modal fade ${extra ?? ''}"
+    tabindex="-1"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :name=${null}
+    :title=${''}
+    :size=${null}          // 'sm' | 'lg' | 'xl'
+    :centered=${false}
+    :scrollable=${false}
+    :fullscreen=${null}    // true | 'sm-down' | 'md-down' | ...
+    :staticBackdrop=${false}
+    :open=${false}
+
+    // private
+    :_labelId=${`bs-modal-title-${$id}`}
+    :_dialogClass=${[
+      'modal-dialog',
+      size ? `modal-${size}` : '',
+      centered ? 'modal-dialog-centered' : '',
+      scrollable ? 'modal-dialog-scrollable' : '',
+      fullscreen === true ? 'modal-fullscreen' : '',
+      typeof fullscreen === 'string' ? `modal-fullscreen-${fullscreen}` : '',
+    ].filter(s => s).join(' ')}
+
+    id=${name}
+    aria-labelledby=${_labelId}
+    aria-hidden="true"
+    data-bs-backdrop=${staticBackdrop ? 'static' : null}
+    data-bs-keyboard=${staticBackdrop ? 'false' : null}
+
+    /*
+      `globalThis` rather than a bare `bootstrap`: the standard
+      library is on the scope chain, a page's own libraries are not,
+      and going through `globalThis` is what keeps "this line needs a
+      browser" visible in the line
+    */
+    :handle-open=${(v) => {
+      // only while this markup is in the page: an `:if`/`:for-data` region
+      // can take it out with `open` still true, and Bootstrap asked
+      // to show a detached element walks into its own internals
+      if (!$dom.isConnected) return;
+      const modal = globalThis.bootstrap.Modal.getOrCreateInstance($dom);
+      v ? modal.show() : modal.hide();
+    }}
+    /*
+      Bootstrap's plugins own DOM outside this element -- a backdrop,
+      a popper, a body class -- so an element removed without a
+      dispose() leaves it behind. `:will-detach` rather than
+      `:will-dispose`: an `:if`/`:for-data` region takes its markup out of
+      the page without its scope going anywhere, and the leak is the
+      same either way
+      Bootstrap's plugins own DOM and page state outside this
+      element -- a backdrop, a scroll lock on <body> -- and
+      `dispose()` releases the plugin without undoing any of it for
+      one that is still open. So the element is put back the way it
+      was found, which is what a page removing an open modal
+      would otherwise be left needing to do by hand.
+
+      `:will-detach` rather than `:will-dispose`: an `:if`/`:for-data`
+      region takes its markup out of the page without its scope going
+      anywhere, and the leak is identical either way
+    */
+    :will-detach=${() => {
+      const doc = globalThis.document;
+      globalThis.bootstrap.Modal.getInstance($dom)?.dispose();
+      $dom.style.display = '';
+      $dom.classList.remove('show');
+      // only once nothing else is holding the page open
+      if (doc.querySelector('.modal.show')) return;
+      doc.body.classList.remove('modal-open');
+      doc.body.style.overflow = '';
+      doc.body.style.paddingRight = '';
+    }}
+    :on-hidden.bs.modal=${() => open = false}
+    :on-shown.bs.modal=${() => open = true}
+  >
+    <div class=${_dialogClass}>
+      <div class="modal-content">
+        <div class="modal-header">
+          <h1 class="modal-title fs-5" id=${_labelId}>${title}</h1>
+          <bs-close :dismiss="modal" />
+        </div>
+
+        <div class="modal-body">
+          <:slot />
+        </div>
+
+        <div class="modal-footer">
+          <:slot name="footer">
+            <bs-button :variant="secondary" :dismiss="modal">Close</bs-button>
+          </:slot>
+        </div>
+      </div>
+    </div>
+  </:define>
+
+</lib>

package/parts/nav.htm

@@ -0,0 +1,89 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    Navs, pills, tabs and underline are one component in Bootstrap and one
+    here too: they differ by a class, not by structure.
+
+    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.
+  -->
+  <:define tag="bs-nav:ul"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :items=${[
+      { name: 'Active', link: '#', active: true },
+      { name: 'Link', link: '#' },
+      { name: 'Disabled', link: '#', disabled: true },
+    ]}
+    :variant=${null}      // 'tabs' | 'pills' | 'underline'
+    :fill=${false}
+    :justified=${false}
+    :vertical=${false}
+    :align=${'start'}     // 'start' | 'center' | 'end'
+    :toggle=${null}       // 'tab' | 'pill' — for tabbed panes
+
+    // private
+    :_class=${[
+      'nav',
+      variant ? `nav-${variant}` : '',
+      fill ? 'nav-fill' : '',
+      justified ? 'nav-justified' : '',
+      vertical ? 'flex-column' : '',
+      align === 'center' ? 'justify-content-center' : '',
+      align === 'end' ? 'justify-content-end' : '',
+      extra,
+    ].filter(s => s).join(' ')}
+
+    class=${_class}
+    role=${toggle ? 'tablist' : null}
+  >
+    <li class="nav-item"
+      :for-each=${items}
+      :for-as="item"
+      role=${toggle ? 'presentation' : null}>
+      <button class="nav-link"
+        type="button"
+        :if=${toggle}
+        :class-active=${item.active}
+        :attr-disabled=${item.disabled}
+        data-bs-toggle=${toggle}
+        data-bs-target=${item.target}
+        role="tab"
+        aria-selected=${item.active ? 'true' : 'false'}>${item.name}</button>
+
+      <a class="nav-link"
+        :else
+        :class-active=${item.active}
+        :class-disabled=${item.disabled}
+        href=${item.link ?? null}
+        aria-current=${item.active ? 'page' : null}
+        aria-disabled=${item.disabled ? 'true' : null}>${item.name}</a>
+    </li>
+  </:define>
+
+  <!--- The panes a `:toggle`-ing `bs-nav` switches between. -->
+  <:define tag="bs-tab-content:div" class="tab-content">
+    <:slot />
+  </:define>
+
+  <:define tag="bs-tab-pane:div"
+    class="tab-pane fade ${extra ?? ''}"
+    role="tabpanel"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :name=${null}
+    :active=${false}
+
+    id=${name}
+    :class-show=${active}
+    :class-active=${active}
+    tabindex="0"
+  >
+    <:slot />
+  </:define>
+
+</lib>

package/parts/navbar.htm

@@ -0,0 +1,82 @@
+<lib>
+  <:import src="base.htm" />
+
+  <!---
+    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
+    something from the Bootstrap docs — see the default below for its shape;
+    `button: true` turns an entry into a call to action.
+
+    The collapse target needs an id that no other navbar on the page shares,
+    and `$id` is exactly that: unique per instance, so two navbars can't
+    collide and the caller never has to invent a name.
+
+    Two named slots: the unnamed one is the brand, `end` is whatever should
+    sit past the links — a search box, a theme toggle, an avatar.
+  -->
+  <:define tag="bs-navbar:nav"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :items=${[
+      { name: 'Home', link: '#', active: true },
+      { name: 'Features', link: '#' },
+      { name: 'Pricing', link: '#' },
+    ]}
+    :brand=${'#'}
+    :expand=${'lg'}
+    :container=${'container'}   // 'container' | 'container-fluid' | ...
+    :sticky=${false}
+    :fixed=${false}
+    :theme=${null}              // 'light' | 'dark' — independent of the page
+    :bg=${'body-tertiary'}
+
+    // private
+    :_id=${`bs-navbar-${$id}`}
+    :_class=${[
+      'navbar',
+      expand ? `navbar-expand-${expand}` : '',
+      bg ? `bg-${bg}` : '',
+      extra,
+    ].filter(s => s).join(' ')}
+
+    class=${_class}
+    :class-sticky-top=${sticky}
+    :class-fixed-top=${fixed}
+    data-bs-theme=${theme}
+  >
+    <div class=${container}>
+      <a class="navbar-brand" href=${brand}><:slot /></a>
+
+      <button class="navbar-toggler"
+        type="button"
+        data-bs-toggle="collapse"
+        data-bs-target="#${_id}"
+        aria-controls=${_id}
+        aria-expanded="false"
+        aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+      </button>
+
+      <div class="collapse navbar-collapse" id=${_id}>
+        <ul class="navbar-nav me-auto mb-2 mb-lg-0">
+          <li class="nav-item" :for-each=${items} :for-as="item">
+            <a class="nav-link"
+              :class-active=${item.active}
+              :class-disabled=${item.disabled}
+              :class-btn=${item.button}
+              :class-btn-primary=${item.button}
+              href=${item.link ?? null}
+              aria-current=${item.active ? 'page' : null}
+              aria-disabled=${item.disabled ? 'true' : null}>${item.name}</a>
+          </li>
+        </ul>
+
+        <div class="d-flex gap-2 align-items-center">
+          <:slot name="end" />
+        </div>
+      </div>
+    </div>
+  </:define>
+
+</lib>

package/parts/offcanvas.htm

@@ -0,0 +1,90 @@
+<lib>
+  <:import src="base.htm" />
+  <:import src="button.htm" />
+
+  <!---
+    An offcanvas panel: the same shape as `bs-modal`, opened by a trigger
+    naming it or by the `:open` value.
+
+      <bs-button :toggle="offcanvas" :target="#menu">Menu</bs-button>
+      <bs-offcanvas :name="menu" :title="Menu">…</bs-offcanvas>
+  -->
+  <:define tag="bs-offcanvas:div"
+    class="offcanvas"
+    tabindex="-1"
+
+    // parameters
+    :extra=${null}      // extra classes for this instance
+    :name=${null}
+    :title=${''}
+    :placement=${'start'}   // 'start' | 'end' | 'top' | 'bottom'
+    :backdrop=${true}
+    :scroll=${false}
+    :responsive=${null}     // 'lg' — an offcanvas below this breakpoint only
+    :open=${false}
+
+    // private
+    :_labelId=${`bs-offcanvas-title-${$id}`}
+    :_class=${[
+      responsive ? `offcanvas-${responsive}` : 'offcanvas',
+      `offcanvas-${placement}`,
+      extra,
+    ].join(' ')}
+
+    class=${_class}
+    id=${name}
+    aria-labelledby=${_labelId}
+    data-bs-backdrop=${backdrop ? null : 'false'}
+    data-bs-scroll=${scroll ? 'true' : null}
+
+    :handle-open=${(v) => {
+      // only while this markup is in the page: an `:if`/`:for-data` region
+      // can take it out with `open` still true, and Bootstrap asked
+      // to show a detached element walks into its own internals
+      if (!$dom.isConnected) return;
+      const panel = globalThis.bootstrap.Offcanvas.getOrCreateInstance($dom);
+      v ? panel.show() : panel.hide();
+    }}
+    /*
+      Bootstrap's plugins own DOM outside this element -- a backdrop,
+      a popper, a body class -- so an element removed without a
+      dispose() leaves it behind. `:will-detach` rather than
+      `:will-dispose`: an `:if`/`:for-data` region takes its markup out of
+      the page without its scope going anywhere, and the leak is the
+      same either way
+      Bootstrap's plugins own DOM and page state outside this
+      element -- a backdrop, a scroll lock on <body> -- and
+      `dispose()` releases the plugin without undoing any of it for
+      one that is still open. So the element is put back the way it
+      was found, which is what a page removing an open offcanvas
+      would otherwise be left needing to do by hand.
+
+      `:will-detach` rather than `:will-dispose`: an `:if`/`:for-data`
+      region takes its markup out of the page without its scope going
+      anywhere, and the leak is identical either way
+    */
+    :will-detach=${() => {
+      const doc = globalThis.document;
+      globalThis.bootstrap.Offcanvas.getInstance($dom)?.dispose();
+      $dom.style.display = '';
+      $dom.classList.remove('show');
+      // only once nothing else is holding the page open
+      if (doc.querySelector('.offcanvas.show')) return;
+      doc.body.classList.remove('offcanvas-open');
+      doc.body.style.overflow = '';
+      doc.body.style.paddingRight = '';
+    }}
+    :on-hidden.bs.offcanvas=${() => open = false}
+    :on-shown.bs.offcanvas=${() => open = true}
+  >
+    <div class="offcanvas-header">
+      <h5 class="offcanvas-title" id=${_labelId}>${title}</h5>
+      <bs-close :dismiss="offcanvas" />
+    </div>
+
+    <div class="offcanvas-body">
+      <:slot />
+    </div>
+  </:define>
+
+</lib>