@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/textarea/textarea.css.js

@@ -0,0 +1,51 @@
+import { css } from 'lit';
+
+/**
+ * What a textarea adds to the shared field chrome.
+ *
+ * Everything else — label, sizes, padding, radius, states, help text, focus
+ * ring — comes from shared/form-field.css.js, the same sheet bd-custom-input,
+ * bd-custom-dropdown and bd-custom-input-clipboard read.
+ *
+ * Only two things genuinely differ for a control that holds more than one
+ * line, and both are here rather than in the shared sheet so the other three
+ * are unaffected.
+ */
+export const textareaCSS = css`
+  /* 1. Height comes from the rows attribute, not from the size.
+
+     The shared sheet pins a height per size — that is what makes an input the
+     same height as a button of the same size — and applying it here would
+     collapse a four-row textarea to one line. The size still sets padding,
+     type step and radius, so the control still matches its siblings on every
+     axis where matching means anything.
+
+     Do not expect a rows="1" textarea to equal a one-line input: the two
+     compute height by different formulas and land about 6px apart at md.
+     Roughly 4px of that is the taller line box below, and the other 2px is
+     the borders — the shared sheet's fixed height is border-box, so its 1px
+     borders sit inside the number, while a height derived from rows adds them
+     on top. Closing the gap would mean forcing tight on a box of running
+     text, which is the one thing this component should not do. */
+  textarea.form-input-bd {
+    height: auto;
+    resize: vertical;
+  }
+
+  /* 2. line-height normal, not tight.
+
+     The shared sheet uses tight because a single-line field's height is
+     derived from it and because the select was clipping its own descenders.
+     Neither applies to a box of running text, where 1.25 is cramped to read
+     and 1.5 is the body-copy value the rest of the system sets. */
+  textarea.form-input-bd {
+    /* no role: the comment above this rule has the argument, and it is a
+       leading decision rather than a type role -- the size comes from the
+       field's own size step. 1.25 does not clip here (measured: 104/104 on
+       wrapped text), so this is a legibility call for a box of running text,
+       not a fix for a clipped box. */
+    line-height: var(--typography-lineHeight-normal);
+  }
+`;
+
+export default textareaCSS;

package/src/components/textarea/textarea.js

