@repobit/dex-system-design 0.25.11 → 0.26.0

package/src/components/tab-list/tab-list.js

@@ -0,0 +1,184 @@
+import { LitElement, html, nothing } from "lit";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
+
+/**
+ * The tab strip on its own — the row of buttons, the selected underline, and
+ * the WAI-ARIA tabs keyboard pattern. It owns no panel and no layout; the
+ * section that uses it decides what a panel is and how the page around it is
+ * arranged.
+ *
+ * ## Light DOM, on purpose
+ *
+ * `aria-controls` and `aria-labelledby` are IDREFs, and an IDREF does not
+ * resolve across a shadow boundary. A tab inside this element's shadow root
+ * therefore could not point at a panel living in the consumer's shadow root.
+ * Rendering into light DOM keeps the buttons in the same node tree as the
+ * panel, so the wiring is real rather than decorative.
+ *
+ * The consequence is that `static styles` would never apply. Import
+ * `tabListCSS` from ./tab-list.css.js and add it to the consuming component's
+ * own `static styles` instead.
+ *
+ * ## Two appearances, one control
+ *
+ * `appearance="switcher"` draws the Content Switcher: a pill track with the
+ * selected option on a white pill. It is a skin rather than its own element
+ * because everything below it -- role="tablist", role="tab", aria-selected,
+ * the roving tabindex and the Arrow/Home/End pattern with automatic
+ * activation -- is identical, and the light-DOM decision above is the whole
+ * reason this element exists. A separate <bd-content-switcher> would have had
+ * to re-solve the IDREF problem and keep a second copy of the keyboard
+ * pattern in step with this one.
+ *
+ * Storybook lists it as Components/Content Switcher so it is findable by the
+ * name it was designed under.
+ */
+export class BdTabList extends LitElement {
+  static properties = {
+    tabs      : { type: Array },
+    selected  : { type: Number, reflect: true },
+    label     : { type: String },
+    panelId   : { type: String, attribute: "panel-id" },
+    idPrefix  : { type: String, attribute: "id-prefix" },
+    /**
+     * The skin. Omitted gives the underlined strip this element has always
+     * drawn; "switcher" gives the pill-track content switcher. It is an
+     * appearance and not a second element on purpose -- see the note above
+     * the class for why.
+     */
+    appearance: { type: String, reflect: true }
+  };
+
+  // See the note above: light DOM is what makes the ARIA wiring work.
+  createRenderRoot() {
+    return this;
+  }
+
+  constructor() {
+    super();
+    this.tabs     = [];
+    this.selected = 0;
+    this.label    = "";
+    this.panelId  = "";
+    this.idPrefix = "bd-tab";
+  }
+
+  tabId(index) {
+    return `${this.idPrefix}-${index}`;
+  }
+
+  _select(index, { focus = false } = {}) {
+    if (index === this.selected) return;
+    this.selected = index;
+    this.dispatchEvent(new CustomEvent("bd-tab-select", {
+      detail  : { index },
+      bubbles : true,
+      composed: true
+    }));
+    if (focus) this.updateComplete.then(() => this._focusSelected());
+  }
+
+  /**
+   * The switcher's equal-width rule, which CSS alone cannot express.
+   *
+   * The design asks for every option to be as wide as the LONGEST label, so a
+   * translation cannot make one option wider than another. That needs three
+   * things at once -- the track hugs its content, the columns are equal, and
+   * the equal width is the widest option's -- and no grid declaration gives
+   * all three. Measured on the Unequal labels story: `1fr` produced 127.21 and
+   * 141.79 and wrapped both labels, and `minmax(max-content, 1fr)` produced
+   * 78.35 and 248.77. Both are correct CSS; an `fr` track needs definite free
+   * space to equalise, and a shrink-to-fit container has none -- and once the
+   * width IS definite, `fr` splits it evenly rather than matching the widest.
+   *
+   * So the widest option is measured and published as a custom property the
+   * grid reads. The property is cleared first: without that, a re-render after
+   * the labels get SHORTER would measure the widths this rule had already
+   * equalised and the track could never shrink again.
+   */
+  _sizeSwitcherOptions() {
+    if (this.appearance !== "switcher") return;
+    const track = this.querySelector(".bd-tabs-container");
+    const options = [...this.querySelectorAll(".bd-tab-button")];
+    if (!track || !options.length) return;
+
+    track.style.removeProperty("--bd-switcher-option-width");
+    const widest = Math.max(...options.map(o => o.getBoundingClientRect().width));
+    if (widest > 0) track.style.setProperty("--bd-switcher-option-width", `${widest}px`);
+  }
+
+  updated(changed) {
+    super.updated(changed);
+    this._sizeSwitcherOptions();
+  }
+
+  firstUpdated() {
+    /* The measurement is only as good as the font that was loaded when it ran.
+       IBM Plex arrives after first paint, and a fallback face has different
+       advance widths -- so a switcher measured on the fallback keeps a width
+       that no longer matches its own text. One re-measure once the faces are
+       in is enough; fonts.ready settles once per document. */
+    document.fonts?.ready.then(() => this._sizeSwitcherOptions());
+  }
+
+  _focusSelected() {
+    this.querySelector(`#${CSS.escape(this.tabId(this.selected))}`)?.focus();
+  }
+
+  /**
+   * Arrow keys move and activate in one step (automatic activation), which is
+   * the WAI-ARIA recommendation when revealing a panel is cheap — it is here,
+   * the panels are already in the DOM.
+   */
+  _onKeydown(event) {
+    const last = this.tabs.length - 1;
+    if (last < 0) return;
+
+    let next;
+    switch (event.key) {
+      case "ArrowRight": next = this.selected === last ? 0 : this.selected + 1; break;
+      case "ArrowLeft": next = this.selected === 0 ? last : this.selected - 1; break;
+      case "Home": next = 0; break;
+      case "End": next = last; break;
+      default: return;
+    }
+
+    event.preventDefault();
+    this._select(next, { focus: true });
+  }
+
+  render() {
+    return html`
+      <div
+        class="bd-tabs-container ${this.appearance === "switcher" ? "bd-tabs-container--switcher" : ""}"
+        role="tablist"
+        aria-label=${this.label || nothing}
+        @keydown=${this._onKeydown}
+      >
+        ${this.tabs.map((tab, index) => {
+          const isSelected = this.selected === index;
+          return html`
+            <button
+              type="button"
+              role="tab"
+              id=${this.tabId(index)}
+              aria-selected=${isSelected ? "true" : "false"}
+              aria-controls=${this.panelId || nothing}
+              tabindex=${isSelected ? "0" : "-1"}
+              class="bd-tab-button ${isSelected ? "bd-selected" : ""}"
+              @click=${() => this._select(index)}
+            >
+              ${tab.icon
+                ? html`<img src=${tab.icon} alt=${tab.iconAlt || ""} class="bd-tab-icon" />`
+                : ""}
+              <span class="bd-tab-label">${tab.content ?? tab.label}</span>
+            </button>
+          `;
+        })}
+      </div>
+    `;
+  }
+}
+
+customElements.define("bd-tab-list", BdTabList);

