@aquera/nile-elements 2.0.5 → 2.0.7

package/src/nile-app-shell-side-nav/nile-app-shell-side-nav.css.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { css } from 'lit';
+
+/**
+ * AppShellSideNav CSS. The shell owns the track width; this owns what happens
+ * inside it — a pinned header, a scrolling body, a pinned footer.
+ */
+export const styles = css`
+  :host {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    /* The nav and the page share one surface. */
+    background: var(--nile-app-shell-side-nav-bg, transparent);
+  }
+
+  :host([hidden]) {
+    display: none;
+  }
+
+  .header,
+  .footer {
+    flex: 0 0 auto;
+    display: block;
+  }
+
+  .body {
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow-y: auto;
+    overflow-x: hidden;
+    padding: var(
+      --nile-app-shell-side-nav-padding,
+      var(--nile-spacing-lg, var(--ng-spacing-lg))
+    );
+    scrollbar-width: thin;
+  }
+
+  .body::-webkit-scrollbar {
+    width: 6px;
+  }
+
+  .body::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  .body::-webkit-scrollbar-thumb {
+    background-color: var(
+      --nile-colors-neutral-500,
+      var(--ng-colors-border-primary)
+    );
+    border-radius: 10px;
+  }
+
+  /* A rail has no room for a horizontal scrollbar or for wide children. */
+  :host([collapsed]) .body {
+    overflow-x: hidden;
+  }
+`;
+
+export default [styles];

package/src/nile-app-shell-side-nav/nile-app-shell-side-nav.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright Aquera Inc 2023
+ *
+ * This source code is licensed under the BSD-3-Clause license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html, CSSResultArray, TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+import { styles } from './nile-app-shell-side-nav.css';
+import { AppShellController } from '../nile-app-shell/shell-controller';
+import NileElement from '../internal/nile-element';
+
+/**
+ * @summary The shell's left region — the navigation track. Assigns itself to the
+ * shell's `side-nav` slot and mirrors the shell's rail state, so nav content can
+ * style against it.
+ *
+ * @status stable
+ * @since 2.0
+ *
+ * @tag nile-app-shell-side-nav
+ *
+ * @dependency nile-app-shell
+ *
+ * @slot - The nav body. Scrolls.
+ * @slot header - Pinned above the scroll region — a wordmark or product switcher.
+ * @slot footer - Pinned below it — an account row or help link.
+ *
+ * @csspart header - The pinned header.
+ * @csspart body - The scrolling nav body.
+ * @csspart footer - The pinned footer.
+ *
+ * @cssproperty [--nile-app-shell-side-nav-padding=12px] - Body inset. 12 + 40 +
+ *   12 is what makes a 64px rail.
+ * @cssproperty [--nile-app-shell-side-nav-bg=transparent] - Surface behind the
+ *   nav. Transparent by default: the nav and the page share one.
+ */
+@customElement('nile-app-shell-side-nav')
+export class NileAppShellSideNav extends NileElement {
+  public static get styles(): CSSResultArray {
+    return [styles];
+  }
+
+  private shellLink = new AppShellController(this);
+
+  /**
+   * Mirrors the shell's effective rail state — the user's preference, or a rail
+   * forced by the shell's width. Set by the shell; treat it as read-only and
+   * style against it (`nile-app-shell-side-nav[collapsed] .label`).
+   */
+  @property({ type: Boolean, reflect: true })
+  collapsed: boolean = false;
+
+  /** Id of the shell to follow. Defaults to the nearest ancestor. */
+  @property({ type: String })
+  shell?: string;
+
+  public connectedCallback(): void {
+    super.connectedCallback();
+    // Claim the shell's left region unless the author placed it elsewhere.
+    if (!this.hasAttribute('slot')) this.setAttribute('slot', 'side-nav');
+  }
+
+  protected willUpdate(): void {
+    this.shellLink.shellId = this.shell;
+    const shell = this.shellLink.shell;
+    if (shell) this.collapsed = shell.rail;
+  }
+
+  public render(): TemplateResult {
+    return html`
+      <slot name="header" part="header" class="header"></slot>
+      <div class="body" part="body"><slot></slot></div>
+      <slot name="footer" part="footer" class="footer"></slot>
+    `;
+  }
+}
+
+export default NileAppShellSideNav;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'nile-app-shell-side-nav': NileAppShellSideNav;
+  }
+}

