@markout-lang/bootstrap-kit 0.3.0 → 0.4.1

package/README.md

@@ -24,8 +24,15 @@ logical root it declares. See [npm kits](../../docs/design/npm-kits.md) —
 including the other case, a kit vendored into a docroot, which is imported by
 its path instead.
 
-`all.htm` pulls in everything. Each part imports `base.htm` itself and a file
-is only imported once per page, so importing parts by hand never leaves
+`all.htm` pulls in everything, and that is the ordinary thing to import: a
+component no tag on the page uses is dropped before the page is served, so
+what the whole kit costs is what you actually reach for. A page importing all
+of it and using one `bs-alert` serves 4.7KB where the same page with that
+pass turned off is 19.8KB.
+
+Importing parts by hand is for when you want to be explicit rather than to
+save weight — it is worth 134 bytes on that page. Each part imports
+`base.htm` itself and a file is only imported once, so it never leaves
 Bootstrap out:
 
 ```html
@@ -33,6 +40,20 @@ Bootstrap out:
 <:import src="/npm/@markout-lang/bootstrap-kit/parts/card.htm" />
 ```
 
+Those 134 bytes are the pass being careful rather than a component sneaking
+through, and they are two stencils: `bs-alert` names `<bs-close>` in its
+body, `bs-close` lives in `button.htm`, and so `bs-button` and `bs-badge`
+count as used. A tag named inside another definition's body is kept even
+when that definition is itself dropped — narrowing that needs the usage
+graph rather than a flat set, and getting it wrong deletes markup a page
+needs.
+
+Both pages there do the same things, which is what makes the comparison mean
+anything. `theme.htm` used to be the exception: importing `all.htm` brought a
+pre-paint script the hand-picked page never got, so the whole-kit page was
+278 bytes larger for doing something more. Colour modes are opt-in now, so
+that difference belongs to whichever page asks for them.
+
 Every component below is shown one after another in the [kitchen
 sink](https://markout.dev/demos/kitchen-sink), and
 [Orbit](https://markout.dev/demos/orbit) is an operations dashboard built out
@@ -65,15 +86,22 @@ all of them.
 **Parameters for the chrome, the slot for the content.** What a card *has* —
 a title, a footer, an image — is a parameter. What it *contains* is slotted.
 
-**`::extra` adds classes.** A `class` written at a usage site *replaces* the
+**`class+=` adds classes.** A `class` written at a usage site *replaces* the
 one a definition sets, which is the language's rule and not something this
-kit overrides. So every component takes `::extra` for the utility classes a
-caller wants on top:
+kit overrides — and since every component here computes its own, writing one
+gets you a warning naming `class+=`. That is the spelling to reach for:
 
 ```html
-<bs-alert ::variant="warning" ::extra="mb-0">Careful</bs-alert>
+<bs-alert ::variant="warning" class+="mb-0">Careful</bs-alert>
+<bs-alert ::dismissible class-="fade">No animation, please</bs-alert>
 ```
 
+Every component used to declare an `::extra` parameter for this, hand-rolled
+into its own class list — 28 files agreeing on a convention the language now
+has a spelling for. `::bodyExtra` on `bs-card` stays, and says why the rest
+went: `class+=` reaches a component's own element, and the card's *body* is a
+different element.
+
 **Comments in a tag: `//` for one line, `/* … */` for more.** Both are
 stripped at parse time. A run of `//` lines reads as a stack of fragments;
 one block says it once.
@@ -215,13 +243,21 @@ variables, so restyling everything is setting one value at the import site:
 | `bsFontSans` | Bootstrap's system stack |
 | `bsLinkDecoration` | `underline` |
 
-Colour modes are `theme.htm`: an inline pre-paint script so the page never
-flashes the wrong mode, and `<bs-theme-toggle />` to switch it.
+Colour modes are `theme.htm`, and they are opt-in: write `<bs-theme-auto />`
+for the behaviour on its own — the page follows a stored choice, or the
+system — or a `<bs-theme-toggle />` for the behaviour and a button to drive
+it. Either keeps the inline pre-paint script that stops the page flashing the
+wrong mode; a page that writes neither ships neither, even having imported
+the whole kit.
+
+That is `:when-used` doing what it is for. Before it, importing `all.htm`
+gave every page colour modes whether it had asked or not, which is the one
+thing in this kit that DID something merely because a file was imported.
 
 ## Components
 
-Every tag also takes `::extra`. Defaults are in the definitions, which are
-commented.
+Every tag takes `class+=` and `class-=`, which are the language's and not
+listed here. Defaults are in the definitions, which are commented.
 
 ### Content
 
@@ -239,13 +275,29 @@ commented.
 | `bs-textarea` | `label` `name` `value` `placeholder` `rows` `help` `disabled` `readonly` `required` `check` `message` |
 | `bs-select` | `label` `name` `options` `value` `placeholder` `help` `size` `multiple` `disabled` `required` `floating` |
 | `bs-check` | `label` `type` (`checkbox`/`radio`/`switch`) `name` `value` `checked` `inline` `reverse` `disabled` `help` |
-| `bs-check-group` | `legend` `type` `options` `value` `inline` `disabled` |
+| `bs-check-group` | `legend` `type` `options` `value` (see below) `inline` `disabled` |
 | `bs-range` | `label` `name` `min` `max` `step` `value` `disabled` `showValue` |
 | `bs-input-group` | `prefix` `suffix` `size` |
 
 `bs-input` and `bs-textarea` also answer `valid`, which is read rather than
 passed -- see *Values are read and written* above.
 
+**`bs-check-group`'s `::value` is decided by its `::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 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:
+
+```html
+<bs-check-group :aka="channels"
+  ::type="checkbox"
+  ::value=${['Slack']}
+  ::options=${['Email', 'Slack', 'SMS']} />
+
+Deliver to ${channels.value.join(', ')}
+```
+
 ### Components
 
 | Tag | Parameters |
@@ -278,6 +330,7 @@ passed -- see *Values are read and written* above.
 | `bs-progress-stacked` | — |
 | `bs-scrollspy` | `target` `offset` `smooth` `height` |
 | `bs-spinner` | `variant` `type` `small` `label` |
+| `bs-theme-auto` | — (declares that the page uses colour modes) |
 | `bs-theme-toggle` | `variant` `outline` `size` |
 | `bs-toast` | `title` `time` `variant` `open` `autohide` `delay` |
 | `bs-toast-container` | `placement` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markout-lang/bootstrap-kit",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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",
@@ -12,7 +12,7 @@
   },
   "homepage": "https://markout.dev",
   "peerDependencies": {
-    "@markout-lang/core": "^0.5.0"
+    "@markout-lang/core": ">=0.5.0 <1.0.0"
   },
   "markout": {
     "root": "/bootstrap-kit"

package/parts/accordion.htm

@@ -25,10 +25,9 @@
     collide and nothing has to be named.
   -->
   <:define tag="bs-accordion:div"
-    class="accordion ${extra ?? ''}"
+    class="accordion"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::exclusive=${true}  // one open panel at a time
     ::flush=${false}
 
@@ -45,10 +44,9 @@
   </:define>
 
   <:define tag="bs-accordion-item:div"
-    class="accordion-item ${extra ?? ''}"
+    class="accordion-item"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::title=${''}
     ::open=${false}
 

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
@@ -22,13 +22,12 @@
     role="alert"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::variant=${'primary'}
     ::heading=${null}
     ::dismissible=${false}
 
     // private
-    :_class=${['alert', `alert-${variant}`, extra].filter(s => s).join(' ')}
+    :_class=${`alert alert-${variant}`}
 
     class=${_class}
     :class-alert-dismissible=${dismissible}

package/parts/badge.htm

@@ -9,7 +9,6 @@
   <:define tag="bs-badge:span"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::variant=${'primary'}
     ::pill=${false}
     ::position=${null}    // 'top-end' | 'bottom-end' — for a badge on a button
@@ -22,12 +21,9 @@
       position ? 'position-absolute translate-middle' : '',
       position === 'top-end' ? 'top-0 start-100' : '',
       position === 'bottom-end' ? 'top-100 start-100' : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}
-  >
-    <:slot />
-  </:define>
+  ><:slot /></:define>
 
 </lib>

package/parts/breadcrumb.htm

@@ -12,10 +12,8 @@
   -->
   <: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: '#' },

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:
@@ -20,7 +20,6 @@
   <:define tag="bs-button:button"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::variant=${'primary'}
     ::outline=${false}
     ::size=${null}