package/src/components/tab-list/tab-list.stories.js

@@ -0,0 +1,221 @@
+import { html } from "lit";
+import "../paragraph/paragraph.js";
+import "./tab-list.js";
+import { tabListCSS } from "./tab-list.css.js";
+
+/**
+ * The stories render <bd-tab-list> at document scope, where a component's
+ * `static styles` would not reach it anyway — see the note in tab-list.js on
+ * why this element is light DOM. Inside a real component you add `tabListCSS`
+ * to that component's own `static styles` instead of doing this.
+ */
+const withStyles = template => html`
+  <style>${tabListCSS.cssText}</style>
+  <div style="font-family: var(--typography-fontFamily-sans);">${template}</div>
+`;
+
+export default {
+  title     : "Components/Tab List",
+  tags      : ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+
+### This atom does not style itself
+
+\`bd-tab-list\` renders into **light DOM**, so its stylesheet is not adopted the
+way every other atom's is. Importing the element gets you the markup and the
+behaviour and nothing else — a consumer has to put \`tabListCSS\` into its own
+\`static styles\` ahead of any override:
+
+\`\`\`js
+import { tabListCSS } from '@repobit/dex-system-design/tab-list-css';
+
+static styles = [tabListCSS, myComponentCSS];
+\`\`\`
+
+That is deliberate — a tab strip has to sit inside its host's own layout and
+inherit its type — but it is the only atom that works this way, so it is worth
+saying plainly rather than leaving to be discovered.
+**BdTabList** is the tab strip on its own: the row of buttons, the selected
+underline, and the WAI-ARIA tabs keyboard pattern. It owns no panel and no
+surrounding layout — the section using it decides what a panel is.
+
+It was extracted from \`<bd-tabs>\`, \`<bd-tabs-component>\` and
+\`<bd-tabs-component-family>\`, which each hand-rolled the same strip. Those three
+now compose this one.
+
+### Usage
+\`\`\`js
+import "@repobit/dex-system-design/tab-list";
+import { tabListCSS } from "@repobit/dex-system-design/tab-list-css";
+
+static styles = [tabListCSS, myComponentCSS];
+\`\`\`
+
+\`\`\`js
+html\`
+  <bd-tab-list
+    .tabs=\${[{ label: "Windows" }, { label: "macOS" }]}
+    .selected=\${this.selectedTab}
+    id-prefix="tab-btn"
+    panel-id="tab-panel"
+    @bd-tab-select=\${e => this.selectTab(e.detail.index)}
+  ></bd-tab-list>
+
+  <div id="tab-panel" role="tabpanel" aria-labelledby="tab-btn-\${this.selectedTab}">
+    …
+  </div>
+\`
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`tabs\` | array of \`{ label, content?, icon?, iconAlt? }\` | \`[]\` |
+| \`selected\` | index of the active tab | \`0\` |
+| \`label\` | \`aria-label\` for the tablist | \`''\` |
+| \`panel-id\` | id of the panel every tab controls | \`''\` |
+| \`id-prefix\` | prefix for generated tab ids | \`'bd-tab'\` |
+
+\`content\` takes a Lit template and wins over \`label\` when both are set — it
+exists for strips whose label is richer than a string.
+
+### Events
+\`bd-tab-select\` — fires on selection with \`detail: { index }\`. It does not fire
+when the already-selected tab is clicked.
+
+### Light DOM
+\`aria-controls\` and \`aria-labelledby\` are IDREFs, and an IDREF does not resolve
+across a shadow boundary. If the buttons lived in this element's shadow root
+they could not point at a panel in the consuming component's shadow root, so
+this element renders into light DOM and the styles ship as an importable
+\`tabListCSS\` sheet.
+
+### Accessibility
+\`role="tablist"\` with \`role="tab"\` buttons, roving \`tabindex\` so the strip is a
+single tab stop, and arrow keys / Home / End moving between tabs with automatic
+activation. Every tab points at the panel via \`aria-controls\`; the panel points
+back via \`aria-labelledby\`.
+
+### Theming
+Component-local custom properties, all optional:
+\`--bd-tab-color\`, \`--bd-tab-color-selected\`, \`--bd-tab-border-color\`,
+\`--bd-tab-underline-color\`, \`--bd-tab-underline-height\`,
+\`--bd-tab-underline-duration\`, \`--bd-tab-padding\`, \`--bd-tab-padding-mobile\`,
+\`--bd-tab-gap\`, \`--bd-tab-font-size\`, \`--bd-tab-font-weight\`.
+`
+      }
+    }
+  }
+};
+
+const PLATFORMS = [
+  { label: "Windows" },
+  { label: "macOS" },
+  { label: "iOS" },
+  { label: "Android" }
+];
+
+/** A strip wired to a panel, which is how it is meant to be used. */
+export const Default = {
+  name  : "Default",
+  render: () => withStyles(html`
+    <bd-tab-list
+      .tabs=${PLATFORMS}
+      .selected=${0}
+      label="Platform"
+      id-prefix="demo-tab"
+      panel-id="demo-panel"
+      @bd-tab-select=${e => {
+        const panel = document.getElementById("demo-panel");
+        panel.textContent = `${PLATFORMS[e.detail.index].label} panel`;
+        panel.setAttribute("aria-labelledby", `demo-tab-${e.detail.index}`);
+      }}
+    ></bd-tab-list>
+    <div
+      id="demo-panel"
+      role="tabpanel"
+      aria-labelledby="demo-tab-0"
+      style="padding: var(--spacing-24) 0;"
+    >Windows panel</div>
+  `)
+};
+
+/** Selection can start anywhere; the strip does not assume the first tab. */
+export const PreSelected = {
+  name  : "Pre-selected tab",
+  render: () => withStyles(html`
+    <bd-tab-list .tabs=${PLATFORMS} .selected=${2} id-prefix="pre-tab"></bd-tab-list>
+  `)
+};
+
+/** An optional icon per tab. Sizing stays with the consuming section. */
+export const WithIcons = {
+  name  : "With icons",
+  render: () => withStyles(html`
+    <style>.bd-tab-icon { width: 28px; height: 28px; object-fit: contain; }</style>
+    <bd-tab-list
+      id-prefix="icon-tab"
+      .tabs=${[
+        { label: "Admin", icon: "/assets/pic1.png", iconAlt: "" },
+        { label: "Adult", icon: "/assets/pic2.png", iconAlt: "" },
+        { label: "Teen", icon: "/assets/pic3.png", iconAlt: "" }
+      ]}
+    ></bd-tab-list>
+  `)
+};
+
+/** `content` replaces `label` when the strip needs richer markup. */
+export const RichLabels = {
+  name  : "Rich labels (content)",
+  render: () => withStyles(html`
+    <bd-tab-list
+      id-prefix="rich-tab"
+      .tabs=${PLATFORMS.map(p => ({
+        content: html`<bd-p variant="small"><strong>${p.label}</strong></bd-p>`
+      }))}
+    ></bd-tab-list>
+  `)
+};
+
+/** Every knob moved off its default at once, to show what is themeable. */
+export const Themed = {
+  name  : "Themed via custom properties",
+  render: () => withStyles(html`
+    <div style="
+      --bd-tab-color: var(--color-neutral-700);
+      --bd-tab-color-selected: var(--color-green-700);
+      --bd-tab-underline-color: var(--color-green-700);
+      --bd-tab-underline-height: var(--border-width-4);
+      --bd-tab-padding: var(--spacing-12) var(--spacing-32);
+      --bd-tab-border-color: var(--color-neutral-50);
+    ">
+      <bd-tab-list .tabs=${PLATFORMS} .selected=${1} id-prefix="themed-tab"></bd-tab-list>
+    </div>
+  `)
+};
+
+/**
+ * Tab, then arrow keys. The strip is one tab stop and arrows move within it —
+ * the behaviour none of the three sections had before the extraction.
+ */
+export const KeyboardNavigation = {
+  name  : "Keyboard navigation",
+  render: () => withStyles(html`
+    <p style="font-family: var(--typography-fontFamily-sans);">
+      Focus the strip with <kbd>Tab</kbd>, then use <kbd>←</kbd> <kbd>→</kbd>
+      <kbd>Home</kbd> <kbd>End</kbd>.
+    </p>
+    <bd-tab-list .tabs=${PLATFORMS} label="Platform" id-prefix="kbd-tab"></bd-tab-list>
+  `)
+};
+
+/** A single tab still renders a valid tablist. */
+export const SingleTab = {
+  name  : "Single tab (edge case)",
+  render: () => withStyles(html`
+    <bd-tab-list .tabs=${[{ label: "Only one" }]} id-prefix="single-tab"></bd-tab-list>
+  `)
+};