package/src/nile-floating-panel/nile-floating-panel.css.ts

@@ -81,26 +81,24 @@ export const styles = css`
     display: none;
   }
 
+  /* Offset arrow by 0.5px so its outline aligns with the panel border and its fill fully covers it. */
   .tippy-box[data-theme~='floating-panel'][data-placement^='top'] > .tippy-svg-arrow { bottom: 0; }
-  .tippy-box[data-theme~='floating-panel'][data-placement^='top'] > .tippy-svg-arrow:after,
   .tippy-box[data-theme~='floating-panel'][data-placement^='top'] > .tippy-svg-arrow > svg {
-    top: 16px;
+    top: 15.5px;
     transform: rotate(180deg);
   }
   .tippy-box[data-theme~='floating-panel'][data-placement^='bottom'] > .tippy-svg-arrow { top: 0; }
-  .tippy-box[data-theme~='floating-panel'][data-placement^='bottom'] > .tippy-svg-arrow > svg { bottom: 16px; }
+  .tippy-box[data-theme~='floating-panel'][data-placement^='bottom'] > .tippy-svg-arrow > svg { bottom: 15.5px; }
   .tippy-box[data-theme~='floating-panel'][data-placement^='left'] > .tippy-svg-arrow { right: 0; }
-  .tippy-box[data-theme~='floating-panel'][data-placement^='left'] > .tippy-svg-arrow:after,
   .tippy-box[data-theme~='floating-panel'][data-placement^='left'] > .tippy-svg-arrow > svg {
     transform: rotate(90deg);
-    top: calc(50% - 3px);
+    top: calc(50% - 3.5px);
     left: 11px;
   }
   .tippy-box[data-theme~='floating-panel'][data-placement^='right'] > .tippy-svg-arrow { left: 0; }
-  .tippy-box[data-theme~='floating-panel'][data-placement^='right'] > .tippy-svg-arrow:after,
   .tippy-box[data-theme~='floating-panel'][data-placement^='right'] > .tippy-svg-arrow > svg {
     transform: rotate(-90deg);
-    top: calc(50% - 3px);
+    top: calc(50% - 3.5px);
     right: 11px;
   }
 
@@ -113,6 +111,14 @@ export const styles = css`
 
   .tippy-box[data-theme~='floating-panel'] > .tippy-svg-arrow > svg {
     position: absolute;
+    overflow: visible;
+  }
+
+  .tippy-box[data-theme~='floating-panel'] > .tippy-svg-arrow > svg > .nile-floating-panel__arrow-outline {
+    fill: none;
+    stroke: var(--nile-colors-dark-200, var(--ng-colors-border-secondary-alt));
+    stroke-width: 1;
+    vector-effect: non-scaling-stroke;
   }
 
   .tippy-box[data-theme~='floating-panel'][data-placement^='top'] > .tippy-arrow {
@@ -123,6 +129,13 @@ export const styles = css`
     border-width: 8px 8px 0;
     border-top-color: initial;
   }
+  .tippy-box[data-theme~='floating-panel'][data-placement^='top'] > .tippy-arrow:after {
+    bottom: -8px;
+    left: -1px;
+    border-width: 9px 9px 0;
+    border-top-color: var(--nile-colors-dark-200, var(--ng-colors-border-secondary-alt));
+    clip-path: inset(2px 0 0 0);
+  }
   .tippy-box[data-theme~='floating-panel'][data-placement^='bottom'] > .tippy-arrow {
     top: 0;
   }
@@ -131,6 +144,13 @@ export const styles = css`
     border-width: 0 8px 8px;
     border-bottom-color: initial;
   }