@@ -0,0 +1,136 @@
+import { LitElement, html, nothing } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { formFieldCSS } from '../shared/form-field.css.js';
+import { textareaCSS } from './textarea.css.js';
+import { resolveSize } from '../shared/prop-vocabulary.js';
+
+// ids are scoped to the shadow root, so fixed ones are safe here
+const TEXTAREA_ID = 'custom-textarea';
+const HELP_ID = 'custom-textarea-help';
+
+/**
+ * The fourth form control, and the one the shared-stylesheet work missed.
+ *
+ * bd-custom-input, bd-custom-dropdown and bd-custom-input-clipboard were
+ * collapsed onto shared/form-field.css.js; this one kept a stylesheet of its
+ * own and, with it, no size axis, no label, no help text and no validation
+ * states. It pinned the `md` radius and a fixed 16px type, so the Control
+ * Sizes story — which renders it in all three size rows under a caption that
+ * names it — showed it disagreeing with the other three at `sm` and `lg`.
+ *
+ * It now composes the same sheet and takes the same props, so a textarea and
+ * an input of the same size are the same control with a different number of
+ * lines.
+ */
+export class BdTextarea extends LitElement {
+  static styles = [formFieldCSS, textareaCSS];
+
+  static properties = {
+    label      : { type: String },
+    size       : { type: String, reflect: true },
+    value      : { type: String },
+    placeholder: { type: String },
+    rows       : { type: Number },
+    required   : { type: Boolean },
+    tooltip    : { type: String },
+    invalid    : { type: Boolean },
+    validated  : { type: Boolean, reflect: true },
+    disabled   : { type: Boolean, reflect: true },
+    name       : { type: String }
+  };
+
+  constructor() {
+    super();
+    this.label = '';
+    this.size = 'md';
+    this.value = '';
+    this.placeholder = '';
+    this.rows = 4;
+    this.required = false;
+    this.tooltip = '';
+    this.invalid = false;
+    this.validated = false;
+    this.disabled = false;
+    this.name = '';
+  }
+
+  willUpdate(changed) {
+    if (changed.has('size')) this.size = resolveSize(this.size);
+  }
+
+  /* The native event retargets to the host, which has no value property of its
+     own, so the host mirrors it — the same arrangement bd-custom-input uses.
+     `bd-input` keeps its original detail shape (the raw string) because
+     consumers already read it that way. */
+  _onInput(e) {
+    this.value = e.target.value;
+    this.dispatchEvent(new CustomEvent('bd-input', {
+      detail  : e.target.value,
+      bubbles : true,
+      composed: true
+    }));
+  }
+
+  _onChange(e) {
+    this.value = e.target.value;
+    this.dispatchEvent(new CustomEvent('bd-change', {
+      detail  : { value: this.value, name: this.name },
+      bubbles : true,
+      composed: true
+    }));
+  }
+
+  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];
+
+    const stateClass = this.disabled
+      ? 'form-input--disabled'
+      : this.invalid
+        ? 'form-input--error'
+        : this.validated
+          ? 'form-input--success'
+          : '';
+
+    const helpTextClass = this.invalid
+      ? 'form-help-text--error'
+      : this.validated
+        ? 'form-help-text--success'
+        : 'form-help-text--default';
+
+    return html`
+      <div class="input-container">
+        ${this.label
+          ? html`<label for="${TEXTAREA_ID}" class="form-label ${labelClass}">
+              ${this.label}
+              ${this.required
+                ? html`<span class="form-label__required" aria-hidden="true">*</span>`
+                : ''}
+            </label>`
+          : nothing}
+        <textarea
+          id="${TEXTAREA_ID}"
+          class="form-input-bd ${inputClass} ${stateClass}"
+          rows=${this.rows}
+          name="${this.name || nothing}"
+          placeholder=${this.placeholder || nothing}
+          ?required=${this.required}
+          ?disabled=${this.disabled}
+          aria-invalid="${this.invalid ? 'true' : nothing}"
+          aria-describedby="${this.tooltip ? HELP_ID : nothing}"
+          .value=${this.value}
+          @input=${this._onInput}
+          @change=${this._onChange}
+        ></textarea>
+        ${this.tooltip
+          ? html`<div id="${HELP_ID}" class="form-help-text ${helpTextClass}">
+              ${this.tooltip}
+            </div>`
+          : nothing}
+      </div>
+    `;
+  }
+}
+
+customElements.define('bd-textarea', BdTextarea);

package/src/components/textarea/textarea.stories.js