package/src/components/tabs/tabs.css.js

@@ -2,7 +2,6 @@ import { css } from "lit";
 
 export default css`
   :host {
-    --bd-accesibility-focus: var(--color-blue-500);
     font-size: 100%;
     display: block;
     font-family: var(--typography-fontFamily-sans);
@@ -17,8 +16,6 @@ export default css`
     display: flex;
     flex-direction: column;
     align-items: center;
-    max-width: 1290px;
-    margin-inline: auto;
     box-sizing: border-box;
   }
 
@@ -38,13 +35,8 @@ export default css`
     margin-bottom: var(--spacing-32);
   }
 
-  /* Tab buttons row */
-  .bd-tabs-container {
-    display: inline-flex;
-    justify-content: center;
-    flex-wrap: wrap;
-    border-bottom: 1px solid var(--color-neutral-100);
-  }
+  /* The tab strip itself lives in Components/Tab List (tabListCSS, included in
+     static styles above). Only this section's own layout stays here. */
 
   /* Panel — full width, fara padding inline */
   .bd-panel-wrapper {
@@ -52,118 +44,17 @@ export default css`
     box-sizing: border-box;
   }
 
-  .bd-tab-button {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    background: none;
-    border: none;
-    padding: var(--spacing-10) var(--spacing-16);
-    cursor: pointer;
-    color: var(--color-blue-500);
-    position: relative;
-    font-family: var(--typography-fontFamily-sans);
-    font-size: var(--typography-body-large-fontSize);
-    font-weight: var(--typography-fontWeight-semibold);
-    transition: color var(--transition-duration-fast) var(--transition-easing-smooth);
-  }
-
-  .bd-tab-button::after {
-    content: "";
-    height: 3px;
-    background: var(--color-blue-500);
-    position: absolute;
-    left: 0;
-    bottom: 0;
-    width: 0;
-    transition: width var(--transition-duration-slow) var(--transition-easing-smooth);
-  }
-
-  .bd-tab-button.bd-selected::after {
-    width: 100%;
-  }
-
-  .bd-tab-button.bd-selected {
-    color: var(--color-neutral-900);
-    font-weight: var(--typography-fontWeight-semibold);
-  }
-
-  .bd-tab-button:focus-visible {
-    outline: 2px solid var(--bd-accesibility-focus);
-    outline-offset: 2px;
-    border-radius: var(--radius-sm);
-  }
-
-  .bd-tab-label {
-    pointer-events: none;
-  }
-
-  /* Columns grid */
-  .bd-columns-container {
-    display: grid;
-    gap: var(--spacing-32);
-    width: 100%;
-    justify-content: center;
-  }
-
-  /* Coloana individuala */
-  .bd-col {
-    display: flex;
-    flex-direction: column;
-    width: 300px;
-  }
-
-  /* Icon wrapper */
-  .col-icon-wrapper {
-    display: flex;
-    align-items: flex-start;
-    margin-bottom: var(--spacing-8);
-    overflow: hidden;
-  }
-
-  /* Title wrapper */
-  .col-title-wrapper {
-    display: flex;
-    align-items: flex-start;
-    margin-bottom: var(--spacing-8);
-    overflow: hidden;
-  }
-
-  .col-title {
-    font-family: var(--typography-fontFamily-sans);
-    font-size: var(--typography-fontSize-2xl);
-    font-weight: var(--typography-fontWeight-bold);
-    color: var(--color-neutral-900);
-    line-height: var(--typography-lineHeight-normal);
-  }
-
-  .col-description {
-    margin-bottom: var(--spacing-16);
-    font-family: var(--typography-fontFamily-sans);
-    font-size: var(--typography-fontSize-md);
-    color: var(--color-neutral-700);
-    line-height: var(--typography-lineHeight-normal);
-    overflow: hidden;
-  }
+  /* No column rules. A tab panel's columns are bd-features' -- every panel in
+     every story wraps its content in <bd-features>, which renders .bd-col,
+     .col-icon-wrapper, .col-title-wrapper, .col-title and .col-description
+     into its own shadow root and styles them from features.css.js. A copy of
+     six of those selectors stood here and could not reach across that
+     boundary: measured 0 matches for every one of them across 9 bd-tabs shadow
+     roots in 604 built stories.
 
-  /* Responsive */
-  @media (max-width: 992px) {
-    .bd-col {
-      width: 260px;
-    }
-  }
-
-  @media (max-width: 600px) {
-    .bd-col {
-      width: 100%;
-    }
-
-    .bd-tabs-container {
-      gap: var(--spacing-4);
-    }
-
-    .bd-tab-button {
-      padding: var(--spacing-8) var(--spacing-12);
-    }
-  }
+     Two recorded findings went with them, and neither was a question about
+     tabs. The 24px/1.5 column title in scripts/typography-pairings.json was
+     this file's .col-title, so the pairing it recorded rendered nowhere; and
+     the two responsive widths were this file's entries in the lg and 600
+     column groups, where bd-features carries the live ones. */
 `;

package/src/components/tabs/tabs.js

@@ -1,11 +1,15 @@
 import { LitElement, html } from "lit";
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import "../../tokens/tokens.js";
 import { keyed } from "lit/directives/keyed.js";
-import { tokens } from "../../tokens/tokens.js";
 import "../features/features.js";
 import "../heading/heading.js";
 import "../highlight/highlight.js";
 import "../paragraph/paragraph.js";
+import "../tab-list/tab-list.js";
+import { tabListCSS } from "../tab-list/tab-list.css.js";
 import tabsCSS from "./tabs.css.js";
+import { ensembleCSS } from "../shared/ensemble.css.js";
 
 class BdTabPanel extends LitElement {
   static styles = [];
@@ -25,7 +29,7 @@ class BdTabs extends LitElement {
     _panelMinHeight: { type: Number, state: true },
     bgBlue         : { type: Boolean, reflect: true, attribute: "bg-blue" }  };
 
-  static styles = [tokens, tabsCSS];
+  static styles = [ensembleCSS, tabListCSS, tabsCSS];
 
   constructor() {
     super();
@@ -78,33 +82,26 @@ class BdTabs extends LitElement {
     const activePanel = panels[this.selectedTab];
 
     return html`