+  .tippy-box[data-theme~='floating-panel'][data-placement^='bottom'] > .tippy-arrow:after {
+    top: -8px;
+    left: -1px;
+    border-width: 0 9px 9px;
+    border-bottom-color: var(--nile-colors-dark-200, var(--ng-colors-border-secondary-alt));
+    clip-path: inset(0 0 2px 0);
+  }
   .tippy-box[data-theme~='floating-panel'][data-placement^='left'] > .tippy-arrow {
     right: 0;
   }
@@ -139,6 +159,13 @@ export const styles = css`
     border-width: 8px 0 8px 8px;
     border-left-color: initial;
   }
+  .tippy-box[data-theme~='floating-panel'][data-placement^='left'] > .tippy-arrow:after {
+    right: -8px;
+    top: -1px;
+    border-width: 9px 0 9px 9px;
+    border-left-color: var(--nile-colors-dark-200, var(--ng-colors-border-secondary-alt));
+    clip-path: inset(0 0 0 2px);
+  }
   .tippy-box[data-theme~='floating-panel'][data-placement^='right'] > .tippy-arrow {
     left: 0;
   }
@@ -147,18 +174,29 @@ export const styles = css`
     border-width: 8px 8px 8px 0;
     border-right-color: initial;
   }
+  .tippy-box[data-theme~='floating-panel'][data-placement^='right'] > .tippy-arrow:after {
+    left: -8px;
+    top: -1px;
+    border-width: 9px 9px 9px 0;
+    border-right-color: var(--nile-colors-dark-200, var(--ng-colors-border-secondary-alt));
+    clip-path: inset(0 2px 0 0);
+  }
 
   .tippy-box[data-theme~='floating-panel'] > .tippy-arrow {
     width: 16px;
     height: 16px;
     color: var(--nile-colors-white-base, var(--ng-colors-bg-primary));
   }
