@repobit/dex-system-design 0.25.12 → 0.26.0

package/src/components/alert/alert.css.js

@@ -0,0 +1,198 @@
+import { css } from 'lit';
+
+/**
+ * Styled entirely from design tokens -- see npm run lint:tokens.
+ *
+ * Reshaped 2026-09-14 to the Eclipse Alert banner (Figma yzCimjlQG7RzokkgVpjfnZ
+ * node 5021:11630), using this package's roles rather than that file's
+ * variables. The two systems turn out to share ancestry: three of the five
+ * tints matched byte-for-byte (blue f0f7ff, green edfdf1, red fff0f0), the type
+ * size matched at 14px, and the radius, gaps and padding all landed on our
+ * existing scales -- radius/small 8px IS --radius-lg, and 16/12/8 are
+ * --spacing-16/12/8.
+ *
+ * Two places the design and this package disagree, both resolved our way
+ * because our tokens are the brief:
+ *
+ *   warning tint   the design is fff6f0, an orange; --status-warning-surface is
+ *                  fffbf0, a yellow. Ours. Worth knowing that warning is the
+ *                  tightest of the six: its accent reads 3.49:1 on its own
+ *                  tint where every other tone clears 4.2, so a future change
+ *                  to either half has least room here.
+ *   actions ink    the design is 0045ad; --color-text-brand is blue-600
+ *                  0059d6. Ours, and blue-600 is the documented choice for ink
+ *                  on a tint -- CLAUDE.md records blue-500 as failing there.
+ *
+ * THE LEFT ACCENT RULE IS GONE. This atom carried a 4px border-left in the
+ * tone's accent colour; the design is tint-only, with a full border on the
+ * outline variant instead. That is a visible change to a shipped atom and it
+ * was asked for. The invariant the old rule existed to keep -- that an alert
+ * and a bd-badge of the same tone are the same colour by construction, because
+ * both read --status-<tone>-accent -- survives, because the icon now carries
+ * it.
+ *
+ * EVERY COMBINATION WAS MEASURED, not assumed: title and description
+ * (--color-text-primary) run 16.03 to 17.97:1 across the six grounds, the
+ * actions ink 5.51 to 6.18, and the tone accents 3.49 to 8.39 against the 3:1
+ * non-text bar. No pair needed a compromise.
+ */
+export const alertCSS = css`
+  :host {
+    display: block;
+  }
+
+  /* The native hidden attribute has to beat the display above, or a consumer
+     writing <bd-alert hidden> gets a visible alert. Same fix as
+     icons/icon-element.js. */
+  :host([hidden]) {
+    display: none;
+  }
+
+  .alert {
+    display: flex;
+    align-items: flex-start;
+    gap: var(--spacing-12);
+    padding: var(--spacing-16);
+    border-radius: var(--radius-lg);
+    font-family: var(--typography-fontFamily-sans);
+    /* Set ONCE, here. The title differs from the description by weight only,
+       which is what the design does too -- Body/medium/semibold over
+       Body/medium/regular, both 14px -- so nothing below re-declares a size.
+       .
+       THE LEADING IS DELIBERATELY NOT THE DESIGN'S. The design specifies 20px;
+       this resolves to 1.45, which computes to 20.3px at 14px. Confirmed 2026-09-14
+       to stay as it is: a unitless ratio is the first rule of this package's
+       typography contract, because an absolute 20px stops scaling when a reader
+       enlarges their text, which is the defect the rule exists to prevent. The
+       0.3px is the price of keeping it. 1.45 also clears the Plex leading floor
+       that Romanian diacritics need, so there is no clipping risk in dropping
+       toward the design's figure -- but there is no reason to. */
+    font-size: var(--typography-body-small-fontSize);
+    line-height: var(--typography-body-small-lineHeight);
+    color: var(--color-text-primary);
+    background: var(--status-info-surface);
+  }
+
+  /* The tone sets the ground and the icon's ink in one place, so the two cannot
+     drift apart. The icon reads currentColor from .icon, which is the rule the
+     icon atoms already follow. */
+  .icon {
+    flex: none;
+    display: flex;
+    color: var(--status-info-accent);
+  }
+
+  :host([tone='success']) .alert {
+    background: var(--status-success-surface);
+  }
+
+  :host([tone='success']) .icon {
+    color: var(--status-success-accent);
+  }
+
+  :host([tone='warning']) .alert {
+    background: var(--status-warning-surface);
+  }
+
+  :host([tone='warning']) .icon {
+    color: var(--status-warning-accent);
+  }
+
+  :host([tone='error']) .alert {
+    background: var(--status-error-surface);
+  }
+
+  :host([tone='error']) .icon {
+    color: var(--status-error-accent);
+  }
+
+  :host([tone='neutral']) .alert {
+    background: var(--status-neutral-surface);
+  }
+
+  :host([tone='neutral']) .icon {
+    color: var(--status-neutral-accent);
+  }
+
+  /* The outline variant is a SURFACE treatment, not a tone: it keeps whichever
+     tone's icon is set and drops the tint for the page ground plus an edge.
+     That is why it is its own attribute rather than a sixth tone -- the design
+     models both axes in one enum, and folding a surface choice into the status
+     vocabulary is the category error CLAUDE.md names.
+     .
+     The edge takes --color-border-container, the role for a self-contained
+     object's boundary, which is what this is. The design spells it
+     rgba(0,0,0,0.1); the role is neutral-100 and within a shade of it. */
+  :host([variant='outline']) .alert {
+    background: var(--color-surface-default);
+    border: var(--border-width-1) solid var(--color-border-container);
+  }
+
+  .content {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-8);
+    overflow-wrap: break-word;
+  }
+
+  /* no role: the title's weight. Semibold at 14px is not a role this package
+     has -- body-small is 400, label-default and control-label-default are 500 --
+     and the element is doing the work a role would name. It stays a strong so
+     the emphasis is in the markup rather than in a class, which is the same
+     argument button.css.js's .button--bold makes.
+     .
+     The value is deliberate and not the UA default: strong renders at bolder
+     (700), and semibold keeps an alert title from shouting inside a status
+     strip. The design agrees -- Body/medium/semibold. */
+  .title { font-weight: var(--typography-fontWeight-semibold); }
+
+  /* The design gives the description a 24px floor so a one-line alert has the
+     same height as the icon beside it and the row does not look top-heavy. */
+  .body {
+    min-height: var(--icon-lg-size);
+  }
+
+  /* Each action is its own flex item, so the gap needs each one slotted
+     separately -- wrapping several in one span makes them a single item and
+     they run together with no space. The stories show the right shape.
+     .
+     The colour here is a DEFAULT, not the source of the action ink: bd-link
+     and bd-button both set their own, so in normal use this never paints. It
+     is kept so a bare anchor or a run of text slotted here gets brand ink
+     rather than the UA's blue, which is the only case it applies to. Do not go
+     looking here for why an action is the colour it is -- look at the atom. */
+  .actions {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--spacing-12);
+    color: var(--color-text-brand);
+  }
+
+  /* Rendered only when something is slotted in, so an alert without actions
+     does not carry an empty row and the gap above it. */
+  .actions[hidden] {
+    display: none;
+  }
+
+  .dismiss {
+    flex: none;
+    display: flex;
+    padding: var(--spacing-0);
+    border: none;
+    background: none;
+    color: var(--color-text-muted);
+    border-radius: var(--focus-outline-radius);
+    cursor: pointer;
+  }
+
+  /* One token, one painter -- the same invariant accordion.css.js records. */
+  .dismiss:focus-visible {
+    outline: none;
+    box-shadow: var(--focus-outline-primary);
+  }
+`;
+
+export default alertCSS;