-      <div class="bd-tabs-component">
+      <div class="bd-ensemble bd-tabs-component">
 
         ${this.title
           ? html`<bd-highlight highlight-text="${this.highlightText}">${this.title}</bd-highlight>`
           : ""}
 
         ${this.subtitle
-          ? html`<bd-p kind="large" class="bd-tabs-subtitle">${this.subtitle}</bd-p>`
+          ? html`<bd-p variant="large" class="bd-tabs-subtitle">${this.subtitle}</bd-p>`
           : ""}
 
-        <div class="bd-tabs-container" role="tablist">
-          ${panels.map((panel, index) => html`
-            <button
-              role="tab"
-              aria-selected="${this.selectedTab === index ? "true" : "false"}"
-              aria-controls="tab-panel-${index}"
-              id="tab-btn-${index}"
-              class="bd-tab-button ${this.selectedTab === index ? "bd-selected" : ""}"
-              @click=${() => this.selectTab(index)}
-            >
-              <span class="bd-tab-label">${panel.getAttribute("title")}</span>
-            </button>
-          `)}
-        </div>
+        <bd-tab-list
+          .tabs=${panels.map(panel => ({ label: panel.getAttribute("title") }))}
+          .selected=${this.selectedTab}
+          id-prefix="tab-btn"
+          panel-id="tab-panel"
+          @bd-tab-select=${e => this.selectTab(e.detail.index)}
+        ></bd-tab-list>
 
         <div
-          id="tab-panel-${this.selectedTab}"
+          id="tab-panel"
           role="tabpanel"
           aria-labelledby="tab-btn-${this.selectedTab}"
           class="bd-panel-wrapper"