-  .tippy-box[data-theme~='floating-panel'] > .tippy-arrow:before {
+  /* :after is a 1px-larger triangle in the border colour, stacked behind :before, so the border continues around the arrow. */
+  .tippy-box[data-theme~='floating-panel'] > .tippy-arrow:before,
+  .tippy-box[data-theme~='floating-panel'] > .tippy-arrow:after {
     content: '';
     position: absolute;
     border-color: transparent;
     border-style: solid;
   }
+  .tippy-box[data-theme~='floating-panel'] > .tippy-arrow:before { z-index: 1; }
+  .tippy-box[data-theme~='floating-panel'] > .tippy-arrow:after { z-index: 0; }
 `;
 
 export function injectGlobalFloatingPanelStyles(): void {

package/src/nile-floating-panel/nile-floating-panel.ts

@@ -21,6 +21,24 @@ import {
 } from '../nile-lite-tooltip/utils';
 import { VisibilityManager } from '../utilities/visibility-manager.js';
 
+const TIPPY_ROUND_ARROW =
+  /^<svg width="(\d+)" height="(\d+)"[^>]*><path d="(.+?)H0z"/.exec(roundArrow);
+
+const NILE_ROUND_ARROW = ((): string => {
+  if (!TIPPY_ROUND_ARROW) return roundArrow;
+
+  const [, rawWidth, rawHeight, curve] = TIPPY_ROUND_ARROW;
+  const width = Number(rawWidth);
+  const height = Number(rawHeight) + 1; // + the skirt that covers the border
+
+  return (
+    `<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" aria-hidden="true" focusable="false" xmlns="http://www.w3.org/2000/svg">` +
+    `<path d="${curve}V${height}H0Z"></path>` +
+    `<path class="nile-floating-panel__arrow-outline" d="${curve}"></path>` +
+    `</svg>`
+  );
+})();
+
 /**
  * Nile floating-panel component.
  *
@@ -482,7 +500,7 @@ export class NileFloatingPanel extends NileElement {
 
   private _resolveArrow() {
     switch (this.arrow) {
-      case 'round': return roundArrow;
+      case 'round': return NILE_ROUND_ARROW;
       case 'none': return false as const;
       default: return true as const;
     }

package/src/nile-popover/nile-popover.css.ts

@@ -40,10 +40,6 @@ export const styles = css`
     background-color: var(--nile-colors-white-base, var(--ng-colors-bg-primary));
     border: solid 1px var(--nile-colors-dark-200, var(--ng-colors-border-secondary-alt));
     box-shadow: var(--nile-box-shadow-2, var(--ng-shadow-lg));
-    --arrow-size: 18px;
-    --arrow-size-diagonal: calc(var(--arrow-size) * 0.7071);
-    --arrow-padding-offset: calc(var(--arrow-size-diagonal) - var(--arrow-size));
-    --arrow-color: var(--nile-colors-white-base, var(--ng-colors-text-white));
   }
 
   .popover__action {
@@ -52,19 +48,38 @@ export const styles = css`
   }
 
   nile-popup {
-    --arrow-size: 18px;
-    --arrow-color: var(--nile-colors-white-base, var(--ng-colors-text-white));
+    --arrow-size: 10px;
+    --arrow-color: var(--nile-colors-white-base, var(--ng-colors-bg-primary));
+    --arrow-border-color: var(
+      --nile-colors-dark-200,
+      var(--ng-colors-border-secondary-alt)
+    );
   }
 
-  .popup__arrow {
-    position: absolute;
-    width: calc(var(--arrow-size-diagonal) * 2);
-    height: calc(var(--arrow-size-diagonal) * 2);
-    rotate: 45deg;
-    background: var(--arrow-color);
-    z-index: -1;
-    border: solid 1px var(--nile-colors-dark-200, var(--ng-colors-border-secondary-alt));
-    box-shadow: var(--nile-box-shadow-2, var(--ng-shadow-lg));
+  nile-popup::part(arrow) {
+    z-index: 1;
+    border: none;
+    box-shadow: none;
+  }
+
+  nile-popup[data-current-placement^='bottom']::part(arrow) {
+    border-top: solid 1px var(--arrow-border-color);
+    border-left: solid 1px var(--arrow-border-color);
+  }
+
+  nile-popup[data-current-placement^='top']::part(arrow) {
+    border-bottom: solid 1px var(--arrow-border-color);
+    border-right: solid 1px var(--arrow-border-color);
+  }
+
+  nile-popup[data-current-placement^='left']::part(arrow) {
+    border-top: solid 1px var(--arrow-border-color);
+    border-right: solid 1px var(--arrow-border-color);
+  }
+
+  nile-popup[data-current-placement^='right']::part(arrow) {
+    border-bottom: solid 1px var(--arrow-border-color);
+    border-left: solid 1px var(--arrow-border-color);
   }
 `;
 

package/src/nile-popover/nile-popover.test.ts

@@ -7,7 +7,7 @@ describe('NilePopover', () => {
   it('2. shadow root', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.shadowRoot).to.not.be.null; });
   it('3. tag name', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.tagName.toLowerCase()).to.equal('nile-popover'); });
   it('4. placement defaults top', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.placement).to.equal('top'); });
-  it('5. distance defaults 18', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.distance).to.equal(18); });
+  it('5. distance defaults 12', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.distance).to.equal(12); });
   it('6. preventOverlayClose defaults false', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.preventOverlayClose).to.equal(false); });
   it('7. arrow defaults true', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.arrow).to.equal(true); });
   it('8. title defaults empty', async () => { const el = await fixture<NilePopover>(html`<nile-popover></nile-popover>`); expect(el.title).to.equal(''); });

package/src/nile-popover/nile-popover.ts

@@ -56,7 +56,7 @@ export class NilePopover extends NileElement {
     | 'left-end' = 'top';
 
   /** The distance in pixels from which to offset the popover away from its target. */
-  @property({ type: Number }) distance = 18;
+  @property({ type: Number }) distance = 12;
 
   @property({ type: Boolean, reflect: true }) preventOverlayClose = false;
 