@@ -36,7 +35,6 @@
       'btn',
       variant ? `btn-${outline ? 'outline-' : ''}${variant}` : '',
       size ? `btn-${size}` : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}
@@ -53,13 +51,12 @@
 
   <!---
     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"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::href=${'#'}
     ::variant=${null}
     ::outline=${false}
@@ -76,7 +73,6 @@
       button && variant ? `btn-${outline ? 'outline-' : ''}${variant}` : '',
       button && size ? `btn-${size}` : '',
       !button && variant ? `link-${variant}` : '',
-      extra,
     ].filter(s => s).join(' ') || null}
 
     class=${_class}
@@ -87,19 +83,16 @@
     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.
   -->
   <:define tag="bs-button-group:div"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${'Button group'}
     ::size=${null}
     ::vertical=${false}
@@ -108,7 +101,6 @@
     :_class=${[
       vertical ? 'btn-group-vertical' : 'btn-group',
       size ? `btn-group-${size}` : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}
@@ -123,11 +115,10 @@
     buttons inside one, and this is the wrapper that says so.
   -->
   <:define tag="bs-button-toolbar:div"
-    class="btn-toolbar ${extra ?? ''}"
+    class="btn-toolbar"
     role="toolbar"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${'Toolbar'}
     ::gap=${2}
 
@@ -146,10 +137,9 @@
   -->
   <:define tag="bs-close:button"
     type="button"
-    class="btn-close ${extra ?? ''}"
+    class="btn-close"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${'Close'}
     ::dismiss=${null}
     ::disabled=${false}

package/parts/card.htm

@@ -11,15 +11,14 @@
         <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
+    The body is the one region a caller cannot reach with `class+=`, 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}
@@ -38,7 +37,6 @@
       variant ? `text-bg-${variant}` : '',
       border ? `border-${border}` : '',
       align ? `text-${align}` : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}
