@kubex/zinc 1.1.98 → 1.1.100

package/scss/shared/_button.scss

@@ -2,7 +2,9 @@
 @use '../variables';
 
 @mixin button {
-  border-radius: var(--zn-border-radius);
+  // Buttons take their own radius token so a theme can make controls pills
+  // without reshaping panels, inputs and dialogs at the same time.
+  border-radius: var(--zn-button-border-radius, var(--zn-border-radius));
   display: inline-flex;
   align-items: center;
   justify-content: center;
@@ -10,7 +12,7 @@
   margin: auto;
   width: fit-content;
   background-color: rgb(var(--zn-primary));
-  color: rgba(255, 255, 255, 0.9);
+  color: rgba(var(--zn-color-on-primary, 255, 255, 255), 0.9);
   font-size: var(--zn-text-button-label-font-size);
   font-weight: var(--zn-text-button-label-font-weight);
   line-height: var(--zn-text-button-label-line-height);

package/scss/themes/_typography.scss

@@ -12,6 +12,7 @@
  *   --zn-text-<role>-font-weight
  *   --zn-text-<role>-color
  *   --zn-text-<role>-transform
+ *   --zn-text-<role>-letter-spacing
  *
  * All roles use the sans family (--zn-font-sans). Apply a role
  * in a component with the text-style() mixin from scss/mixins.
@@ -59,5 +60,6 @@ $text-styles: (
       --zn-text-#{$role}-color: var(--zn-text-color);
     }
     --zn-text-#{$role}-transform: #{map.get($style, "transform")};
+    --zn-text-#{$role}-letter-spacing: var(--zn-letter-spacing-normal, normal);
   }
 }

package/src/components/background/background.component.ts

@@ -0,0 +1,111 @@
+import {type CSSResultGroup, html, unsafeCSS} from 'lit';
+import {property} from 'lit/decorators.js';
+import {ResizeController} from '@lit-labs/observers/resize-controller.js';
+import {styleMap} from 'lit/directives/style-map.js';
+import ZincElement from '../../internal/zinc-element';
+import ZnIcon from '../icon';
+
+import styles from './background.scss';
+
+export type BackgroundImageStrength = 'soft' | 'medium' | 'full';
+export type BackgroundMotion = 'none' | 'drift' | 'breathe';
+export type BackgroundOverlay = 'none' | 'soft' | 'strong';
+export type BackgroundOverlayTone = 'light' | 'dark';
+
+/**
+ * @summary Composes a colour, decorative image, image strength, optional motion and contrast overlay behind slotted content.
+ *
+ * @documentation https://zinc.style/components/background
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-icon
+ *
+ * @slot - Content displayed above the background layers.
+ *
+ * @csspart base - The component's full-size background canvas.
+ * @csspart image - The decorative background image.
+ * @csspart overlay - The contrast overlay between the image and content.
+ * @csspart floating-icons - The non-interactive layer containing the floating icons.
+ * @csspart floating-icon - Each floating `zn-icon`.
+ * @csspart content - The wrapper around the default slot.
+ *
+ * @cssproperty --zn-background-color - Fallback colour when the `color` attribute is not set.
+ * @cssproperty --zn-background-image-position - Position of the background image. Defaults to `center`.
+ * @cssproperty --zn-background-overlay-angle - Direction of the overlay gradient. Defaults to `110deg`.
+ * @cssproperty --zn-background-floating-icon-color - Colour of the floating icons. Defaults to `currentColor`.
+ */
+export default class ZnBackground extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+  static dependencies = {'zn-icon': ZnIcon};
+
+  private readonly resizeObserver = new ResizeController<number>(this, {
+    callback: entries => {
+      const width = entries[0]?.contentRect.width ?? this.offsetWidth;
+      return Math.max(1, Math.min(width * 0.05, 150));
+    },
+  });
+
+  /** URL of the decorative background image. */
+  @property() image = '';
+
+  /** CSS colour painted beneath the image. */
+  @property() color = '';
+
+  /** Visibility of the image: `soft` (30%), `medium` (62%) or `full` (100%). */
+  @property({attribute: 'image-strength', reflect: true}) imageStrength: BackgroundImageStrength = 'full';
+
+  /** Subtle animation applied to the image. Motion stops when reduced motion is requested. */
+  @property({reflect: true}) motion: BackgroundMotion = 'none';
+
+  /** Strength of the contrast gradient above the image. */
+  @property({reflect: true}) overlay: BackgroundOverlay = 'soft';
+
+  /** Whether the overlay uses a light or dark contrast treatment. */
+  @property({attribute: 'overlay-tone', reflect: true}) overlayTone: BackgroundOverlayTone = 'light';
+
+  /** Comma-separated Zinc icon names placed as ambient decoration. At most eight are rendered. */
+  @property({attribute: 'floating-icons'}) floatingIcons = '';
+
+  /** Pauses background motion without changing the selected motion treatment. */
+  @property({type: Boolean, reflect: true}) paused = false;
+
+  render() {
+    const floatingIcons = this.floatingIcons
+      .split(',')
+      .map(icon => icon.trim())
+      .filter(Boolean)
+      .slice(0, 8);
+    const floatingIconSize = this.resizeObserver.value ?? 1;
+
+    return html`
+      <div
+        part="base"
+        class="background"
+        style=${styleMap({'--_zn-background-color': this.color || undefined})}>
+        ${this.image ? html`
+          <img
+            part="image"
+            class="background__image"
+            src=${this.image}
+            alt=""
+            decoding="async">
+        ` : ''}
+        <div part="overlay" class="background__overlay" aria-hidden="true"></div>
+        ${floatingIcons.length ? html`
+          <div part="floating-icons" class="background__floating-icons" aria-hidden="true">
+            ${floatingIcons.map(icon => html`
+              <zn-icon
+                part="floating-icon"
+                class="background__floating-icon"
+                src=${icon}
+                size=${floatingIconSize}
+                aria-hidden="true"></zn-icon>
+            `)}
+          </div>
+        ` : ''}
+        <div part="content" class="background__content"><slot></slot></div>
+      </div>
+    `;
+  }
+}