package/src/nile-side-bar-footer/nile-side-bar-footer.css.ts

@@ -16,6 +16,11 @@ export const styles = css`
   background: var(--nile-colors-neutral-100, var(--ng-colors-bg-primary));
 }
 
+/* Opt-in: drop the surface color so the footer sits on whatever is behind it. */
+:host([background='transparent']) {
+  background: transparent;
+}
+
 .footer {
   display: flex;
   flex-direction: column;    

package/src/nile-side-bar-footer/nile-side-bar-footer.test.ts

@@ -0,0 +1,55 @@
+import { expect, fixture, html } from '@open-wc/testing';
+import './nile-side-bar-footer';
+import type { NileSideBarFooter } from './nile-side-bar-footer';
+
+const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+
+/**
+ * The surface color comes from a design token, which a bare fixture does not
+ * load — so pin it on a wrapper to have something concrete to assert against.
+ */
+async function withToken(markup: unknown) {
+  const wrapper = await fixture<HTMLDivElement>(
+    html`<div style="--nile-colors-neutral-100: rgb(1, 2, 3)">${markup}</div>`
+  );
+  const el = wrapper.querySelector('nile-side-bar-footer') as NileSideBarFooter;
+  await el.updateComplete;
+  return el;
+}
+
+const backgroundOf = (el: NileSideBarFooter) => getComputedStyle(el).backgroundColor;
+
+describe('NileSideBarFooter — background', () => {
+  it('1. defaults to "default" and reflects the attribute', async () => {
+    const el = await withToken(html`<nile-side-bar-footer></nile-side-bar-footer>`);
+    expect(el.background).to.equal('default');
+    expect(el.getAttribute('background')).to.equal('default');
+  });
+
+  it('2. paints the sidebar surface color by default', async () => {
+    const el = await withToken(html`<nile-side-bar-footer></nile-side-bar-footer>`);
+    expect(backgroundOf(el)).to.equal('rgb(1, 2, 3)');
+  });
+
+  it('3. background="transparent" removes the background', async () => {
+    const el = await withToken(
+      html`<nile-side-bar-footer background="transparent"></nile-side-bar-footer>`
+    );
+    expect(el.background).to.equal('transparent');
+    expect(backgroundOf(el)).to.equal(TRANSPARENT);
+  });
+
+  it('4. setting the property at runtime reflects and re-styles both ways', async () => {
+    const el = await withToken(html`<nile-side-bar-footer></nile-side-bar-footer>`);
+
+    el.background = 'transparent';
+    await el.updateComplete;
+    expect(el.getAttribute('background')).to.equal('transparent');
+    expect(backgroundOf(el)).to.equal(TRANSPARENT);
+
+    el.background = 'default';
+    await el.updateComplete;
+    expect(el.getAttribute('background')).to.equal('default');
+    expect(backgroundOf(el)).to.equal('rgb(1, 2, 3)');
+  });
+});

package/src/nile-side-bar-footer/nile-side-bar-footer.ts

@@ -6,7 +6,7 @@
  */
 
 import { html, CSSResultArray, TemplateResult } from 'lit';
-import { customElement } from 'lit/decorators.js';
+import { customElement, property } from 'lit/decorators.js';
 import { styles } from './nile-side-bar-footer.css';
 import NileElement from '../internal/nile-element';
 
@@ -17,9 +17,20 @@ import NileElement from '../internal/nile-element';
  *
  * @slot icon - Slot for footer icon
  * @slot text - Slot for footer text
+ *
+ * @attr background - Background treatment of the footer ("default" | "transparent").
+ *   Defaults to "default", which paints the sidebar surface color. Set to
+ *   "transparent" to drop the background so whatever sits behind the footer shows
+ *   through.
  */
 @customElement('nile-side-bar-footer')
 export class NileSideBarFooter extends NileElement {
+  /**
+   * Background treatment of the footer. `default` keeps the sidebar surface
+   * color; `transparent` removes it.
+   */
+  @property({ type: String, reflect: true, attribute: true }) background: 'default' | 'transparent' = 'default';
+
   public static get styles(): CSSResultArray {
     return [styles];
   }

package/src/nile-side-bar-header/nile-side-bar-app-shell.test.ts

@@ -0,0 +1,78 @@
+import { expect, fixture, html, waitUntil } from '@open-wc/testing';
+import '../nile-app-shell/nile-app-shell';
+import '../nile-side-bar/nile-side-bar';
+import './nile-side-bar-header';
+import '../nile-side-bar-footer/nile-side-bar-footer';
+import type { NileAppShell } from '../nile-app-shell/nile-app-shell';
+import type { NileSideBarHeader } from './nile-side-bar-header';
+import type { NileSideBarFooter } from '../nile-side-bar-footer/nile-side-bar-footer';
+
+const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+const SURFACE = 'rgb(1, 2, 3)';
+
+/**
+ * nile-app-shell owns the nav track's surface, so it forces the slotted
+ * sidebar's own background off:
+ *
+ *   ::slotted([slot='side-nav']) {
+ *     background: var(--nile-app-shell-side-nav-bg, transparent) !important;
+ *   }
+ *
+ * That reaches the `nile-side-bar` only. The header and footer live one level
+ * deeper — they are light-DOM children of the sidebar, slotted into ITS shadow
+ * root — so the shell cannot see them, and their own surface color survives.
+ * These tests pin that boundary down, because it is the whole reason
+ * `background="transparent"` exists.
+ */
+async function shellWithSidebar(headerBg?: string, footerBg?: string) {
+  const el = await fixture<NileAppShell>(html`
+    <nile-app-shell style="width: 1400px; height: 600px; --nile-colors-neutral-100: ${SURFACE};">
+      <nile-side-bar slot="side-nav">
+        <nile-side-bar-header slot="header" background="${headerBg ?? 'default'}">
+          <span slot="logo">Logo</span>
+        </nile-side-bar-header>
+        <nile-side-bar-footer slot="footer" background="${footerBg ?? 'default'}">
+          <span>Help</span>
+        </nile-side-bar-footer>
+      </nile-side-bar>
+      <span slot="top-bar">Title</span>
+      <p>page</p>
+    </nile-app-shell>
+  `);
+  await waitUntil(() => el.hasAttribute('has-side-nav'));
+
+  const sidebar = el.querySelector('nile-side-bar') as HTMLElement;
+  const header = el.querySelector('nile-side-bar-header') as NileSideBarHeader;
+  const footer = el.querySelector('nile-side-bar-footer') as NileSideBarFooter;
+  await header.updateComplete;
+  await footer.updateComplete;
+  return { el, sidebar, header, footer };
+}
+
+const bg = (el: HTMLElement) => getComputedStyle(el).backgroundColor;
+
+describe('side-bar header/footer inside nile-app-shell', () => {
+  it('1. the shell strips the sidebar\'s own background', async () => {
+    const { sidebar } = await shellWithSidebar();
+    expect(bg(sidebar)).to.equal(TRANSPARENT);
+  });
+
+  it('2. without the new property the header/footer keep painting a surface, which is the seam', async () => {
+    const { header, footer } = await shellWithSidebar();
+    expect(bg(header)).to.equal(SURFACE);
+    expect(bg(footer)).to.equal(SURFACE);
+  });
+
+  it('3. background="transparent" closes the seam — nav track is one flat surface', async () => {
+    const { sidebar, header, footer } = await shellWithSidebar('transparent', 'transparent');
+    expect(bg(sidebar)).to.equal(TRANSPARENT);
+    expect(bg(header)).to.equal(TRANSPARENT);
+    expect(bg(footer)).to.equal(TRANSPARENT);
+  });
+
+  it('4. the shell\'s !important rule does not override the header/footer either way', async () => {
+    const { header, footer } = await shellWithSidebar('default', 'transparent');
+    expect(bg(header)).to.equal(SURFACE);
+    expect(bg(footer)).to.equal(TRANSPARENT);
+  });
+});

package/src/nile-side-bar-header/nile-side-bar-header.css.ts

@@ -23,6 +23,11 @@ export const styles = css`
   background: var(--nile-colors-neutral-100, var(--ng-colors-bg-primary));
 }
 