@@ -84,7 +82,6 @@
   <: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
@@ -93,9 +90,7 @@
     :_class=${attached
       ? 'card-group'
       : `row row-cols-1 row-cols-md-${cols} g-${gap}`}
-    :_groupClass=${extra ? `${_class} ${extra}` : _class}
-
-    class=${_groupClass}
+    class=${_class}
   >
     <:slot />
   </:define>

package/parts/carousel.htm

@@ -10,10 +10,9 @@
     is worth a component at all.
   -->
   <:define tag="bs-carousel:div"
-    class="carousel slide ${extra ?? ''}"
+    class="carousel slide"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::slides=${[]}
     ::controls=${true}
     ::indicators=${true}

package/parts/check.htm

@@ -4,15 +4,14 @@
   <!---
     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"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${null}
     ::type=${'checkbox'}   // 'checkbox' | 'radio' | 'switch'
     ::name=${null}
@@ -28,7 +27,7 @@
     :_helpId=${`bs-check-help-${$id}`}
     :_type=${type === 'switch' ? 'checkbox' : type}
 
-    class="form-check ${extra ?? ''}"
+    class="form-check"
     :class-form-switch=${type === 'switch'}
     :class-form-check-inline=${inline}
     :class-form-check-reverse=${reverse}
@@ -41,6 +40,7 @@
       role=${type === 'switch' ? 'switch' : null}
       aria-describedby=${help ? _helpId : null}
       :attr-checked=${checked}
+      :prop-checked=${checked}
       :attr-disabled=${disabled}
       :on-change=${ev => checked = ev.target.checked}>
 
@@ -54,25 +54,43 @@
 
   <!---
     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
+    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
+    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.
+
+    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
+    already picks the input's type and the switch class.
   -->
   <:define tag="bs-check-group:div"
-    class="mb-3 ${extra ?? ''}"
+    class="mb-3"
     role="group"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::legend=${null}
     ::type=${'radio'}
     ::options=${[]}
-    ::value=${null}
+    ::value=${type === 'radio' ? null : []}
     ::inline=${false}
     ::disabled=${false}
 
     // private
     :_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
