@repobit/dex-system-design 1.0.1 → 2.0.0

package/src/components/highlight/highlight.stories.js

@@ -22,10 +22,11 @@ export default {
 \`\`\`
 
 ### Behavior
-- The component reads \`this.textContent\` and splits it on \`highlight-text\`
-- If \`highlight-text\` is not found in the text, the full slot content is rendered without decoration
-- If found, the highlighted word gets a \`<span class="highlight">\` wrapper with decorative SVG elements (ellipses + rectangles) added on both sides
-- The right-side decoration is injected via \`updated()\` using direct DOM manipulation
+- The headline keeps its markup: \`<em>\`, \`<strong>\`, \`<br>\` and links render as written, and the first occurrence of \`highlight-text\` is marked where it sits; a later occurrence renders as plain text
+- The headline is a copy of the content, so a script listener attached to an element inside it does not carry over; links still work, because the \`href\` does
+- If \`highlight-text\` is not found, or crosses an element boundary (\`family <em>member</em>\`), the content renders through the slot as it is, without decoration
+- The mark is a \`<span class="highlight">\` with a bar and dot drawn at each end
+- Editing the content after it renders re-renders the headline
 
 ### Notes
 - \`sub-title\` renders a \`bd-p kind="small"\` above the headline, **not** a heading

package/src/components/icons/icon-element.js

@@ -1,6 +1,23 @@
 import { LitElement, css } from "lit";
 import { iconSize } from "../shared/token-scales.js";
 
+/* One sheet per distinct size and colour, shared by every icon that asks for
+   the same pair: a page of forty check icons adopts one sheet, not forty. */
+const instanceSheets = new Map();
+
+const instanceSheet = (size, color) => {
+  const key = `${size}|${color}`;
+  let sheet = instanceSheets.get(key);
+  if (!sheet) {
+    sheet = new CSSStyleSheet();
+    sheet.replaceSync(
+      `:host { --bd-icon-size: ${size}; }` + (color ? ` svg { color: ${color}; }` : "")
+    );
+    instanceSheets.set(key, sheet);
+  }
+  return sheet;
+};
+
 /**
  * Base for the tintable interface icons.
  *
@@ -47,8 +64,9 @@ export class BdIconElement extends LitElement {
   static styles = css`
     :host {
       display: inline-flex;
-      /* --bd-icon-size is component-local and always set below, so the
-         fallback is only reached if a subclass forgets to call super. */
+      /* --bd-icon-size is component-local and always set by the instance
+         sheet below, so the fallback is only reached if a subclass forgets to
+         call super. */
       height: var(--bd-icon-size, var(--icon-md-size));
     }
 
@@ -83,17 +101,42 @@ export class BdIconElement extends LitElement {
     this.height = null;
   }
 
+  /* WHY NOT THE HOST'S STYLE ATTRIBUTE.
+     This used to write --bd-icon-size and color into this.style on every
+     update. The host's style attribute belongs to the page, and with no color
+     prop the update removed the colour outright, so
+     <bd-check-icon style="color: green"> rendered in the inherited text
+     colour, and so did any icon a script coloured after its first render.
+     The inline size meant no stylesheet could set --bd-icon-size either.
+
+     Both now live in a sheet adopted into this shadow root, and the host's
+     style attribute is never read or written:
+
+       size    a :host rule. The page's CSS on the element wins over it, as it
+               already did for height -- header.css.js sets one on
+               .bd-header-signature -- and now does for --bd-icon-size too.
+       colour  a rule on the svg, so the color prop still beats the page's CSS
+               on the host, as the inline colour did. Unset, nothing is
+               written and the artwork's currentColor follows the host,
+               wherever its colour came from. */
   willUpdate() {
     // An explicit pixel size wins, for the callers that still pass one.
     const px = this.height ?? this.width;
     const { defaultSize } = this.constructor;
     // a step first, then an off-scale default, then the caller's pixels
     const step = iconSize(this.size) || iconSize(defaultSize) || defaultSize;
-    this.style.setProperty("--bd-icon-size", px == null ? step : `${px}px`);
+    const size = Number.isFinite(px) ? `${px}px` : step;
 
     // No colour of its own by default: the artwork is currentColor, so it
-    // follows whatever it sits in.
-    if (this.color) this.style.color = this.color;
-    else this.style.removeProperty("color");
+    // follows whatever it sits in. A value CSS would not accept as a colour is
+    // dropped, as an inline one was -- and it never reaches the sheet's text.
+    const color = this.color && CSS.supports("color", this.color) ? this.color : "";
+
+    this._baseSheets ??= this.renderRoot.adoptedStyleSheets;
+    const sheet = instanceSheet(size, color);
+    if (this._instanceSheet !== sheet) {
+      this._instanceSheet = sheet;
+      this.renderRoot.adoptedStyleSheets = [...this._baseSheets, sheet];
+    }
   }
 }