package/src/components/background/background.scss

@@ -0,0 +1,236 @@
+@use "../../wc";
+
+:host {
+  display: block;
+  position: relative;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  isolation: isolate;
+}
+
+.background {
+  position: relative;
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+  min-height: inherit;
+  overflow: hidden;
+  background-color: var(--_zn-background-color, var(--zn-background-color, transparent));
+}
+
+.background__image,
+.background__overlay,
+.background__floating-icons {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}
+
+.background__image {
+  width: 108%;
+  height: 108%;
+  max-width: none;
+  inset: -4%;
+  object-fit: cover;
+  object-position: var(--zn-background-image-position, center);
+  opacity: 1;
+}
+
+:host([image-strength="soft"]) .background__image {
+  opacity: 0.3;
+}
+
+:host([image-strength="medium"]) .background__image {
+  opacity: 0.62;
+}
+
+.background__overlay {
+  background: linear-gradient(
+    var(--zn-background-overlay-angle, 110deg),
+    rgb(255 255 255 / 18%),
+    rgb(255 255 255 / 4%)
+  );
+}
+
+:host([overlay="none"]) .background__overlay {
+  display: none;
+}
+
+:host([overlay="strong"]) .background__overlay {
+  background: linear-gradient(
+    var(--zn-background-overlay-angle, 110deg),
+    rgb(255 255 255 / 48%),
+    rgb(255 255 255 / 18%)
+  );
+}
+
+:host([overlay-tone="dark"]) .background__overlay {
+  background: linear-gradient(
+    var(--zn-background-overlay-angle, 110deg),
+    rgb(4 12 32 / 28%),
+    rgb(4 12 32 / 6%)
+  );
+}
+
+:host([overlay-tone="dark"][overlay="strong"]) .background__overlay {
+  background: linear-gradient(
+    var(--zn-background-overlay-angle, 110deg),
+    rgb(4 12 32 / 62%),
+    rgb(4 12 32 / 28%)
+  );
+}
+
+:host([motion="drift"]) .background__image {
+  animation: zn-background-drift 28s ease-in-out infinite alternate;
+}
+
+:host([motion="breathe"]) .background__image {
+  animation: zn-background-breathe 18s ease-in-out infinite;
+}
+
+:host([paused]) .background__image {
+  animation-play-state: paused;
+}
+
+.background__floating-icons {
+  overflow: hidden;
+  color: var(--zn-background-floating-icon-color, currentColor);
+}
+
+.background__floating-icon {
+  --_zn-background-icon-opacity-min: 0.01;
+  --_zn-background-icon-opacity-max: 0.18;
+  position: absolute;
+  left: 8%;
+  top: 13%;
+  opacity: var(--_zn-background-icon-opacity-min);
+  animation: zn-background-icon-float 11s ease-in-out infinite alternate both;
+}
+
+.background__floating-icon:nth-child(2) {
+  --_zn-background-icon-opacity-min: 0.08;
+  --_zn-background-icon-opacity-max: 0.34;
+  left: auto;
+  right: 9%;
+  top: 9%;
+  animation-delay: -4s;
+  animation-duration: 14s;
+}
+
+.background__floating-icon:nth-child(3) {
+  --_zn-background-icon-opacity-min: 0.03;
+  --_zn-background-icon-opacity-max: 0.5;
+  left: 2%;
+  top: 47%;
+  animation-delay: -7s;
+  animation-duration: 13s;
+}
+
+.background__floating-icon:nth-child(4) {
+  --_zn-background-icon-opacity-min: 0.12;
+  --_zn-background-icon-opacity-max: 0.38;
+  left: auto;
+  right: 12%;
+  top: 45%;
+  animation-delay: -2s;
+  animation-duration: 10s;
+}
+
+.background__floating-icon:nth-child(5) {
+  --_zn-background-icon-opacity-min: 0.05;
+  --_zn-background-icon-opacity-max: 0.29;
+  left: 21%;
+  top: auto;
+  bottom: 4%;
+  animation-delay: -5s;
+  animation-duration: 15s;
+}
+
+.background__floating-icon:nth-child(6) {
+  --_zn-background-icon-opacity-min: 0.01;
+  --_zn-background-icon-opacity-max: 0.42;
+  left: auto;
+  right: 4%;
+  top: auto;
+  bottom: 3%;
+  animation-delay: -9s;
+  animation-duration: 12s;
+}
+
+.background__floating-icon:nth-child(7) {
+  --_zn-background-icon-opacity-min: 0.09;
+  --_zn-background-icon-opacity-max: 0.31;
+  left: 42%;
+  top: 7%;
+  animation-delay: -6s;
+  animation-duration: 16s;
+}
+
+.background__floating-icon:nth-child(8) {
+  --_zn-background-icon-opacity-min: 0.04;
+  --_zn-background-icon-opacity-max: 0.46;
+  left: 54%;
+  top: auto;
+  bottom: 8%;
+  animation-delay: -11s;
+  animation-duration: 17s;
+}
+
+:host([paused]) .background__floating-icon {
+  animation-play-state: paused;
+}
+
+.background__content {
+  position: relative;
+  z-index: 1;
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+  min-height: inherit;
+}
+
+@keyframes zn-background-drift {
+  from {
+    transform: scale(1.04) translate3d(-1.2%, -0.6%, 0);
+  }
+
+  to {
+    transform: scale(1.04) translate3d(1.2%, 0.6%, 0);
+  }
+}
+
+@keyframes zn-background-breathe {
+  0%, 100% {
+    transform: scale(1.02);
+  }
+
+  50% {
+    transform: scale(1.07);
+  }
+}
+
+@keyframes zn-background-icon-float {
+  from {
+    opacity: var(--_zn-background-icon-opacity-min);
+    transform: translate3d(-8%, -12%, 0) scale(0.88) rotate(-8deg);
+  }
+
+  to {
+    opacity: var(--_zn-background-icon-opacity-max);
+    transform: translate3d(8%, 12%, 0) scale(1.06) rotate(8deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .background__image,
+  .background__floating-icon {
+    animation: none;
+  }
+
+  .background__floating-icon {
+    opacity: var(--_zn-background-icon-opacity-max);
+  }
+}

package/src/components/background/background.test.ts

@@ -0,0 +1,120 @@
+import '../../../dist/zn.min.js';
+import {expect, fixture, html, waitUntil} from '@open-wc/testing';
+import type ZnBackground from './background.component';
+
+const transparentImage = 'data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs=';
+
+describe('<zn-background>', () => {
+  it('renders slotted content above the background layers', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background><p>Lesson content</p></zn-background>`);
+
+    const content = el.shadowRoot!.querySelector<HTMLElement>('.background__content')!;
+    const slot = content.querySelector<HTMLSlotElement>('slot')!;
+
+    expect(slot.assignedElements()[0].textContent).to.equal('Lesson content');
+    expect(getComputedStyle(content).zIndex).to.equal('1');
+  });
+
+  it('composes the configured colour and decorative image', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background color="#123456" image=${transparentImage}></zn-background>`);
+
+    const base = el.shadowRoot!.querySelector<HTMLElement>('.background')!;
+    const image = el.shadowRoot!.querySelector<HTMLImageElement>('.background__image')!;
+
+    expect(getComputedStyle(base).backgroundColor).to.equal('rgb(18, 52, 86)');
+    expect(image.src).to.equal(transparentImage);
+    expect(image.alt).to.equal('');
+    expect(image.getAttribute('part')).to.equal('image');
+  });
+
+  it('does not render an image element without an image URL', async () => {
+    const el = await fixture<ZnBackground>(html`<zn-background></zn-background>`);
+
+    expect(el.shadowRoot!.querySelector('.background__image')).to.not.exist;
+  });
+
+  it('applies soft, medium and full image strengths', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background image=${transparentImage} image-strength="soft"></zn-background>`);
+    const image = el.shadowRoot!.querySelector<HTMLImageElement>('.background__image')!;
+
+    expect(getComputedStyle(image).opacity).to.equal('0.3');
+    el.imageStrength = 'medium';
+    await el.updateComplete;
+    expect(getComputedStyle(image).opacity).to.equal('0.62');
+    el.imageStrength = 'full';
+    await el.updateComplete;
+    expect(getComputedStyle(image).opacity).to.equal('1');
+  });
+
+  it('supports drift and breathe motion and can pause it', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background image=${transparentImage} motion="drift"></zn-background>`);
+    const image = el.shadowRoot!.querySelector<HTMLImageElement>('.background__image')!;
+
+    expect(getComputedStyle(image).animationName).to.equal('zn-background-drift');
+    el.motion = 'breathe';
+    el.paused = true;
+    await el.updateComplete;
+    expect(getComputedStyle(image).animationName).to.equal('zn-background-breathe');
+    expect(getComputedStyle(image).animationPlayState).to.equal('paused');
+  });
+
+  it('supports none, soft and strong light or dark overlays', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background overlay="none"></zn-background>`);
+    const overlay = el.shadowRoot!.querySelector<HTMLElement>('.background__overlay')!;
+
+    expect(getComputedStyle(overlay).display).to.equal('none');
+    el.overlay = 'soft';
+    await el.updateComplete;
+    const lightGradient = getComputedStyle(overlay).backgroundImage;
+    expect(lightGradient).to.contain('255, 255, 255');
+
+    el.overlay = 'strong';
+    el.overlayTone = 'dark';
+    await el.updateComplete;
+    const darkGradient = getComputedStyle(overlay).backgroundImage;
+    expect(darkGradient).to.contain('4, 12, 32');
+    expect(darkGradient).to.not.equal(lightGradient);
+  });
+
+  it('renders up to eight comma-separated floating Zinc icons', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background
+        floating-icons="school, lightbulb, quiz, psychology, star, rocket, science, public, hidden">
+      </zn-background>`);
+    const icons = el.shadowRoot!.querySelectorAll<HTMLElement>('.background__floating-icon');
+
+    expect(icons).to.have.lengthOf(8);
+    expect(icons[0].getAttribute('src')).to.equal('school');
+    expect(icons[7].getAttribute('src')).to.equal('public');
+    expect(el.shadowRoot!.querySelector('.background__floating-icons')!.getAttribute('aria-hidden')).to.equal('true');
+  });
+
+  it('sizes floating icons to five percent of the background width', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background floating-icons="school" style="width: 1000px;"></zn-background>`);
+    const icon = el.shadowRoot!.querySelector<HTMLElement & {size: number}>('.background__floating-icon')!;
+
+    await waitUntil(() => icon.size === 50);
+    expect(icon.size).to.equal(50);
+  });
+
+  it('caps floating icons at 150 pixels and keeps opacity within one to fifty percent', async () => {
+    const el = await fixture<ZnBackground>(html`
+      <zn-background floating-icons="school,lightbulb" style="width: 4000px;"></zn-background>`);
+    const icons = [...el.shadowRoot!.querySelectorAll<HTMLElement & {size: number}>('.background__floating-icon')];
+
+    await waitUntil(() => icons[0].size === 150);
+    expect(icons[0].size).to.equal(150);
+    icons.forEach(icon => {
+      const styles = getComputedStyle(icon);
+      expect(Number(styles.getPropertyValue('--_zn-background-icon-opacity-min'))).to.be.at.least(0.01);
+      expect(Number(styles.getPropertyValue('--_zn-background-icon-opacity-max'))).to.be.at.most(0.5);
+      expect(styles.animationName).to.equal('zn-background-icon-float');
+    });
+  });
+});

package/src/components/background/index.ts

@@ -0,0 +1,12 @@
+import ZnBackground from './background.component';
+
+export * from './background.component';
+export default ZnBackground;
+
+ZnBackground.define('zn-background');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-background': ZnBackground;
+  }
+}

package/src/components/button/button.scss

@@ -17,7 +17,12 @@
 .button {
   @include shared.button;
 
+  // --btn-color paints the fill; --btn-ink is the text/icon colour that sits
+  // on top of it. They are declared as a pair so a theme with a light accent
+  // (e.g. neon lime) can re-point the ink via --zn-color-on-* without any
+  // component-level override.
   --btn-color: var(--zn-primary);
+  --btn-ink: var(--zn-color-on-primary, 255, 255, 255);
   --notification-color: rgb(var(--zn-color-error));
 
   border-width: var(--zn-button-border-width, 1px);
@@ -31,18 +36,22 @@
 
   &.button--info {
     --btn-color: var(--zn-color-info);
+    --btn-ink: var(--zn-color-on-info, 255, 255, 255);
   }
 
   &.button--error {
     --btn-color: var(--zn-color-error);
+    --btn-ink: var(--zn-color-on-error, 255, 255, 255);
   }
 
   &.button--warning {
     --btn-color: var(--zn-color-warning);
+    --btn-ink: var(--zn-color-on-warning, 255, 255, 255);
   }
 
   &.button--success {
     --btn-color: var(--zn-color-success);
+    --btn-ink: var(--zn-color-on-success, 255, 255, 255);
   }
 
   &__label--hidden {
@@ -131,7 +140,7 @@
 
   background-color: rgba(var(--btn-color));
   border-color: var(--zn-button-border-color, rgb(var(--btn-color)));
-  color: rgba(255, 255, 255, 0.9);
+  color: rgba(var(--btn-ink), 0.9);
 
   &:hover:not([disabled]) {
     background-color: rgba(var(--btn-color), 0.8);
@@ -154,7 +163,7 @@
 
   &:hover:not([disabled]), &:active:not([disabled]) {
     background-color: rgb(var(--btn-color));
-    color: white;
+    color: rgb(var(--btn-ink));
   }
 
   &.button--secondary {
@@ -219,9 +228,10 @@
 
 .button--star {
   --btn-color: var(--zn-orange);
+  --btn-ink: var(--zn-color-on-warning, 255, 255, 255);
   background-color: rgb(var(--btn-color));
   border-color: var(--zn-button-border-color, rgb(var(--btn-color)));
-  color: white;
+  color: rgb(var(--btn-ink));
   opacity: 1 !important;
 
   &:hover:not([disabled]) {
@@ -239,7 +249,7 @@
 
     &:hover:not([disabled]), &:active:not([disabled]) {
       background-color: rgba(var(--btn-color));
-      color: white;
+      color: rgb(var(--btn-ink));
     }
   }
 }