+/* Opt-in: drop the surface color so the header sits on whatever is behind it. */
+:host([background='transparent']) {
+  background: transparent;
+}
+
 .header-content {
   display: flex;
   align-items: center;

package/src/nile-side-bar-header/nile-side-bar-header.test.ts

@@ -0,0 +1,55 @@
+import { expect, fixture, html } from '@open-wc/testing';
+import './nile-side-bar-header';
+import type { NileSideBarHeader } from './nile-side-bar-header';
+
+const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+
+/**
+ * The surface color comes from a design token, which a bare fixture does not
+ * load — so pin it on a wrapper to have something concrete to assert against.
+ */
+async function withToken(markup: unknown) {
+  const wrapper = await fixture<HTMLDivElement>(
+    html`<div style="--nile-colors-neutral-100: rgb(1, 2, 3)">${markup}</div>`
+  );
+  const el = wrapper.querySelector('nile-side-bar-header') as NileSideBarHeader;
+  await el.updateComplete;
+  return el;
+}
+
+const backgroundOf = (el: NileSideBarHeader) => getComputedStyle(el).backgroundColor;
+
+describe('NileSideBarHeader — background', () => {
+  it('1. defaults to "default" and reflects the attribute', async () => {
+    const el = await withToken(html`<nile-side-bar-header></nile-side-bar-header>`);
+    expect(el.background).to.equal('default');
+    expect(el.getAttribute('background')).to.equal('default');
+  });
+
+  it('2. paints the sidebar surface color by default', async () => {
+    const el = await withToken(html`<nile-side-bar-header></nile-side-bar-header>`);
+    expect(backgroundOf(el)).to.equal('rgb(1, 2, 3)');
+  });
+
+  it('3. background="transparent" removes the background', async () => {
+    const el = await withToken(
+      html`<nile-side-bar-header background="transparent"></nile-side-bar-header>`
+    );
+    expect(el.background).to.equal('transparent');
+    expect(backgroundOf(el)).to.equal(TRANSPARENT);
+  });
+
+  it('4. setting the property at runtime reflects and re-styles both ways', async () => {
+    const el = await withToken(html`<nile-side-bar-header></nile-side-bar-header>`);
+
+    el.background = 'transparent';
+    await el.updateComplete;
+    expect(el.getAttribute('background')).to.equal('transparent');
+    expect(backgroundOf(el)).to.equal(TRANSPARENT);
+
+    el.background = 'default';
+    await el.updateComplete;
+    expect(el.getAttribute('background')).to.equal('default');
+    expect(backgroundOf(el)).to.equal('rgb(1, 2, 3)');
+  });
+});

package/src/nile-side-bar-header/nile-side-bar-header.ts

@@ -16,10 +16,20 @@ import NileElement from '../internal/nile-element';
  *
  * @tag nile-side-bar-header
  *
+ * @attr background - Background treatment of the header ("default" | "transparent").
+ *   Defaults to "default", which paints the sidebar surface color. Set to
+ *   "transparent" to drop the background so whatever sits behind the header shows
+ *   through.
  */
 @customElement('nile-side-bar-header')
 export class NileSideBarHeader extends NileElement {
 
+	/**
+	 * Background treatment of the header. `default` keeps the sidebar surface
+	 * color; `transparent` removes it.
+	 */
+	@property({ type: String, reflect: true, attribute: true }) background: 'default' | 'transparent' = 'default';
+
 	/**
 	 * The styles for nile-side-bar-header
 	 * @remarks If you are extending this class you can extend the base styles with super. Eg `return [super(), myCustomStyles]`