package/src/components/icons/icons.stories.js

@@ -81,6 +81,13 @@ per the foundation rule it should be a token reference such as
 text it sits beside. A raw hex value here is the same drift the tokens exist to
 prevent.
 
+### Styling an icon from the page
+An icon never writes its own \`style\` attribute, so whatever the page puts
+there stays. With no \`color\` prop, \`style="color: …"\` or any stylesheet
+colour on the icon reaches the artwork; the \`color\` prop, when set, beats both.
+A stylesheet can size an icon with \`height\` or \`--bd-icon-size\` on the
+element, and either beats the \`size\` prop.
+
 ### Known inconsistencies
 - **\`bd-laurel-icon\` keeps an 80px default**, off the scale, which stops at 64.
   Shrinking the awards wreath by a fifth is a design decision rather than a

package/src/components/image/image.css.js

@@ -84,112 +84,23 @@ export default css`
       box-shadow: var(--shadow-xl);
     }
 
-    /* Border Variants - Keep for additional styling options */
-    .bd-img.bordered {
-      border: var(--border-width-2) solid var(--color-border-subtle);
-    }
-
-    .bd-img.bordered-primary {
-      border: var(--border-width-2) solid var(--color-border-brand);
-    }
-
-    .bd-img.bordered-thick {
-      border: var(--border-width-4) solid var(--color-border-disabled);
-    }
-
-    /* Responsive Behavior */
-    .bd-img.responsive {
-      width: 100%;
-      height: auto;
-    }
-
-    /* Aspect Ratio Containers */
-    .bd-img.aspect-16-9 {
-      aspect-ratio: 16 / 9;
-    }
-
-    .bd-img.aspect-4-3 {
-      aspect-ratio: 4 / 3;
-    }
-
-    .bd-img.aspect-1-1 {
-      aspect-ratio: 1 / 1;
-    }
-
-    /* Hover Effects */
-    .bd-img.hover-zoom:hover {
-      transform: scale(1.05);
-      transition: transform var(--transition-duration-slow) var(--transition-easing-smooth);
-    }
-
-    .bd-img.hover-shadow:hover {
-      box-shadow: var(--shadow-lg);
-      transition: box-shadow var(--transition-duration-slow) var(--transition-easing-smooth);
-    }
-
-    .bd-img:focus-visible {
-      /* the one focus ring — see Foundations/Focus */
-      outline: none;
-      box-shadow: var(--focus-outline-primary);
-    }
-
-    /* Loading state */
-    .bd-img:not([src]) {
-      background-color: var(--color-surface-muted);
-      /* no token: the dimension scale stops at 64px */
-      min-height: 100px;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      /* --color-text-muted, not --color-text-disabled. Loading is not disabled,
-         and the difference is not academic: the disabled text role carries a
-         contrast exemption -- WCAG 1.4.3 excuses disabled controls from the
-         4.5:1 minimum -- and this label claims that exemption without being
-         entitled to it. It is a sentence a reader is meant to read while they
-         wait.
-
-         Measured on this ground: neutral-400 on neutral-100 is 2.51:1, which
-         misses even the 3:1 floor for non-text. --color-text-muted is
-         neutral-600 at 5.12:1 and is the role this package already uses for
-         low-emphasis readable text -- caption and form help text both resolve
-         to it.
-
-         The ground stays --color-surface-muted. Loading is a state, muted is
-         the state surface, and bd-skeleton -- the package's other loading
-         affordance -- already sits on it. Only the ink was choosing by value.
-         See "Choosing a semantic role" in the package README. */
-      color: var(--color-text-muted);
-      /* no role: alt text shown when the image has no src -- a glyph/marker/placeholder box, not running
-         prose. See list-item.css.js's .bd-list-item-marker::before for the
-         argument. */
-      font-size: var(--typography-fontSize-sm);
-    }
-
-    /* The placeholder copy is a local property rather than a string in the
-       stylesheet: content: "Image loading..." cannot be translated, and this
-       atom and bd-picture used two different sentences for the same state. */
-    .bd-img:not([src])::before {
-      content: var(--bd-img-loading-label, "Loading image");
-    }
+    /* Gone from here, because nothing could reach them: bordered,
+       bordered-primary and bordered-thick, responsive, aspect-16-9 / 4-3 /
+       1-1, hover-zoom and hover-shadow had no prop, and the only way to set
+       one was to pass its name as fit, which now accepts only the five values
+       above. :focus-visible styled an <img>, which never takes focus. And the
+       :not([src]) loading placeholder could not appear: the template always
+       writes a src attribute, and an <img> renders no ::before even without
+       one. bd-picture keeps its own placeholder, which does work. */
 
     /* Smooth transitions for radius and shadow changes */
     .bd-img {
       transition: border-radius var(--transition-duration-normal) var(--transition-easing-smooth), box-shadow var(--transition-duration-normal) var(--transition-easing-smooth);
     }
 