package/src/components/alert/alert.js

@@ -0,0 +1,103 @@
+import { LitElement, html, nothing } from 'lit';
+// Installs the design tokens into document scope; see src/tokens/tokens.js
+import '../../tokens/tokens.js';
+import '../icons/circle-info-icon.js';
+import '../icons/close-icon.js';
+import { alertCSS } from './alert.css.js';
+
+/**
+ * A status banner: an icon, a title, a description, optional actions, and an
+ * optional dismiss.
+ *
+ * Shaped to the Eclipse Alert banner (Figma yzCimjlQG7RzokkgVpjfnZ node
+ * 5021:11630) with this package's roles. See alert.css.js for what the two
+ * systems agreed on and the two places they did not.
+ *
+ * TWO AXES, NOT ONE. The design models six values of a single `type` enum:
+ * Information, Success, Danger, Warning, Neutral and Outline. Five of those are
+ * statuses and one is a surface treatment, so this element keeps them apart --
+ * `tone` for the status, `variant` for the treatment. An outline alert still
+ * has a tone, and folding the two into one attribute would mean
+ * tone="outline", which says nothing about what the alert is telling you.
+ *
+ * THE LEADING ICON. bd-circle-info-icon, the glyph the design asked for. It
+ * was a bd-missing-icon placeholder from the day this component was built --
+ * a visible dashed box that check:icons reported as owed -- which is the
+ * recorded process for an icon we need and have not drawn: no font glyph, no
+ * inline path, no silent omission. The artwork arrived from Eclipse and the
+ * placeholder is gone. Pass your own through the icon slot to override it.
+ */
+export class BdAlert extends LitElement {
+  static styles = [alertCSS];
+
+  static properties = {
+    /** info | success | warning | error | neutral */
+    tone        : { type: String, reflect: true },
+    /** tint (default) | outline */
+    variant     : { type: String, reflect: true },
+    heading     : { type: String },
+    dismissible : { type: Boolean, reflect: true },
+    /** The dismiss button's accessible name, overridable per context. */
+    dismisslabel: { type: String },
+    _hasActions : { state: true }
+  };
+
+  constructor() {
+    super();
+    this.tone = 'info';
+    this.variant = 'tint';
+    this.heading = '';
+    this.dismissible = false;
+    this.dismisslabel = 'Dismiss alert';
+    this._hasActions = false;
+  }
+
+  /* The actions row is only rendered when something is slotted into it, so an
+     alert without actions does not carry an empty row and the gap above it.
+     Read from the slot rather than from a querySelector at render time, so it
+     stays right when a consumer adds or removes actions later. */
+  _onActionsSlotChange(event) {
+    this._hasActions = event.target.assignedNodes({ flatten: true })
+      .some(n => n.nodeType === Node.ELEMENT_NODE || n.textContent.trim());
+  }
+
+  _onDismiss() {
+    /* The element does not remove itself: what should happen to the space it
+       occupied is the page's decision, not the atom's. */
+    this.dispatchEvent(new CustomEvent('bd-dismiss', { bubbles: true, composed: true }));
+  }
+
+  render() {
+    return html`
+      <div class="alert" role=${this.tone === 'error' ? 'alert' : 'status'}>
+        <span class="icon">
+          <slot name="icon">
+            <bd-circle-info-icon size="lg"></bd-circle-info-icon>
+          </slot>
+        </span>
+
+        <div class="content">
+          ${this.heading ? html`<strong class="title">${this.heading}</strong>` : nothing}
+          <div class="body"><slot></slot></div>
+          <div class="actions" ?hidden=${!this._hasActions}>
+            <slot name="actions" @slotchange=${this._onActionsSlotChange}></slot>
+          </div>
+        </div>
+
+        ${this.dismissible
+          ? html`
+            <button
+              class="dismiss"
+              type="button"
+              aria-label=${this.dismisslabel}
+              @click=${this._onDismiss}
+            >
+              <bd-close-icon size="sm"></bd-close-icon>
+            </button>`
+          : nothing}
+      </div>
+    `;
+  }
+}
+
+customElements.define('bd-alert', BdAlert);