@@ -0,0 +1,191 @@
+import { html } from 'lit';
+import './textarea.js';
+import '../label/label.js';
+
+export default {
+  title     : 'Atoms/Textarea',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdTextarea** is a multi-line text field. It is the fourth control in the form
+family, alongside bd-custom-input, bd-custom-dropdown and
+bd-custom-input-clipboard, and it reads the same stylesheet as all three — so a
+textarea and an input of the same size are the same control with a different
+number of lines.
+
+### Usage
+\`\`\`html
+<bd-textarea label="What happened?" placeholder="Tell us more"></bd-textarea>
+<bd-textarea label="Notes" size="lg" rows="8"></bd-textarea>
+<bd-textarea label="Reason" required invalid tooltip="This field is required."></bd-textarea>
+<bd-textarea label="Summary" disabled value="Read only"></bd-textarea>
+
+<bd-textarea @bd-input=\${e => console.log(e.detail)}></bd-textarea>
+\`\`\`
+
+### Size
+\`size\` sets padding, type step and corner radius from the same
+\`--form-input-*\` aliases the other three controls read, so a textarea sits
+correctly in a row beside a button or an input of the same size.
+
+**Height is the exception.** The other three derive a fixed height from padding,
+type step and line-height — that is what keeps a field and a button the same
+height. A textarea's height comes from \`rows\` instead, because a fixed height
+would collapse it to one line. It also sets \`line-height: normal\` rather than
+\`tight\`: 1.25 is right for a single line whose height is derived from it, and
+cramped for a box of running text.
+
+### Label
+The field renders its own label when you pass one, with the same typography and
+the same 4px gap as bd-label — pick either, not both. Left empty, no label
+element is rendered at all, and the control is then **unlabelled**: a screen
+reader announces only "edit, multiline". Pair it with a label if you do not use
+the prop:
+
+\`\`\`html
+<bd-label id="msg-label">What happened?</bd-label>
+<bd-textarea aria-labelledby="msg-label"></bd-textarea>
+\`\`\`
+
+A \`placeholder\` is not a substitute. It disappears as soon as the user types,
+it is not reliably announced, and its contrast is set by the browser.
+
+### Not form-associated
+The \`<textarea>\` lives in this element's shadow root, so it does not
+participate in an outer \`<form>\`. \`name\` is carried on the events for your own
+submit handling; read the value from \`bd-input\`, \`bd-change\` or the \`value\`
+property.
+
+### Events
+\`bd-input\` — every keystroke, \`detail\` is the current value (a string).
+\`bd-change\` — on commit, \`detail\` is \`{ value, name }\`.
+
+The vertical resize handle is left enabled, so a user can grow the field beyond
+\`rows\`.
+        `
+      }
+    }
+  },
+  argTypes: {
+    label: {
+      control    : 'text',
+      description: 'The field\'s own label. Empty renders no label element.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Content' }
+    },
+    size: {
+      control    : { type: 'inline-radio' },
+      options    : ['sm', 'md', 'lg'],
+      description: 'Padding, type step and radius. Height comes from `rows`.',
+      table      : { type: { summary: "'sm'|'md'|'lg'" }, defaultValue: { summary: "'md'" }, category: 'Appearance' }
+    },
+    value: {
+      control    : 'text',
+      description: 'The text content.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Data' }
+    },
+    placeholder: {
+      control    : 'text',
+      description: 'Hint shown while empty. Not a replacement for a label.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Content' }
+    },
+    rows: {
+      control    : 'number',
+      description: 'Visible rows before scrolling. The user can still resize vertically.',
+      table      : { type: { summary: 'number' }, defaultValue: { summary: '4' }, category: 'Appearance' }
+    },
+    tooltip: {
+      control    : 'text',
+      description: 'Help text below the control, and the field\'s accessible description.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: "''" }, category: 'Content' }
+    },
+    required: {
+      control    : 'boolean',
+      description: 'Marks the field required and shows the asterisk on the label.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    invalid: {
+      control    : 'boolean',
+      description: 'Error tint and border, and `aria-invalid` on the control.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    validated: {
+      control    : 'boolean',
+      description: 'Success tint and border.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    },
+    disabled: {
+      control    : 'boolean',
+      description: 'Blocks editing.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'State' }
+    }
+  }
+};
+
+export const Default = () => html`
+  <bd-textarea label="What happened?" placeholder="Tell us what happened"></bd-textarea>
+`;
+
+export const Sizes = {
+  name  : 'All Sizes',
+  render: () => html`
+    <div style="display: grid; gap: var(--spacing-24); max-width: 24rem">
+      <bd-textarea size="sm" label="Small" rows="2" placeholder="sm"></bd-textarea>
+      <bd-textarea size="md" label="Medium" rows="2" placeholder="md"></bd-textarea>
+      <bd-textarea size="lg" label="Large" rows="2" placeholder="lg"></bd-textarea>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `Padding, type step and radius step with the size — 4px / 6px / 8px corners,
+matching a button or an input of the same size. Height stays with \`rows\`.`
+      }
+    }
+  }
+};
+
+export const States = {
+  name  : 'All Validation States',
+  render: () => html`
+    <div style="display: grid; gap: var(--spacing-24); max-width: 24rem">
+      <bd-textarea label="Default" rows="2" tooltip="A neutral hint."></bd-textarea>
+      <bd-textarea label="Required" rows="2" required tooltip="Tell us what happened."></bd-textarea>
+      <bd-textarea label="Invalid" rows="2" invalid tooltip="This field is required."></bd-textarea>
+      <bd-textarea label="Validated" rows="2" validated value="Looks good" tooltip="Thanks."></bd-textarea>
+      <bd-textarea label="Disabled" rows="2" disabled value="Cannot edit this"></bd-textarea>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `The same four state tints the other form controls use, from the same
+\`--form-input-*\` tokens. The help text takes the matching tone.`
+      }
+    }
+  }
+};
+
+export const Disabled = () => html`
+  <bd-textarea label="Summary" disabled value="Cannot edit this"></bd-textarea>
+`;
+
+export const NoLabel = {
+  name  : 'No label (pair it yourself)',
+  render: () => html`
+    <div style="max-width: 24rem">
+      <bd-label id="msg-label">What happened?</bd-label>
+      <bd-textarea aria-labelledby="msg-label" rows="3"></bd-textarea>
+    </div>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: `With no \`label\`, no label element is rendered — so the control is
+unlabelled unless you connect one. This is the composed alternative to the
+built-in label, and it should sit at the same rhythm as the built-in version.`
+      }
+    }
+  }
+};