+    // 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]}
 
     aria-labelledby=${legend ? _legendId : null}
     :_options=${options.map(o =>
@@ -100,9 +118,17 @@
         type=${type === 'switch' ? 'checkbox' : type}
         name=${_name}
         value=${option.value}
-        :attr-checked=${option.value === value}
+        :attr-checked=${_multi ? _selected.includes(option.value) : option.value === value}
+        :prop-checked=${_multi ? _selected.includes(option.value) : option.value === value}
         :attr-disabled=${disabled || option.disabled}
-        :on-change=${ev => value = ev.target.value}>
+        :on-change=${(ev) => {
+          if (!_multi) { value = ev.target.value; return; }
+          const on = ev.target.checked;
+          const hit = ev.target.value;
+          value = _options
+            .filter(o => (o.value === hit ? on : _selected.includes(o.value)))
+            .map(o => o.value);
+        }}>
       <label class="form-check-label"
         for="${_name}-${option.value}">${option.name}</label>
     </div>
@@ -110,10 +136,9 @@
 
   <!--- A range slider, with its label and its current value. -->
   <:define tag="bs-range:div"
-    class="mb-3 ${extra ?? ''}"
+    class="mb-3"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${null}
     ::name=${null}
     ::min=${0}
@@ -127,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
@@ -157,6 +182,7 @@
       max=${max}
       step=${step}
       value=${value}
+      :prop-value=${value}
       :attr-disabled=${disabled}
       :on-input=${ev => value = Number(ev.target.value)}>
   </:define>

package/parts/collapse.htm

@@ -4,19 +4,18 @@
   <!---
     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"
-    class="collapse ${extra ?? ''}"
+    class="collapse"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::name=${null}
     ::open=${false}
     ::horizontal=${false}

package/parts/dropdown.htm

@@ -15,7 +15,6 @@
   <:define tag="bs-dropdown:div"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${'Dropdown'}
     ::items=${[
       { name: 'Action', link: '#' },
@@ -33,7 +32,7 @@
 
     // private
     :_id=${`bs-dropdown-${$id}`}
-    :_class=${[direction === 'down' ? 'dropdown' : `drop${direction}`, extra]
+    :_class=${[direction === 'down' ? 'dropdown' : `drop${direction}`]
               .filter(s => s).join(' ')}
     :_btnClass=${[
       'btn',

package/parts/image.htm

@@ -8,14 +8,12 @@
   <: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}
@@ -25,10 +23,9 @@
 
   <!--- An image with its caption, as one thing. -->
   <:define tag="bs-figure:figure"
-    class="figure ${extra ?? ''}"
+    class="figure"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::src=${null}
     ::alt=${''}
     ::caption=${null}

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
@@ -35,10 +35,9 @@
     layouts are two regions rather than one with a class toggled on it.
   -->
   <:define tag="bs-input:div"
-    class="mb-3 ${extra ?? ''}"
+    class="mb-3"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${null}
     ::type=${'text'}
     ::name=${null}
@@ -75,6 +74,7 @@
         type=${type}
         name=${name}
         value=${value}
+        :prop-value=${value}
         placeholder=${placeholder}
         aria-describedby=${help ? _helpId : null}
         :class-is-invalid=${_invalid}
@@ -97,6 +97,7 @@
         type=${type}
         name=${name}
         value=${value}
+        :prop-value=${value}
         placeholder=${placeholder || label || ' '}
         :class-is-invalid=${_invalid}
         :attr-disabled=${disabled}
@@ -116,10 +117,9 @@
     `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 ?? ''}"
+    class="mb-3"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${null}
     ::name=${null}
     ::value=${''}
@@ -155,6 +155,7 @@
       :attr-disabled=${disabled}
       :attr-readonly=${readonly}
       :attr-required=${required}
+      :prop-value=${value}
       :on-input=${ev => value = ev.target.value}>${value}</textarea>
 
     <div class="form-text"
@@ -165,20 +166,19 @@
   </: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"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::prefix=${null}
     ::suffix=${null}
     ::size=${null}
 
     // private
-    :_class=${['input-group', size ? `input-group-${size}` : '', extra]
+    :_class=${['input-group', size ? `input-group-${size}` : '']
               .filter(s => s).join(' ')}
 
     class=${_class}

package/parts/list-group.htm

@@ -14,7 +14,6 @@
   <:define tag="bs-list-group:div"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::items=${[
       { name: 'An item', active: true },
       { name: 'A second item' },
@@ -28,7 +27,6 @@
       'list-group',
       flush ? 'list-group-flush' : '',
       horizontal ? 'list-group-horizontal' : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}

package/parts/modal.htm

@@ -13,17 +13,16 @@
     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.
   -->
   <:define tag="bs-modal:div"
-    class="modal fade ${extra ?? ''}"
+    class="modal fade"
     tabindex="-1"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::name=${null}
     ::title=${''}
     ::size=${null}          // 'sm' | 'lg' | 'xl'

package/parts/nav.htm

@@ -12,7 +12,6 @@
   <:define tag="bs-nav:ul"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::items=${[
       { name: 'Active', link: '#', active: true },
       { name: 'Link', link: '#' },
@@ -34,7 +33,6 @@
       vertical ? 'flex-column' : '',
       align === 'center' ? 'justify-content-center' : '',
       align === 'end' ? 'justify-content-end' : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}
@@ -64,17 +62,16 @@
     </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>
 
   <:define tag="bs-tab-pane:div"
-    class="tab-pane fade ${extra ?? ''}"
+    class="tab-pane fade"
     role="tabpanel"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::name=${null}
     ::active=${false}
 

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.
 
@@ -17,7 +17,6 @@
   <:define tag="bs-navbar:nav"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::items=${[
       { name: 'Home', link: '#', active: true },
       { name: 'Features', link: '#' },
@@ -37,7 +36,6 @@
       'navbar',
       expand ? `navbar-expand-${expand}` : '',
       bg ? `bg-${bg}` : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     // The gap under the links is only wanted while they are stacked, which

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>
@@ -14,7 +14,6 @@
     tabindex="-1"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::name=${null}
     ::title=${''}
     ::placement=${'start'}   // 'start' | 'end' | 'top' | 'bottom'
@@ -28,7 +27,6 @@
     :_class=${[
       responsive ? `offcanvas-${responsive}` : 'offcanvas',
       `offcanvas-${placement}`,
-      extra,
     ].join(' ')}
 
     class=${_class}

package/parts/pagination.htm

@@ -3,15 +3,15 @@
 
   <!---
     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.
@@ -19,7 +19,6 @@
   <:define tag="bs-pagination:nav"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::current=${1}
     ::pages=${5}
     ::size=${null}          // 'sm' | 'lg'
@@ -39,7 +38,6 @@
     ].filter(s => s).join(' ')}
     :_numbers=${Array.from({ length: pages }, (_, i) => i + 1)}
 
-    class=${extra}
     aria-label=${label}
   >
     <ul class=${_class}>

package/parts/placeholder.htm

@@ -9,14 +9,13 @@
   <:define tag="bs-placeholder:span"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::cols=${6}
     ::size=${null}         // 'xs' | 'sm' | 'lg'
     ::variant=${null}
     ::animation=${'glow'}  // 'glow' | 'wave' | null
 
     // private
-    :_class=${[animation ? `placeholder-${animation}` : '', extra]
+    :_class=${[animation ? `placeholder-${animation}` : '']
               .filter(s => s).join(' ') || null}
     :_barClass=${[
       'placeholder',

package/parts/popover.htm

@@ -10,10 +10,9 @@
     part that usually changes; both are read when it runs.
   -->
   <:define tag="bs-popover:span"
-    class="d-inline-block ${extra ?? ''}"
+    class="d-inline-block"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::title=${''}
     ::content=${''}
     ::placement=${'right'}

package/parts/progress.htm

@@ -4,15 +4,14 @@
   <!---
     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 ${extra ?? ''}"
+    class="progress"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::value=${0}
     ::min=${0}
     ::max=${100}

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} />
@@ -12,13 +12,11 @@
   <:define tag="bs-scrollspy:div"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::target=${null}
     ::offset=${0}
     ::smooth=${false}
     ::height=${null}
 
-    class=${extra}
     data-bs-spy="scroll"
     data-bs-target=${target}
     data-bs-root-margin="${offset}px 0px -40%"

package/parts/select.htm

@@ -8,10 +8,9 @@
       <bs-select ::label="Size" ::options=${['S', 'M', 'L']} />
   -->
   <:define tag="bs-select:div"
-    class="mb-3 ${extra ?? ''}"
+    class="mb-3"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::label=${null}
     ::name=${null}
     ::options=${[]}
@@ -51,13 +50,15 @@
 
         <option value=""
           :if=${placeholder}
-          :attr-selected=${value == null}>${placeholder}</option>
+          :attr-selected=${value == null}
+          :prop-selected=${value == null}>${placeholder}</option>
 
         <option :for-each=${_options}
           :for-as="option"
           value=${option.value}
           :attr-disabled=${option.disabled}
-          :attr-selected=${option.value === value}>${option.name}</option>
+          :attr-selected=${option.value === value}
+          :prop-selected=${option.value === value}>${option.name}</option>
       </select>
 
       <label for=${_id}

package/parts/spinner.htm

@@ -10,7 +10,6 @@
     role="status"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::variant=${null}
     ::type=${'border'}    // 'border' | 'grow'
     ::small=${false}
@@ -21,7 +20,6 @@
       `spinner-${type}`,
       small ? `spinner-${type}-sm` : '',
       variant ? `text-${variant}` : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}

package/parts/table.htm

@@ -2,21 +2,20 @@
   <: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.
   -->
   <:define tag="bs-table:div"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::columns=${[]}
     ::rows=${[]}
     ::caption=${null}
@@ -42,7 +41,6 @@
       align ? `align-${align}` : '',
     ].filter(s => s).join(' ')}
 
-    class=${extra}
     :class-table-responsive=${responsive}
   >
     <table class=${_class}>

package/parts/theme.htm

@@ -10,6 +10,16 @@
     piece of this kit that cannot be reactive, because it has to happen
     before Markout exists.
 
+    It is also the one piece that would otherwise DO something merely because
+    a file was imported. `all.htm` pulls this file in, so every page taking
+    the whole kit used to get colour modes whether it asked for them or not —
+    which is the kind of action at a distance the rest of the kit has none
+    of. So the script waits on a tag: write `<bs-theme-auto />` for the
+    behaviour on its own, or a `<bs-theme-toggle />` for the behaviour and a
+    button to drive it, and a page that writes neither ships neither. Naming
+    a tag no `<:define>` declares is a compile error, which is what stops a
+    rename from leaving this waiting on a name nothing will ever use.
+
     From there `_theme` is an ordinary value, and it starts as whatever that
     script decided rather than as a literal: a served page knows nothing
     about this visitor, so a default written here would be a guess that the
@@ -28,7 +38,7 @@
     kit would rather say so at the point of use than pretend a server has
     them.
   -->
-  <script>
+  <script :when-used="bs-theme-auto bs-theme-toggle">
     (() => {
       const stored = localStorage.getItem('bs-theme');
       const theme = stored
@@ -37,11 +47,25 @@
     })();
   </script>
 
+  <!---
+    "This page uses colour modes", and nothing else. The script above does
+    the work; this is how a page asks for it without also asking for a
+    button, and it has no element, so what it costs the page is one empty
+    scope — 58 bytes on the counter example.
+
+    Deliberately holding no value. It could expose the current mode for a
+    page that needs it in an expression rather than in CSS, and that is 109
+    bytes of props on every page that opts in and doesn't read it, which is
+    all of them so far. A component whose job is to say one thing should
+    cost what saying it costs; the value can be added the day something
+    wants it, and adding it then breaks nothing.
+  -->
+  <:define tag="bs-theme-auto:logic" />
+
   <:define tag="bs-theme-toggle:button"
     type="button"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::variant=${'secondary'}
     ::outline=${true}
     ::size=${null}
@@ -52,7 +76,6 @@
       'btn',
       `btn-${outline ? 'outline-' : ''}${variant}`,
       size ? `btn-${size}` : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}

package/parts/toast.htm

@@ -20,7 +20,6 @@
     aria-atomic="true"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::title=${null}
     ::time=${null}
     ::variant=${null}
@@ -29,7 +28,7 @@
     ::delay=${5000}
 
     // private
-    :_class=${['toast', variant ? `text-bg-${variant} border-0` : '', extra]
+    :_class=${['toast', variant ? `text-bg-${variant} border-0` : '']
               .filter(s => s).join(' ')}
 
     class=${_class}
@@ -81,7 +80,7 @@
 
       <bs-close ::dismiss="toast"
         ::label="Close notification"
-        ::extra="me-2 m-auto"
+        class+="me-2 m-auto"
         :if=${!title} />
     </div>
   </:define>
@@ -93,7 +92,6 @@
   <:define tag="bs-toast-container:div"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::placement=${'bottom-end'}   // 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'top-center'
 
     // private
@@ -103,7 +101,6 @@
       placement.endsWith('start') ? 'start-0' : '',
       placement.endsWith('end') ? 'end-0' : '',
       placement.endsWith('center') ? 'start-50 translate-middle-x' : '',
-      extra,
     ].filter(s => s).join(' ')}
 
     class=${_class}

package/parts/tooltip.htm

@@ -26,10 +26,9 @@
     of its own to hang off; wrap the trigger, not the page around it.
   -->
   <:define tag="bs-tooltip:span"
-    class="d-inline-block ${extra ?? ''}"
+    class="d-inline-block"
 
     // parameters
-    ::extra=${null}      // extra classes for this instance
     ::title=${''}
     ::placement=${'top'}
     ::html=${false}