@repobit/dex-system-design 1.0.1 → 2.0.0

package/src/components/carousel/carousel.js

@@ -4,6 +4,7 @@ import "../../tokens/tokens.js";
 import carouselCSS from "../carousel/carousel.css.js";
 import "../heading/heading.js";
 import "../modal/modal.js";
+import "../pagination-dots/pagination-dots.js";
 export class CarouselItem extends LitElement {
   static properties = {
     icon     : { type: String },
@@ -61,7 +62,9 @@ class CustomCarousel extends LitElement {
   static properties = {
     title       : { type: String },
     headingLevel: { type: Number, attribute: "heading-level" },
-    selectedItem: { type: Object }
+    selectedItem: { type: Object },
+    _pages      : { state: true },
+    _page       : { state: true }
   };
 
   constructor() {
@@ -69,6 +72,10 @@ class CustomCarousel extends LitElement {
     this.selectedItem = null;
     this.title = "";
     this.headingLevel = 2;
+    // scroll stops, 1-based, read from the track; see _measure
+    this._pages = 1;
+    this._page = 1;
+    this._seeking = 0;
   }
 
   /**
@@ -98,36 +105,22 @@ class CustomCarousel extends LitElement {
   firstUpdated() {
     this.track = this.shadowRoot.querySelector(".bd-carousel-track");
     this.slotElement = this.shadowRoot.querySelector("slot");
-    this.leftArrow = this.shadowRoot.querySelector(".bd-left-arrow");
-    this.rightArrow = this.shadowRoot.querySelector(".bd-right-arrow");
 
-    this.track.addEventListener("scroll", () => this.updateArrowStates());
+    this.track.addEventListener("scroll", () => this._measure(), { passive: true });
+    this.track.addEventListener("scrollend", () => { this._seeking = 0; this._measure(); });
+    // a visitor taking hold of the track ends any scroll a control started
+    for (const type of ["pointerdown", "touchstart", "wheel"]) {
+      this.track.addEventListener(type, () => { this._seeking = 0; }, { passive: true });
+    }
 
     this.slotElement.addEventListener("slotchange", () => {
-      this.waitForImagesToLoad().then(() => {
-        this.updateArrowStates();
-      });
+      this.waitForImagesToLoad().then(() => this._measure());
     });
 
-    setTimeout(() => {
-      this.waitForImagesToLoad().then(() => {
-        this.updateArrowStates();
-      });
-    }, 0);
-
-    const arrows = this.shadowRoot.querySelectorAll(".bd-arrow");
-    arrows.forEach((arrow) => {
-      arrow.addEventListener("mousedown", () =>
-        arrow.classList.add("bd-active")
-      );
-      arrow.addEventListener("mouseup", () =>
-        arrow.classList.remove("bd-active")
-      );
-      arrow.addEventListener("mouseleave", () =>
-        arrow.classList.remove("bd-active")
-      );
-      arrow.addEventListener("keydown", (e) => this._onArrowKeydown(e, arrow));
-    });
+    this._resizeObserver = new ResizeObserver(() => this._measure());
+    this._resizeObserver.observe(this.track);
+
+    this.waitForImagesToLoad().then(() => this._measure());
 
     this.addEventListener("open-modal", (e) => {
       this.openModal(e.detail);
@@ -135,6 +128,11 @@ class CustomCarousel extends LitElement {
     this.enableDragAndTouchScroll(this.track);
   }
 
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._resizeObserver?.disconnect();
+  }
+
   waitForImagesToLoad() {
     const assignedElements = this.slotElement.assignedElements({
       flatten: true
@@ -155,40 +153,47 @@ class CustomCarousel extends LitElement {
     return Promise.all(promises);
   }
 
-  scrollCarousel(direction) {
-    const assignedElements = this.slotElement.assignedElements({
-      flatten: true
-    });
-    if (!assignedElements.length) return;
-    const itemWidth = assignedElements[0].offsetWidth || 300;
-    if (!this.track) return;
-
-    this.track.scrollBy({
-      left    : direction === "left" ? -itemWidth : itemWidth,
-      behavior: "smooth"
-    });
-
-    setTimeout(() => this.updateArrowStates(), 300);
+  /* The distance from one item to the next: an item's width and the gap. A
+     scroll stop is one of these, and the controls count stops, not items --
+     the last stop is wherever the track ends, which is short of a full step
+     when the items do not divide the width evenly. */
+  _step() {
+    const first = this.slotElement?.assignedElements({ flatten: true })[0];
+    if (!first) return 0;
+    const gap = parseFloat(getComputedStyle(this.track).columnGap) || 0;
+    return first.offsetWidth + gap;
   }
 
-  updateArrowStates() {
-    const trackWidth = this.track.offsetWidth;
-    const totalWidth = this.track.scrollWidth;
-    const scrollPosition = this.track.scrollLeft;
-    if (!this.leftArrow || !this.rightArrow) return;
-
-    this.leftArrow.classList.toggle("bd-disabled", scrollPosition <= 0);
-    this.rightArrow.classList.toggle(
-      "bd-disabled",
-      scrollPosition + trackWidth >= totalWidth - 1
-    );
+  /* How many stops the track has and which one it is at, from where it has
+     scrolled to -- by a control, a drag, a wheel or a keyboard. While a
+     control's smooth scroll is on its way, the dot it asked for stays current
+     rather than stepping through every stop it passes. */
+  _measure() {
+    if (!this.track) return;
+    const max = this.track.scrollWidth - this.track.clientWidth;
+    const step = this._step();
+    if (max <= 1 || step <= 0) {
+      this._pages = 1;
+      this._page = 1;
+      return;
+    }
+    this._pages = Math.ceil((max - 1) / step) + 1;
+    const left = this.track.scrollLeft;
+    const page = left >= max - 1 ? this._pages : Math.min(this._pages, Math.round(left / step) + 1);
+    if (this._seeking && page !== this._seeking) return;
+    this._seeking = 0;
+    this._page = page;
   }
 
-  _onArrowKeydown(e, arrow) {
-    if (e.key === "Enter" || e.key === " ") {
-      e.preventDefault();
-      arrow.click();
-    }
+  _goToPage(n) {
+    const max = this.track.scrollWidth - this.track.clientWidth;
+    const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+    this._seeking = n;
+    this._page = n;
+    this.track.scrollTo({
+      left    : Math.min((n - 1) * this._step(), max),
+      behavior: reduce ? "auto" : "smooth"
+    });
   }
 
   openModal(item) {
@@ -256,27 +261,18 @@ class CustomCarousel extends LitElement {
             </div>`
           : ""}
 
-        <img
-          src="left-arrow.svg"
-          alt="Left Arrow"
-          class="bd-arrow bd-left-arrow"
-          role="button"
-          aria-label="Scroll left"
-          @click="${() => this.scrollCarousel("left")}"
-          tabindex="0"
-        />
         <div class="bd-carousel-track">
           <slot></slot>
         </div>
-        <img
-          src="right-arrow.svg"
-          alt="Right Arrow"
-          class="bd-arrow bd-right-arrow"
-          role="button"
-          aria-label="Scroll right"
-          @click="${() => this.scrollCarousel("right")}"
-          tabindex="0"
-        />
+        <div class="bd-carousel-controls">
+          <bd-pagination-dots
+            count=${this._pages}
+            current=${this._page}
+            label=${this.title || "Slides"}
+            item-label="Go to item"
+            @bd-change=${e => this._goToPage(e.detail.current)}
+          ></bd-pagination-dots>
+        </div>
       </div>
 
       ${this.selectedItem

package/src/components/carousel/carousel.stories.js

@@ -10,7 +10,7 @@ export default {
         component: `
 **CustomCarousel** and **CarouselItem** are Lit components for a scrollable, draggable card carousel with modal support.
 
-- \`<bd-carousel-section>\` — scrollable container with left/right arrows and optional title
+- \`<bd-carousel-section>\` — scrollable container with optional title, and the package's slide dots (\`bd-pagination-dots\`) under the track
 - \`<bd-carousel-item>\` — individual card with icon, slotted content, and a \`+\` button to open a modal
 
 ### Usage
@@ -23,14 +23,15 @@ export default {
 \`\`\`
 
 ### Behavior
-- Left/right arrows scroll by one item width with smooth scroll
-- Arrows disable automatically at scroll boundaries
-- Click and drag (mouse + touch) supported for scrolling
+- One dot per scroll stop: a stop is one item's width plus the gap, and the last is wherever the track ends
+- A dot scrolls there smoothly (instantly under \`prefers-reduced-motion\`)
+- When every item fits, there is nowhere to go and no controls render
+- Click and drag (mouse + touch) supported for scrolling; the dots follow any scroll
 - Clicking \`+\` on an item fires \`open-modal\` custom event, caught by the carousel to show \`<bd-modal>\`
 - Modal closes via \`close-modal\` event
 
 ### Keyboard Support
-- Arrow buttons respond to Enter/Space
+- The dots are real buttons
 - \`+\` button on items responds to Enter/Space
         `
       }
@@ -84,7 +85,7 @@ export const Default = {
       ${sampleItems.map(renderItem)}
     </bd-carousel-section>
   `,
-  parameters: { docs: { description: { story: '6-item carousel with title. Scroll with arrows or drag.' } } }
+  parameters: { docs: { description: { story: '6-item carousel with title. Move with the dots under the track, or drag.' } } }
 };
 
 export const NoTitle = {
@@ -104,7 +105,7 @@ export const FewItems = {
       ${sampleItems.slice(0, 2).map(renderItem)}
     </bd-carousel-section>
   `,
-  parameters: { docs: { description: { story: 'Only 2 items — right arrow should be disabled if all items fit in view.' } } }
+  parameters: { docs: { description: { story: 'Only 2 items. When every item fits there is nowhere to scroll, so no dots render.' } } }
 };
 
 export const SingleItem = {
@@ -114,7 +115,7 @@ export const SingleItem = {
       ${renderItem(sampleItems[0])}
     </bd-carousel-section>
   `,
-  parameters: { docs: { description: { story: 'Edge case with a single item. Both arrows should be disabled.' } } }
+  parameters: { docs: { description: { story: 'Edge case with a single item: nothing to scroll, so no dots render.' } } }
 };
 
 export const NoIcon = {

package/src/components/checkbox/checkbox.css.js

@@ -40,7 +40,12 @@ export default css`
     /* the one focus ring — see Foundations/Focus. A two-colour ring whose
        white inner band keeps it visible on a coloured or dark surface, which a
        single-colour outline cannot do. */
-    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/code/code.css.js

@@ -62,7 +62,12 @@ export const codeCSS = css`
     /* the one focus ring — see Foundations/Focus. A two-colour ring whose
        white inner band keeps it visible on a coloured or dark surface, which a
        single-colour outline cannot do. */
-    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);
   }
 `;

package/src/components/code/code.js

@@ -1,4 +1,4 @@
-import { LitElement, html } from 'lit';
+import { LitElement, html, nothing } from 'lit';
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import '../../tokens/tokens.js';
 import { codeCSS } from './code.css.js';
@@ -17,20 +17,61 @@ export class BdCode extends LitElement {
     this.label = '';
   }
 
+  /* Whether the block is wider than its box. Only then is there anything to
+     scroll, and only then does it need to be a tab stop. The box changes
+     size with the page, and the content with the light DOM, so both are
+     watched. */
+  _measure() {
+    const pre = this.shadowRoot?.querySelector('pre');
+    const scrollable = !!pre && pre.scrollWidth > pre.clientWidth;
+    if (scrollable !== this._scrollable) {
+      this._scrollable = scrollable;
+      this.requestUpdate();
+    }
+  }
+
+  updated() {
+    const pre = this.shadowRoot.querySelector('pre');
+    if (pre && pre !== this._observed) {
+      this._resize?.disconnect();
+      this._resize = new ResizeObserver(() => this._measure());
+      this._resize.observe(pre);
+      this._observed = pre;
+    }
+    if (!pre) { this._resize?.disconnect(); this._observed = null; }
+    this._measure();
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._content = new MutationObserver(() => this._measure());
+    this._content.observe(this, { childList: true, characterData: true, subtree: true });
+  }
+
+  disconnectedCallback() {
+    this._content?.disconnect();
+    this._resize?.disconnect();
+    this._observed = null;
+    super.disconnectedCallback();
+  }
+
   render() {
     // Block mode nests <code> inside <pre>: <pre> carries the preformatted
     // whitespace, <code> carries "this is code". A bare <pre> is only
     // preformatted text, so assistive tech got no signal it was code at all,
     // even though the inline variant gave one.
     //
-    // The <pre> scrolls horizontally, and a scrollable region that cannot be
-    // focused cannot be scrolled from the keyboard (WCAG 2.1.1). tabindex
-    // makes it reachable; role and label give it something to announce, since
-    // a focusable element with no accessible name says nothing.
+    // A <pre> that scrolls horizontally has to be focusable, or it cannot be
+    // scrolled from the keyboard (WCAG 2.1.1), and a focusable element needs
+    // a name. It is a group, not a region: a named region is a landmark, so
+    // every code block on a page joined the landmark list a screen reader
+    // navigates by, beside header, main and footer. And it is a tab stop only
+    // while it overflows; a snippet that fits has nothing to scroll and was a
+    // stop that did nothing.
     return this.block
       ? html`<pre
-          tabindex="0"
-          role="region"
+          tabindex="${this._scrollable ? '0' : nothing}"
+          role="group"
           aria-label="${this.label || 'Code'}"
         ><code><slot></slot></code></pre>`
       : html`<code><slot></slot></code>`;

package/src/components/code/code.stories.js

@@ -33,10 +33,13 @@ Inline renders a single \`<code>\` with a tinted background. Block nests
 \`<code>\` carries "this is code", which is the spec's pairing for a code block.
 
 ### The block is keyboard-scrollable
-A long line scrolls horizontally, and a scrollable region that cannot be
-focused cannot be scrolled from the keyboard. The block therefore takes
-\`tabindex="0"\` with \`role="region"\` and an accessible name from \`label\`,
-defaulting to "Code", and shows a focus ring when reached by Tab.
+A long line scrolls horizontally, and a scrollable box that cannot be focused
+cannot be scrolled from the keyboard. So while the block is wider than its box
+it takes \`tabindex="0"\` and shows a focus ring when reached by Tab; a block
+that fits has nothing to scroll and is not a tab stop. It is a
+\`role="group"\` named by \`label\`, defaulting to "Code" — a group rather
+than a region, because a named region is a landmark, and a page of code
+samples would otherwise fill the landmark list a screen reader navigates by.
 
 ### Notes
 The inline variant sets its colour explicitly rather than inheriting, so it

package/src/components/divider/divider-horizontal.js

@@ -2,7 +2,7 @@ import { LitElement, html } from "lit";
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import "../../tokens/tokens.js";
 import { dividerHorizontal } from "./divider.css.js";
-import { borderColor } from "../shared/token-scales.js";
+import { borderColor, opacity } from "../shared/token-scales.js";
 
 export class BdDividerHorizontal extends LitElement {
   static styles = [dividerHorizontal];
@@ -27,7 +27,14 @@ export class BdDividerHorizontal extends LitElement {
        ask for `brand-subtle`. The ink vocabulary is still accepted as a
        fallback for the names already in the markup. */
     this.color = "";
-    this.opacity = "0.25";
+    /* No opacity by default. It was 0.25, laid over --color-border-default,
+       and that composite -- rgb(225,227,230), 1.286:1 on the page -- is
+       --color-border-container to within one unit (225,227,229, 1.287:1). So
+       every bare divider was spelling a role that exists by dimming a
+       different one. The stylesheet now draws that role at full strength,
+       which renders the same rule, and opacity is only what a caller asks
+       for. */
+    this.opacity = "";
   }
 
   render() {
@@ -35,13 +42,14 @@ export class BdDividerHorizontal extends LitElement {
     // stylesheet's --color-border-default stands rather than being overridden
     // with an empty value.
     const ink = borderColor(this.color);
+    const fade = opacity(this.opacity);
     return html`
       <hr
         class="hr-line"
         style="
           width: ${this.width};
           ${ink ? `border-top-color: ${ink};` : ''}
-          opacity: ${this.opacity};
+          ${fade ? `opacity: ${fade};` : ''}
         "
       />
     `;

package/src/components/divider/divider-vertical.js

@@ -2,7 +2,7 @@ import { LitElement, html } from "lit";
 // Installs the design tokens into document scope; see src/tokens/tokens.js
 import "../../tokens/tokens.js";
 import { dividerVertical } from "./divider.css.js";
-import { borderColor, spacing } from "../shared/token-scales.js";
+import { borderColor, spacing, opacity, borderWidth } from "../shared/token-scales.js";
 
 export class BdDividerVertical extends LitElement {
   static styles = [dividerVertical];
@@ -18,13 +18,19 @@ export class BdDividerVertical extends LitElement {
   constructor() {
     super();
     this.height = "16";   // a spacing step; was a 15px literal, off every scale
-    this.thickness = "1px";
+    /* A border-width step, resolved to var(--border-width-N); "1px" and the
+       other px spellings are read as their step. It was the literal "1px",
+       written into the style as given -- out of lint:tokens' reach, so any
+       length, or any string at all, could stand in for a hairline. An
+       unknown value falls back to the 1px step. */
+    this.thickness = "1";
     /* No colour by default — see the note in divider-horizontal.js. The
        stylesheet's --color-border-default is the role for a hairline; "subtle"
        was a text role that happened to resolve to the same step. The prop
        resolves through BORDER_ROLES first; see token-scales.js. */
     this.color = "";
-    this.opacity = "1.00";
+    // none by default, so none is written; a value is kept only from 0 to 1
+    this.opacity = "";
 
   }
 
@@ -32,14 +38,15 @@ export class BdDividerVertical extends LitElement {
     // See divider-horizontal.js: no colour means no declaration, so the
     // stylesheet's --color-border-default stands.
     const ink = borderColor(this.color);
+    const fade = opacity(this.opacity);
     return html`
       <div
         class="divider"
         style="
-          width: ${this.thickness};
+          width: ${borderWidth(this.thickness) || borderWidth('1')};
           height: ${spacing(this.height)};
           ${ink ? `background-color: ${ink};` : ''}
-          opacity: ${this.opacity};
+          ${fade ? `opacity: ${fade};` : ''}
         "
       ></div>
     `;

package/src/components/divider/divider.css.js

@@ -3,7 +3,10 @@ import { css } from "lit";
 export const dividerHorizontal = css`
   .hr-line {
     border: none;
-    border-top: var(--border-width-1) solid var(--color-border-default);
+    /* --color-border-container, the rule every bare divider already rendered:
+       it used to be --color-border-default dimmed to 0.25, which composites to
+       the same colour. See divider-horizontal.js. */
+    border-top: var(--border-width-1) solid var(--color-border-container);
     margin: 0;
     width: 100%;
     margin-left: auto;

package/src/components/divider/divider.stories.js

@@ -33,12 +33,12 @@ Two divider components are available:
       control    : { type: 'select' },
       options    : ['primary', 'strong', 'muted', 'subtle', 'inverse', 'success', 'warning', 'error'],
       description: '(Horizontal) A semantic colour role, not a CSS colour.',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: 'subtle' }, category: 'Horizontal' }
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "'' (--color-border-container)" }, category: 'Horizontal' }
     },
     hOpacity: {
       control    : 'text',
-      description: '(Horizontal) Opacity value between 0 and 1',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '0.25' }, category: 'Horizontal' }
+      description: '(Horizontal) Opacity from 0 to 1. Anything else is ignored. None by default.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Horizontal' }
     },
     height: {
       control: { type: 'select' },
@@ -49,8 +49,8 @@ Two divider components are available:
     },
     thickness: {
       control    : 'text',
-      description: '(Vertical) Width/thickness of the line e.g. "1px"',
-      table      : { type: { summary: 'string' }, defaultValue: { summary: '1px' }, category: 'Vertical' }
+      description: '(Vertical) A border-width step — 0, 1, 2, 3, 4 or 8, also written "1px" etc. Resolves to var(--border-width-N); anything else is the 1px step.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '1' }, category: 'Vertical' }
     },
     vColor: {
       control    : { type: 'select' },
@@ -71,7 +71,7 @@ Two divider components are available:
 export const HorizontalDefault = {
   name      : 'Horizontal — Default',
   render    : () => html`<bd-divider-horizontal></bd-divider-horizontal>`,
-  parameters: { docs: { description: { story: 'Default horizontal divider with default color and 0.25 opacity.' } } }
+  parameters: { docs: { description: { story: 'Default horizontal divider: --color-border-container at full strength, no opacity.' } } }
 };
 
 export const HorizontalFullWidth = {