package/src/components/tooltip/tooltip.css.js

@@ -0,0 +1,75 @@
+import { css } from 'lit';
+
+/** Styled entirely from design tokens — see npm run lint:tokens. */
+export const tooltipCSS = css`
+  :host { display: inline-block; position: relative; }
+
+  .bubble {
+    position: absolute;
+    bottom: calc(100% + var(--spacing-8));
+    left: 50%;
+    /* --bd-tooltip-shift is set by the component when the bubble would paint
+       outside the viewport, and is 0 the rest of the time. Centring alone
+       cannot stay on screen: the bubble is centred on its trigger and is wider
+       than it, so a trigger near an edge puts part of the bubble at negative x
+       whatever its width. Bounding the width in P6B reduced that overhang and
+       did not remove it -- the Default story measured 45px outside before and
+       after. There is no CSS that can read where the trigger sits. */
+    transform: translateX(calc(-50% + var(--bd-tooltip-shift, 0px)));
+    /* --z-tooltip is the top rung, and this is a real change: the bubble used
+       to sit on 1, which lost to anything raised above it in the same stacking
+       context. A tooltip opened from inside a dialog has to clear the dialog,
+       which is the reason the ladder puts it above --z-modal. */
+    z-index: var(--z-tooltip);
+    /* The bubble used to be white-space: nowrap with no width bound, so its
+       text became one line as long as the string: measured at 606px for the
+       LongText story, identical at 320 and at 1440, because a single line does
+       not care how much room it has. Anything past the container edge was
+       unreachable -- there is nothing to scroll to a bubble that is painted
+       outside the page box.
+
+       Bounded the way the anchor-nav dropdown panel bounds its own height:
+       min() of a viewport-relative value and a content cap, both from tokens.
+       --content-width-readable is the measure this package already uses for
+       "text somebody has to read". */
+    white-space: normal;
+    /* max-width has to mean the whole bubble, because what has to fit inside
+       the viewport is the box the reader sees. Without this the cap applied to
+       the content and the 4/8 padding was added outside it, so the border box
+       came out 16px wider than the number the min() had just worked out:
+       measured at 320, a cap of 288 produced a 304px bubble, and at 375 a cap
+       of 343 produced 359. The placement code then had 16px less room than the
+       stylesheet thought it had given it. */
+    box-sizing: border-box;
+    /* A single unbreakable token longer than the cap would otherwise paint
+       outside the bubble rather than wrap inside it. break-word only breaks
+       when there is no break opportunity, so ordinary prose is unaffected. */
+    overflow-wrap: break-word;
+    /* width: max-content is load-bearing. The bubble's containing block is the
+       host, which is only as wide as the trigger, so an absolutely positioned
+       bubble with left: 50% has half a trigger to lay out in: removing nowrap
+       without this collapsed the LongText bubble to 88px and eleven lines. */
+    width: max-content;
+    max-width: min(calc(100vw - var(--spacing-32)), var(--content-width-readable));
+    font-family: var(--typography-fontFamily-sans);
+    font-size: var(--typography-caption-default-fontSize);
+    line-height: var(--typography-caption-default-lineHeight);
+    color: var(--color-text-inverse);
+    background: var(--color-surface-inverse);
+    padding: var(--spacing-4) var(--spacing-8);
+    border-radius: var(--radius-sm);
+    box-shadow: var(--shadow-md);
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity var(--transition-duration-fast) var(--transition-easing-smooth);
+  }
+
+  :host(:hover) .bubble,
+  :host(:focus-within) .bubble { opacity: 1; }
+
+  @media (prefers-reduced-motion: reduce) {
+    .bubble { transition: none; }
+  }
+`;
+
+export default tooltipCSS;