package/src/components/alert/alert.stories.js

@@ -0,0 +1,206 @@
+import { html } from 'lit';
+import './alert.js';
+import '../link/link.js';
+
+export default {
+  title     : 'Atoms/Alert',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**BdAlert** is an inline message about the state of something on the page. It
+belongs in the flow, next to whatever it describes — it is not a toast or a
+dialog.
+
+### Usage
+\`\`\`html
+<bd-alert>Your subscription renews on 12 March.</bd-alert>
+<bd-alert tone="success" heading="Payment received">A receipt is on its way.</bd-alert>
+<bd-alert tone="error" heading="Card declined">Check the expiry date and try again.</bd-alert>
+
+<bd-alert variant="outline" heading="On a tinted page">
+  Drops the tint for the page ground and an edge.
+</bd-alert>
+
+<bd-alert tone="warning" heading="Two devices are out of date." dismissible>
+  Windows Defender is still handling protection on them.
+  <bd-link inline slot="actions" href="#">Review devices</bd-link>
+</bd-alert>
+\`\`\`
+
+### Props
+| Prop | Values | Default |
+|---|---|---|
+| \`tone\` | \`info\`, \`success\`, \`warning\`, \`error\`, \`neutral\` | \`info\` |
+| \`variant\` | \`tint\`, \`outline\` | \`tint\` |
+| \`heading\` | any string — omit for a description-only alert | \`''\` |
+| \`dismissible\` | boolean — adds a close button | \`false\` |
+| \`dismisslabel\` | the close button's accessible name | \`Dismiss alert\` |
+
+### Slots
+| Slot | For |
+|---|---|
+| *(default)* | the description. Carries markup, such as a link |
+| \`icon\` | replaces the leading icon |
+| \`actions\` | one or more actions under the description. Collapses when empty. **Each action is its own slotted element** — wrapping several in one span makes them a single flex item and they lose the gap between them |
+
+### Slotted links need \`inline\`
+A \`bd-link\` without \`inline\` is a **standalone** link and sets its own size:
+\`--typography-link-standalone-fontSize\` is \`1rem\`, where this alert's prose is
+\`body-small\` at \`0.875rem\`. Dropped into an alert it renders 16px inside 14px
+text, with a taller line box that pushes the surrounding line apart.
+
+\`inline\` selects \`--typography-link-default-*\`, which is \`inherit\` for both
+size and leading — deliberately, per typography rule 10 in CLAUDE.md: a link
+inside a sentence sits in that sentence's line box. The same applies to an
+action, which should match the alert it belongs to rather than assert a size of
+its own.
+
+The alert **cannot** fix this for you. \`::slotted(bd-link)\` sets properties on
+the host, and the link's own shadow rule sets \`font-size\` on the element
+inside it, so the host never wins. The attribute is the only lever.
+
+### Two axes, not one
+The Figma source models six values of a single \`type\`: five statuses plus
+\`Outline\`. Outline is a **surface treatment**, not a status — an outline alert
+still needs to say whether it is an error — so the two are separate attributes
+here. \`tone="outline"\` would tell a reader nothing about what the alert means.
+
+### The leading icon is a placeholder
+The design's glyph is a circle-info, which this package has not drawn. The
+default is therefore \`bd-missing-icon\` — a visible dashed box that
+\`npm run check:icons\` reports as owed. Pass real artwork through the \`icon\`
+slot to override it.
+
+### Accessibility
+Only \`error\` gets \`role="alert"\`, which interrupts a screen reader. Every other
+tone gets \`role="status"\`, announced politely when the user is idle.
+
+That means **\`warning\` is announced politely, not urgently.** If a warning in
+your context is time-critical, that is worth revisiting — the split is
+currently error-only.
+
+The tone is never the only signal: the heading and the description carry the
+meaning too, so the alert still works for anyone who cannot distinguish the
+tint. Every pairing was measured rather than assumed — the ink runs 16.03 to
+17.97:1 across the six grounds, the actions ink 5.51 to 6.18, and the tone
+accents 3.49 to 8.39 against the 3:1 non-text bar.
+
+\`dismissible\` emits \`bd-dismiss\` and does **not** remove the element: what
+happens to the space it occupied is the page's decision, not the atom's.
+        `
+      }
+    }
+  },
+  argTypes: {
+    tone: {
+      control    : { type: 'select' },
+      options    : ['info', 'success', 'warning', 'error', 'neutral'],
+      description: 'Which kind of message this is. Only `error` announces urgently.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'info' }, category: 'Appearance' }
+    },
+    variant: {
+      control    : { type: 'select' },
+      options    : ['tint', 'outline'],
+      description: 'A surface treatment, independent of the tone. `outline` drops the tint for the page ground and an edge.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'tint' }, category: 'Appearance' }
+    },
+    heading: {
+      control    : 'text',
+      description: 'Optional title, on its own line above the description.',
+      table      : { type: { summary: 'string' }, defaultValue: { summary: '' }, category: 'Content' }
+    },
+    dismissible: {
+      control    : 'boolean',
+      description: 'Adds a close button that emits `bd-dismiss`. The element does not remove itself.',
+      table      : { type: { summary: 'boolean' }, defaultValue: { summary: 'false' }, category: 'Behaviour' }
+    },
+    dismisslabel: {
+      control    : 'text',
+      description: "The close button's accessible name.",
+      table      : { type: { summary: 'string' }, defaultValue: { summary: 'Dismiss alert' }, category: 'Accessibility' }
+    }
+  }
+};
+
+export const Tones = () => html`
+    <div style="display:grid; gap:1rem">
+    <bd-alert heading="Heads up.">Your licence renews in 14 days.</bd-alert>
+    <bd-alert tone="success" heading="Done.">Your device is protected.</bd-alert>
+    <bd-alert tone="warning" heading="Check this.">Two devices are out of date.</bd-alert>
+    <bd-alert tone="error" heading="Blocked.">We could not reach the update server.</bd-alert>
+    <bd-alert tone="neutral" heading="For reference.">Scans run weekly on this plan.</bd-alert>
+    </div>
+  `;
+
+/**
+ * The `outline` variant is a surface treatment and keeps its tone. Both alerts
+ * below are still `info` and `error` respectively — the icon says so, and the
+ * error one still carries `role="alert"`. Use it where the page already has a
+ * tint of its own and a second one would read as dirt.
+ */
+export const Outline = () => html`
+    <div style="display:grid; gap:1rem">
+    <bd-alert variant="outline" heading="Heads up.">Your licence renews in 14 days.</bd-alert>
+    <bd-alert variant="outline" tone="error" heading="Blocked.">We could not reach the update server.</bd-alert>
+    </div>
+  `;
+
+/**
+ * `heading` is optional, and without it the alert is description only. Worth
+ * its own snapshot because it is the shape most inline alerts actually take.
+ */
+export const WithoutHeading = () => html`
+    <div style="display:grid; gap:1rem">
+    <bd-alert>Your licence renews in 14 days.</bd-alert>
+    <bd-alert tone="success">Your device is protected.</bd-alert>
+    <bd-alert tone="error">We could not reach the update server.</bd-alert>
+    </div>
+  `;
+
+/**
+ * The `actions` slot takes one or more actions under the description. It
+ * collapses entirely when nothing is slotted into it, so the three alerts above
+ * carry no empty row — compare their heights with these.
+ */
+export const WithActions = () => html`
+    <bd-alert tone="warning" heading="Two devices are out of date.">
+      Windows Defender is still handling real-time protection on them.
+      <bd-link inline slot="actions" href="#">Review devices</bd-link>
+      <bd-link inline slot="actions" href="#">Remind me later</bd-link>
+    </bd-alert>
+  `;
+
+/**
+ * `dismissible` adds the close button. It emits `bd-dismiss` and deliberately
+ * does not remove the element — whether the space collapses, animates out, or
+ * is replaced is the page's call. This story logs the event rather than acting
+ * on it, which is the honest demonstration.
+ */
+export const Dismissible = () => html`
+    <bd-alert
+      tone="success"
+      heading="Payment received."
+      dismissible
+      @bd-dismiss=${e => e.target.setAttribute('hidden', '')}
+    >
+      A receipt is on its way. This story hides the alert on dismiss, which is
+      one of several things a page might reasonably do.
+    </bd-alert>
+  `;
+
+/**
+ * The description is slotted, so it can carry markup — and it wraps. This is
+ * the story that shows the icon staying pinned to the first line while the
+ * text runs on, which is what `align-items: flex-start` on the row is for.
+ */
+export const LongMessage = () => html`
+    <div style="max-width: 46ch">
+      <bd-alert tone="warning" heading="Two devices are out of date." dismissible>
+        Windows Defender is still handling real-time protection on them. Open
+        <bd-link inline href="#">Device overview</bd-link> to finish setting up, or
+        remove the devices you no longer use.
+      </bd-alert>
+    </div>
+  `;