-    /* Performance optimization for transforms */
-    .bd-img.hover-zoom {
-      will-change: transform;
-    }
-
-    /* A hover that scales the image is the category of motion the setting
-       exists for, and this atom had no guard at all. */
     @media (prefers-reduced-motion: reduce) {
-      .bd-img,
-      .bd-img.hover-zoom:hover,
-      .bd-img.hover-shadow:hover {
+      .bd-img {
         transition: none;
-        transform: none;
       }
     }
   }

package/src/components/image/image.js

@@ -5,6 +5,11 @@ import imgCSS from "./image.css.js";
 
 // the radius steps image.css.js implements — the full --radius-* scale
 const RADIUS_STEPS = ['none', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', 'full'];
+/* fit and shadow become class names, so an unknown value used to become a
+   class too -- fit="bordered" reached a rule nothing documented. Only the
+   values image.css.js implements get through; anything else is the default. */
+const FITS = ['cover', 'contain', 'fill', 'none', 'scale-down'];
+const SHADOWS = ['none', 'sm', 'md', 'lg', 'xl'];
 
 export class BdImg extends LitElement {
   static properties = {
@@ -32,10 +37,10 @@ export class BdImg extends LitElement {
 
   render() {
     const baseClass = 'bd-img';
-    const fitClass = this.fit || 'cover';
+    const fitClass = FITS.includes(this.fit) ? this.fit : 'cover';
     const radius = RADIUS_STEPS.includes(this.radius) ? this.radius : 'none';
     const radiusClass = `radius-${radius}`;
-    const shadowClass = `shadow-${this.shadow || 'none'}`;
+    const shadowClass = `shadow-${SHADOWS.includes(this.shadow) ? this.shadow : 'none'}`;
 
     const finalClass = `${baseClass} ${fitClass} ${radiusClass} ${shadowClass}`;
 

package/src/components/input/custom-form.stories.js

@@ -23,7 +23,7 @@ It includes:
 | State | Description |
 |---|---|
 | \`default\` | Idle, no interaction |
-| \`focused\` | Active keyboard / pointer focus |
+| \`focused\` | Has keyboard focus — set it to move focus into the field; it reflects whether the field is focused |
 | \`invalid\` | Failed validation — red border + helper text |
 | \`validated\` | Passed validation — green border + check icon |
 | \`disabled\` | Non-interactive, visually muted |
@@ -86,7 +86,8 @@ the events for your own use.
 \`invalid\` sets \`aria-invalid="true"\`, and when \`tooltip\` is present the input
 points at it with \`aria-describedby\` — so a screen reader announces both that
 the field is wrong and why. Put the reason in \`tooltip\`; it doubles as the
-help text and the error message.
+help text and the error message. \`bd-custom-dropdown\` and
+\`bd-custom-input-clipboard\` do the same.
 
 The required asterisk is \`aria-hidden\`, because the native \`required\`
 attribute is what actually conveys it.
@@ -129,26 +130,19 @@ everything else is not:
 | | \`bd-custom-input\` | \`bd-custom-dropdown\` | \`bd-custom-input-clipboard\` |
 |---|---|---|---|
 | \`label\`, \`kind\`, \`required\`, \`invalid\`, \`validated\`, \`disabled\`, \`tooltip\` | yes | yes | yes |
-| \`value\` | yes | **no** | yes |
+| \`value\` | yes | yes | yes |
 | \`type\`, \`placeholder\`, \`focused\` | yes | **no** | yes |
-| \`name\`, \`inputmode\`, \`autocomplete\`, \`enterkeyhint\` | yes | **no** | **no** |
+| \`name\` | yes | yes | yes |
+| \`inputmode\`, \`autocomplete\`, \`enterkeyhint\` | yes | **no** | **no** |
 | \`options\` | **no** | yes | **no** |
-| emits | \`bd-input\`, \`bd-change\` | **nothing** | \`input\` |
+| emits | \`bd-input\`, \`bd-change\` | \`bd-input\`, \`bd-change\` | \`bd-input\`, \`bd-change\` |
 
 Storybook shows one shared control panel for all three, so a knob that does
 nothing on the story you are looking at is expected — check this table.
 
-Two of those rows are gaps rather than design:
-
-- **The select emits no event and has no \`value\`.** Choosing an option changes
-  nothing observable from outside the component, so it cannot currently be read
-  without reaching into its shadow root. It needs the same \`value\` +
-  \`bd-input\`/\`bd-change\` treatment the input has.
-- **The clipboard field's event is not the input's.** It fires \`input\` — the
-  native event's own name — with the string as \`detail\` rather than
-  \`{ value, name }\`, and it is neither \`bubbles\` nor \`composed\`, so it reaches
-  a listener on the element itself and nothing further up. Renaming it to
-  \`bd-input\` would align the three, and is a breaking change.
+All three emit the same events with the same \`detail\`, so one form handler
+reads them. The clipboard field used to fire \`input\` — the native event's
+name — with a bare string; a paste fires \`bd-input\` and then \`bd-change\`.
 
 ### The clipboard field pastes, it does not copy
 The button reads the system clipboard with \`navigator.clipboard.readText()\` and
@@ -222,7 +216,7 @@ misses 2.5.5 (AAA, 44px) at every size.
     },
     focused: {
       control    : 'boolean',
-      description: 'Forces the focus ring on; useful for design review in Storybook',
+      description: 'Moves keyboard focus into the field, and reflects whether it has focus. The ring is the browser\'s real focus ring.',
       table      : {
         type        : { summary: 'boolean' },
         defaultValue: { summary: false },
@@ -405,7 +399,8 @@ export const InputDefault = {
 };
 
 /**
- * Input with the focused ring forced on — useful for design review without interaction.
+ * An input that takes focus when it renders, through the focused prop -- the
+ * ring is the real one, because the field really is focused.
  */
 export const InputFocused = {
   name      : 'Input — Focused',
@@ -415,7 +410,7 @@ export const InputFocused = {
     docs: {
       description: {
         story:
-          'Focus ring applied via the `focused` boolean prop. Demonstrates the active ring style without requiring pointer or keyboard interaction inside the story frame.'
+          '`focused` moves keyboard focus into the field when the story renders, so the ring shown is the browser\'s own. Clicking elsewhere clears it, and the prop follows.'
       }
     }
   }

package/src/components/input/input-clipboard.css.js

@@ -50,7 +50,12 @@ export default css`
      shared one; the radius is the default for an element with no radius of its
      own, so the ring is not a hard rectangle. */
   .paste-button:focus-visible {
-    outline: none;
+    /* forced-colors mode does not paint box-shadow, so the ring
+       vanishes there; it does paint an outline, in a system colour. This one
+       is transparent everywhere else, and the offset lands it on the ring's
+       outer band. */
+    outline: var(--border-width-2) solid transparent;
+    outline-offset: var(--focus-outline-offset);
     box-shadow: var(--focus-outline-primary);
     border-radius: var(--focus-outline-radius);
   }

package/src/components/input/input-clipboard.js

@@ -14,12 +14,14 @@ class CustomInputClipboard extends LitElement {
     kind       : { type: String },
     placeholder: { type: String },
     required   : { type: Boolean },
-    focused    : { type: Boolean },
+    focused    : { type: Boolean, reflect: true },
     tooltip    : { type: String },
     invalid    : { type: Boolean },
     validated  : { type: Boolean, reflect: true },
     disabled   : { type: Boolean, reflect: true },
-    value      : { type: String }
+    value      : { type: String },
+    /** Carried on the event detail, as on bd-custom-input. */
+    name       : { type: String }
   };
 
   constructor() {
@@ -37,13 +39,32 @@ class CustomInputClipboard extends LitElement {
     this.validated = false;
     this.disabled = false;
     this.value = "";
+    this.name = "";
+  }
+
+  /* THE EVENTS ARE bd-custom-input's.
+     This fired an event named input -- the native event's own name -- with
+     the bare string as detail, neither bubbling nor composed. The native
+     input from the inner <input> is composed and already leaves the shadow
+     root, so a listener on the host heard every keystroke twice, once with a
+     detail and once without, and a paste once. Now it is bd-input on every
+     change and bd-change on commit, each { value, name }, bubbling and
+     composed, as on bd-custom-input: one form handler reads all three fields.
+     A paste is a commit as well as a change, so it fires both. */
+  _emit(type) {
+    this.dispatchEvent(new CustomEvent(type, {
+      detail  : { value: this.value, name: this.name },
+      bubbles : true,
+      composed: true
+    }));
   }
 
   async pasteFromClipboard() {
     try {
       const text = await navigator.clipboard.readText();
       this.value = text;
-      this.dispatchEvent(new CustomEvent("input", { detail: text }));
+      this._emit("bd-input");
+      this._emit("bd-change");
     } catch (err) {
       console.error("Clipboard paste failed:", err);
     }
@@ -51,7 +72,11 @@ class CustomInputClipboard extends LitElement {
 
   handleInput(e) {
     this.value = e.target.value;
-    this.dispatchEvent(new CustomEvent("input", { detail: this.value }));
+    this._emit("bd-input");
+  }
+
+  handleChange() {
+    this._emit("bd-change");
   }
 
   willUpdate(changed) {
@@ -61,6 +86,21 @@ class CustomInputClipboard extends LitElement {
     if (changed.has("size") || changed.has("kind")) this.size = resolveSize(this.size);
   }
 
+  /* focused is the field's real focus, both ways. Setting it moves keyboard
+     focus into the <input> and clearing it blurs the field; focusing or
+     leaving the field by hand sets it, and it reflects, so the attribute says
+     whether the field has focus. It used to add a .focused class that painted
+     the focus ring on a field that did not have focus -- a second, false
+     indicator on any page that set it. The ring is now only the browser's
+     :focus-visible, which a text field shows whenever it is focused. */
+  updated(changed) {
+    if (!changed.has('focused')) return;
+    const input = this.shadowRoot.querySelector('input');
+    const has = this.shadowRoot.activeElement === input;
+    if (this.focused && !has) input?.focus();
+    if (!this.focused && has) input?.blur();
+  }
+
   render() {
     const inputClass = {
       sm: "input-sm",
@@ -88,6 +128,10 @@ class CustomInputClipboard extends LitElement {
         ? "form-help-text--success"
         : "form-help-text--default";
 
+    // The hint is the field's description, and the state is announced, not
+    // only drawn: invalid used to be a red border alone and the hint was never
+    // pointed at, so the reason a field was invalid reached a screen reader
+    // not at all. Both as bd-custom-input does them.
     return html`
       <div class="input-container">
         ${this.label
@@ -101,15 +145,19 @@ class CustomInputClipboard extends LitElement {
         <div class="input-with-button">
           <input
             id="clipboard-input"
-            class="form-input-bd ${inputClass} ${this.focused
-              ? "focused"
-              : ""} ${inputStateClass}"
+            class="form-input-bd ${inputClass} ${inputStateClass}"
             type="${this.type}"
             placeholder="${this.placeholder}"
             .value="${this.value}"
             ?required="${this.required}"
             ?disabled="${this.disabled}"
+            name="${this.name || nothing}"
+            aria-invalid="${this.invalid ? "true" : nothing}"
+            aria-describedby="${this.tooltip ? "clipboard-input-help" : nothing}"
+            @focus="${() => { this.focused = true; }}"
+            @blur="${() => { this.focused = false; }}"
             @input="${this.handleInput}"
+            @change="${this.handleChange}"
           />
           <button
             class="paste-button"
@@ -139,7 +187,7 @@ class CustomInputClipboard extends LitElement {
         </div>
 
         ${this.tooltip
-          ? html`<div class="form-help-text ${helpTextClass}">
+          ? html`<div id="clipboard-input-help" class="form-help-text ${helpTextClass}">
               ${this.tooltip}
             </div>`
           : ""}

package/src/components/input/input.js

@@ -18,7 +18,7 @@ class CustomInput extends LitElement {
     kind        : { type: String },
     placeholder : { type: String },
     required    : { type: Boolean },
-    focused     : { type: Boolean },
+    focused     : { type: Boolean, reflect: true },
     tooltip     : { type: String },
     invalid     : { type: Boolean },
     validated   : { type: Boolean, reflect: true },
@@ -86,6 +86,21 @@ class CustomInput extends LitElement {
     if (changed.has("size") || changed.has("kind")) this.size = resolveSize(this.size);
   }
 
+  /* focused is the field's real focus, both ways. Setting it moves keyboard
+     focus into the <input> and clearing it blurs the field; focusing or
+     leaving the field by hand sets it, and it reflects, so the attribute says
+     whether the field has focus. It used to add a .focused class that painted
+     the focus ring on a field that did not have focus -- a second, false
+     indicator on any page that set it. The ring is now only the browser's
+     :focus-visible, which a text field shows whenever it is focused. */
+  updated(changed) {
+    if (!changed.has('focused')) return;
+    const input = this.shadowRoot.querySelector('input');
+    const has = this.shadowRoot.activeElement === input;
+    if (this.focused && !has) input?.focus();
+    if (!this.focused && has) input?.blur();
+  }
+
   render() {
     const inputClass = { sm: "input-sm", md: "input-md", lg: "input-lg" }[this.size];
     const labelClass = { sm: "label-sm", md: "label-md", lg: "label-lg" }[this.size];
@@ -116,7 +131,7 @@ class CustomInput extends LitElement {
           : nothing}
         <input
           id="${INPUT_ID}"
-          class="form-input-bd ${inputClass} ${this.focused ? "focused" : ""} ${inputStateClass}"
+          class="form-input-bd ${inputClass} ${inputStateClass}"
           type="${this.type}"
           name="${this.name || nothing}"
           placeholder="${this.placeholder}"
@@ -128,6 +143,8 @@ class CustomInput extends LitElement {
           ?disabled="${this.disabled}"
           aria-invalid="${this.invalid ? "true" : nothing}"
           aria-describedby="${this.tooltip ? HELP_ID : nothing}"
+          @focus="${() => { this.focused = true; }}"
+          @blur="${() => { this.focused = false; }}"
           @input="${this._onInput}"
           @change="${this._onChange}"
         />

package/src/components/label/label.js

@@ -4,6 +4,13 @@ import '../../tokens/tokens.js';
 import { labelCSS } from './label.css.js';
 import { resolveSize } from '../shared/prop-vocabulary.js';
 
+let labelIds = 0;
+
+/* Controls whose own <label for> would have worked: the ones a label can be
+   for. A custom element is not here -- see the note on _target. */
+const LABELABLE = new Set(["input", "select", "textarea", "button", "meter", "output", "progress"]);
+const ACTIVATES = new Set(["checkbox", "radio"]);
+
 export class BdLabel extends LitElement {
   static styles = [labelCSS];
 
@@ -17,6 +24,7 @@ export class BdLabel extends LitElement {
     super();
     this.size = 'md';
     this.required = false;
+    this.addEventListener('click', e => this._activate(e));
   }
 
   willUpdate(changed) {
@@ -24,9 +32,87 @@ export class BdLabel extends LitElement {
     if (changed.has('size')) this.size = resolveSize(this.size, 'md');
   }
 
+  /* WHY for IS DONE BY HAND.
+     The <label> this renders is in its own shadow root, and a for reference
+     resolves only in the tree it is written in, so <bd-label for="email">
+     pointed at nothing: the control went unnamed and a click on the label did
+     nothing. It now does what a native label's for does, for a native control
+     in the same tree as this element:
+
+       name       the control gets aria-labelledby pointing at this element,
+                  added to whatever it already lists, and taken back when for
+                  changes or this element leaves -- so the control is named by
+                  the label's text
+       activate   a click on the label focuses the control, and toggles it
+                  when it is a checkbox or a radio
+
+     The control may not exist yet when this renders -- it can come later in
+     the page, or be rendered after -- so until it is found the root is
+     watched for it. */
+  connectedCallback() {
+    super.connectedCallback();
+    this._link();
+  }
+
+  disconnectedCallback() {
+    this._unlink();
+    super.disconnectedCallback();
+  }
+
+  updated(changed) {
+    if (changed.has('for')) this._link();
+  }
+
+  /* The control, when for names one in this element's own tree. A custom
+     element is skipped: its real control is inside its own shadow root, where
+     aria-labelledby on the host does not reach -- label a bd-custom-input
+     with its own label prop. */
+  get _target() {
+    if (!this.for || !this.isConnected) return null;
+    const el = this.getRootNode().getElementById?.(this.for);
+    return el && LABELABLE.has(el.localName) ? el : null;
+  }
+
+  _link() {
+    this._unlink();
+    if (!this.for || !this.isConnected) return;
+    const target = this._target;
+    if (!target) {
+      // not there yet: watch for it, and stop as soon as it is
+      const root = this.getRootNode();
+      this._waiting = new MutationObserver(() => { if (this._target) this._link(); });
+      this._waiting.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['id'] });
+      return;
+    }
+    if (!this.id) this.id = `bd-label-${++labelIds}`;
+    const ids = (target.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean);
+    if (!ids.includes(this.id)) target.setAttribute('aria-labelledby', [...ids, this.id].join(' '));
+    this._linked = { target, id: this.id };
+  }
+
+  _unlink() {
+    this._waiting?.disconnect();
+    this._waiting = null;
+    if (!this._linked) return;
+    const { target, id } = this._linked;
+    const ids = (target.getAttribute('aria-labelledby') || '').split(/\s+/).filter(t => t && t !== id);
+    if (ids.length) target.setAttribute('aria-labelledby', ids.join(' '));
+    else target.removeAttribute('aria-labelledby');
+    this._linked = null;
+  }
+
+  _activate(e) {
+    const target = this._target;
+    if (!target || target.disabled) return;
+    // a link or a control slotted into the label keeps its own click
+    if (e.composedPath().some(n => n !== this && n.matches?.('a[href], button, input, select, textarea'))) return;
+    target.focus();
+    if (target.localName === 'input' && ACTIVATES.has(target.type)) target.click();
+  }
+
   render() {
     return html`
-      <label for=${this.for || nothing}>
+      <label>
         <slot></slot>${this.required
           ? html`<span class="required" aria-hidden="true">*</span>`
           : nothing}