package/src/components/tooltip/tooltip.js

@@ -0,0 +1,156 @@
+import { LitElement, html } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import { tooltipCSS } from './tooltip.css.js';
+
+export class BdTooltip extends LitElement {
+  static styles = [tooltipCSS];
+
+  static properties = {
+    text: { type: String }
+  };
+
+  constructor() {
+    super();
+    this.text = '';
+  }
+
+  /* The bubble is centred on its trigger and is wider than it, so near a
+     viewport edge part of it lands outside the page. No CSS can fix that --
+     the browser cannot be asked "where is my trigger" from a stylesheet -- so
+     the shift is measured here and handed back to CSS as a custom property.
+
+     Deliberately additive: --bd-tooltip-shift defaults to 0 in the stylesheet,
+     so a tooltip in a document where this never runs renders exactly as it did
+     before. getBoundingClientRect and ResizeObserver are both already used by
+     five components in this package; this is the same pattern, not a new one. */
+  /**
+   * The margin the bubble keeps from each viewport edge, read from the same
+   * token the stylesheet subtracts. The cap there is `100vw - --spacing-32`,
+   * which is that margin on each side, and the two numbers have to agree: the
+   * previous version clamped to a hard-coded 8 while the stylesheet reserved
+   * 16, so placement aimed at a boundary the width contract had not left room
+   * for.
+   */
+  _margin() {
+    const raw = getComputedStyle(this).getPropertyValue('--spacing-16');
+    const px = parseFloat(raw);
+    /* Tokens are installed in document scope and always resolve; the fallback
+       is for a disconnected element, where getComputedStyle returns nothing. */
+    return Number.isFinite(px) ? (raw.includes('rem') ? px * 16 : px) : 16;
+  }
+
+  /* The bubble is centred on its trigger and is wider than it, so near a
+     viewport edge part of it lands outside the page. No CSS can fix that --
+     the browser cannot be asked "where is my trigger" from a stylesheet -- so
+     the shift is measured here and handed back to CSS as a custom property.
+
+     Deliberately additive: --bd-tooltip-shift defaults to 0 in the stylesheet,
+     so a tooltip in a document where this never runs renders exactly as it did
+     before.
+
+     Both edges, not one. The previous version corrected whichever edge it
+     found outside first and stopped -- an `if` on the left and an `else if` on
+     the right -- which is only sound while the bubble is narrower than the
+     space between the margins. It was not: the border box ran 16px past its
+     own cap, so pushing the left edge in pushed the right edge out and the
+     `else if` never ran to notice.
+
+     Now the two constraints are solved together. For a shift s the bubble
+     lands at [left + s, right + s], and staying inside the margins means
+
+         s >= M - left        and        s <= V - M - right
+
+     so the centred position s = 0 is clamped into [minShift, maxShift]. With
+     box-sizing: border-box the bubble is at most V - 2M wide, which is exactly
+     the condition for that interval to be non-empty -- the width contract is
+     what makes the placement solvable, which is why the box model had to be
+     fixed first. */
+  _place() {
+    const bubble = this.renderRoot?.querySelector('.bubble');
+    if (!bubble) return;
+    bubble.style.setProperty('--bd-tooltip-shift', '0px');
+    const box = bubble.getBoundingClientRect();
+    if (box.width === 0) return;
+
+    const margin = this._margin();
+    const minShift = margin - box.left;
+    const maxShift = window.innerWidth - margin - box.right;
+
+    /* minShift > maxShift means the bubble is wider than the space between the
+       margins, which the width cap should prevent. If a consuming page has
+       overridden that cap, the left edge wins: the start of the text stays
+       readable rather than the end of it. */
+    const shift = minShift > maxShift
+      ? minShift
+      : Math.min(Math.max(0, minShift), maxShift);
+
+    bubble.style.setProperty('--bd-tooltip-shift', `${Math.round(shift)}px`);
+  }
+
+  /* Placement runs once the bubble has a box, not only when it is revealed.
+     The bubble is laid out at all times -- opacity: 0 hides it and
+     pointer-events: none takes it out of the way, but neither takes it out of
+     flow -- so an unplaced bubble on a trigger near the right edge widened the
+     document: measured at 1440, the right-edge bubble in Atoms/Tooltip "At the
+     viewport edges" ended at x=1622.5 and the page scrollWidth was 1623, a
+     183px horizontal scrollbar produced by something invisible.
+
+     This is not the placement-on-first-update that P7F tried and reverted.
+     That call ran the single-edge algorithm above on a content-box bubble, and
+     it moved the overflow rather than removing it -- 183px at the right edge
+     became 61px on Long Text at 320. Running it here is only correct because
+     the width contract and the clamp were fixed first; the ordering is the
+     fix, not the call site.
+
+     One pass here is not enough on its own, and the observer below is why.
+     Measured: this call alone left Long Text at 320 with shift 80px and 53px
+     of overflow, where placing again after everything had settled produced
+     shift 11px and none. The arithmetic was right both times -- the geometry
+     was not final the first time. */
+  firstUpdated() {
+    this._place();
+    /* The trigger is slotted light DOM and is usually a custom element of its
+       own, so it upgrades and takes its real width AFTER this tooltip has
+       rendered: the bubble is centred on a reference that has not finished
+       existing. Observing both boxes covers that, and the font swap and any
+       later content change with it, rather than guessing a delay.
+
+       Both boxes, because they move for different reasons: the host changes
+       when the trigger resizes, the bubble when its own text reflows.
+       ResizeObserver fires once on observe, which is the settled first pass. */
+    if (typeof ResizeObserver === 'undefined') return;
+    this._ro = new ResizeObserver(() => this._place());
+    this._ro.observe(this);
+    const bubble = this.renderRoot?.querySelector('.bubble');
+    if (bubble) this._ro.observe(bubble);
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this._onShow = () => this._place();
+    /* Both reveals the stylesheet already honours, and resize because the
+       measurement is only true for the width it was taken at. */
+    this.addEventListener('mouseenter', this._onShow);
+    this.addEventListener('focusin', this._onShow);
+    window.addEventListener('resize', this._onShow);
+  }
+
+  disconnectedCallback() {
+    this.removeEventListener('mouseenter', this._onShow);
+    this.removeEventListener('focusin', this._onShow);
+    window.removeEventListener('resize', this._onShow);
+    this._ro?.disconnect();
+    this._ro = undefined;
+    super.disconnectedCallback();
+  }
+
+  render() {
+    return html`
+      <slot></slot>
+      <span class="bubble" role="tooltip">${this.text}</span>
+    `;
+  }
+}
+
+customElements.define('bd-tooltip', BdTooltip);