@kubex/zinc 1.0.107 → 1.0.109

package/docs/_includes/sidebar.njk

@@ -7,6 +7,7 @@
       <li><a href="/getting-started/table-examples">Table Examples</a></li>
       <li><a href="/getting-started/example-layout">Example Layout</a></li>
       <li><a href="/getting-started/example-page">Example Page</a></li>
+      <li><a href="/getting-started/shimmer-text">Shimmer Text</a></li>
     </ul>
   </li>
   <li>

package/docs/pages/components/icon.md

@@ -333,6 +333,8 @@ Explicit library specification:
 <zn-icon src="test1@example.com" library="gravatar" size="48"></zn-icon>
 ```
 
+Email addresses are trimmed, lowercased, and hashed with SHA-256 before the Gravatar request is made.
+
 Using shorthand notation:
 
 ```html:preview
@@ -348,6 +350,8 @@ Libravatar is an open-source alternative to Gravatar. Use it for federated avata
 <zn-icon src="user@example.com" library="libravatar" size="48" round></zn-icon>
 ```
 
+Email addresses are trimmed, lowercased, and hashed with SHA-256 before the Libravatar request is made.
+
 Similar to Gravatar, you can specify fallback options:
 
 ```html:preview
@@ -727,4 +731,4 @@ your HTML like this:
       grid-template-columns: repeat(4, 1fr);
     }
   }
-</style>
+</style>

package/docs/pages/getting-started/shimmer-text.md

@@ -0,0 +1,81 @@
+---
+meta:
+  title: Shimmer Text
+  description: A global utility class that applies an animated shimmer sweep to text, suitable for loading, processing, or "thinking" states.
+---
+
+# Shimmer Text
+
+`shimmer-text` is a global utility class that animates a horizontal highlight sweep across text colour. Use it to convey an in-progress state — AI generation, background processing, or any "working on it" indicator.
+
+The class works on any element with text content, including inside Zinc components. Colour variants mirror the standard Zinc palette: `zn-primary`, `zn-accent`, `zn-info`, `zn-success`, `zn-warning`, `zn-error`.
+
+When `prefers-reduced-motion: reduce` is set, the animation is suppressed and the text falls back to a solid colour matching the chosen variant.
+
+## Examples
+
+### Default
+
+```html:preview
+<span class="shimmer-text">Thinking…</span>
+```
+
+### Colour Variants
+
+```html:preview
+<div style="display: flex; flex-direction: column; gap: 8px;">
+  <span class="shimmer-text">Default</span>
+  <span class="shimmer-text zn-primary">Primary</span>
+  <span class="shimmer-text zn-accent">Accent</span>
+  <span class="shimmer-text zn-info">Info</span>
+  <span class="shimmer-text zn-success">Success</span>
+  <span class="shimmer-text zn-warning">Warning</span>
+  <span class="shimmer-text zn-error">Error</span>
+</div>
+```
+
+### Headings and Larger Text
+
+The shimmer scales with whatever `font-size` is on the element, so it can be applied to headings or inline within prose.
+
+```html:preview
+<h2 class="shimmer-text zn-primary" style="margin: 0;">Generating summary…</h2>
+<p style="margin: 8px 0 0;">
+  Please wait while we <span class="shimmer-text zn-info">analyse your data</span>.
+</p>
+```
+
+### Inside Zinc Components
+
+Because `shimmer-text` is a plain class, it composes with any Zinc component that renders slotted text.
+
+```html:preview
+<zn-chip class="shimmer-text zn-accent">Processing</zn-chip>
+```
+
+### Tuning the Sweep
+
+The effect mirrors the Claude CLI's character-level shimmer: a narrow, sharper highlight slides across text rather than a soft gradient wash. The class exposes these CSS custom properties — all sized in `ch` so they scale with the current font size.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `--shimmer-base` | `rgb(var(--zn-text))` | Resting text colour. |
+| `--shimmer-highlight` | `rgb(var(--zn-text-heading))` | Colour of the spotlight. |
+| `--shimmer-core` | `0.5ch` | Half-width of the solid-colour core of the spotlight. |
+| `--shimmer-spread` | `1.5ch` | Half-width of the full highlight including its fade-out edges. |
+| `--shimmer-duration` | `2s` | Time for one full sweep cycle. |
+
+```html:preview
+<div style="display: flex; flex-direction: column; gap: 6px;">
+  <span class="shimmer-text">Default sweep</span>
+  <span class="shimmer-text" style="--shimmer-duration: 1s;">Faster sweep</span>
+  <span class="shimmer-text" style="--shimmer-duration: 4s;">Slower, gentler sweep</span>
+  <span class="shimmer-text" style="--shimmer-core: 1ch; --shimmer-spread: 3ch;">Wider spotlight</span>
+</div>
+```
+
+The Claude CLI scales its sweep with message length (50ms per character plus 10 characters of offscreen pause on each side). To match that feel in CSS, set `--shimmer-duration` to roughly `(messageCharacters + 20) × 50ms`.
+
+### Reduced Motion
+
+The animation is wrapped in `@media (prefers-reduced-motion: no-preference)`. Users who have requested reduced motion see the static colour variant instead — no configuration required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.0.107",
+  "version": "1.0.109",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

package/scss/shared/index.scss

@@ -2,6 +2,7 @@
 @forward "layout";
 @forward "divide";
 @forward "nav";
+@forward "shimmer";
 
 
 // Need to remove the below from zinc, or have nice defaults that don't mess everything up

package/scss/shared/shimmer.scss

@@ -0,0 +1,98 @@
+
+@keyframes shimmer-text-sweep {
+  0% {
+    background-position: 100% center;
+  }
+  100% {
+    background-position: 0% center;
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .shimmer-text {
+    --shimmer-base: rgb(var(--zn-text));
+    --shimmer-highlight: rgb(var(--zn-text-heading));
+    --shimmer-core: 0.5ch;
+    --shimmer-spread: 1.5ch;
+    --shimmer-duration: 1.5s;
+
+    display: inline-block;
+    width: fit-content;
+    max-width: 100%;
+    background-image:
+      linear-gradient(
+        90deg,
+        transparent calc(50% - var(--shimmer-spread)),
+        var(--shimmer-highlight) calc(50% - var(--shimmer-core)),
+        var(--shimmer-highlight) calc(50% + var(--shimmer-core)),
+        transparent calc(50% + var(--shimmer-spread))
+      ),
+      linear-gradient(var(--shimmer-base), var(--shimmer-base));
+    background-size: 250% 100%, auto;
+    background-clip: text;
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent !important;
+    color: transparent !important;
+    animation: var(--shimmer-duration) linear infinite shimmer-text-sweep;
+
+    &.zn-error {
+      --shimmer-base: rgb(var(--zn-color-error));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-error)) 55%, white);
+    }
+
+    &.zn-success {
+      --shimmer-base: rgb(var(--zn-color-success));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-success)) 55%, white);
+    }
+
+    &.zn-info {
+      --shimmer-base: rgb(var(--zn-color-info));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-info)) 55%, white);
+    }
+
+    &.zn-warning {
+      --shimmer-base: rgb(var(--zn-color-warning));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-warning)) 55%, white);
+    }
+
+    &.zn-primary {
+      --shimmer-base: rgb(var(--zn-primary));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-primary)) 55%, white);
+    }
+
+    &.zn-accent {
+      --shimmer-base: rgb(var(--zn-accent));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-accent)) 55%, white);
+    }
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .shimmer-text {
+    color: rgb(var(--zn-text));
+
+    &.zn-error {
+      color: rgb(var(--zn-color-error)) !important;
+    }
+
+    &.zn-success {
+      color: rgb(var(--zn-color-success)) !important;
+    }
+
+    &.zn-info {
+      color: rgb(var(--zn-color-info)) !important;
+    }
+
+    &.zn-warning {
+      color: rgb(var(--zn-color-warning)) !important;
+    }
+
+    &.zn-primary {
+      color: rgb(var(--zn-primary)) !important;
+    }
+
+    &.zn-accent {
+      color: rgb(var(--zn-accent)) !important;
+    }
+  }
+}

package/src/components/datepicker/datepicker.component.ts

@@ -321,6 +321,12 @@ export default class ZnDatepicker extends ZincElement implements ZincFormControl
       return;
     }
 
+    if (event.key === 'Escape') {
+      this.input.blur();
+      event.stopPropagation();
+      return;
+    }
+
     // Allow navigation and control keys
     const allowedKeys = [
       'Backspace', 'Delete', 'Tab', 'Escape', 'Enter',

package/src/components/datepicker/datepicker.test.ts

@@ -1,5 +1,6 @@
 import '../../../dist/zn.min.js';
-import { expect, fixture, html } from '@open-wc/testing';
+import {expect, fixture, html} from '@open-wc/testing';
+import type ZnDatepicker from './datepicker.component';
 
 describe('<zn-datepicker>', () => {
   it('should render a component', async () => {
@@ -7,4 +8,34 @@ describe('<zn-datepicker>', () => {
 
     expect(el).to.exist;
   });
+
+  describe('Escape key', () => {
+    it('blurs the inner input when focused and the calendar is closed', async () => {
+      const el = await fixture<ZnDatepicker>(html`<zn-datepicker></zn-datepicker>`);
+      await el.updateComplete;
+
+      // Focus shows AirDatepicker's calendar (showEvent: 'focus'). Per spec, Escape
+      // while calendar is open is handled by AirDatepicker; our handler engages once
+      // the calendar is closed. Hide it explicitly to simulate the calendar-closed
+      // state, then press Escape.
+      el.focus();
+      await el.updateComplete;
+      const dp = (el as unknown as { _instance?: { hide: () => void; visible: boolean } })._instance;
+      dp?.hide();
+      await el.updateComplete;
+      el.input.focus();
+      await el.updateComplete;
+      expect(el.shadowRoot!.activeElement).to.equal(el.input);
+
+      el.input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+      await el.updateComplete;
+
+      expect(el.shadowRoot!.activeElement, 'inner input should be blurred').to.not.equal(el.input);
+    });
+  });
 });

package/src/components/form-group/form-group.component.ts

@@ -74,14 +74,14 @@ export default class ZnFormGroup extends ZincElement {
                     </zn-tooltip>`
                   : ''}
               </label>
+            </div>` : html``}
 
-              ${hasHelpText ? html`
-                <div
-                  part="form-control-help-text"
-                  id="help-text"
-                  class="form-control__help-text">
-                  <slot name="help-text">${this.helpText}</slot>
-                </div>` : html``}
+          ${hasHelpText ? html`
+            <div
+              part="form-control-help-text"
+              id="help-text"
+              class="form-control__help-text">
+              <slot name="help-text">${this.helpText}</slot>
             </div>` : html``}
 
           <div part="form-control-input" class="form-control-input">

package/src/components/icon/icon.component.ts

@@ -1,8 +1,8 @@
 import {choose} from 'lit/directives/choose.js';
 import {classMap} from "lit/directives/class-map.js";
 import {type CSSResultGroup, html, render, unsafeCSS} from 'lit';
-import {md5} from '../../utilities/md5';
 import {property} from 'lit/decorators.js';
+import {sha256} from '../../utilities/sha256';
 import {styleMap} from "lit/directives/style-map.js";
 import ZincElement from '../../internal/zinc-element';
 
@@ -30,7 +30,7 @@ export type IconColor =
   | "violet"
   | "pink"
   | "grey"
-  | (string & {});
+  | (string & Record<never, never>);
 
 /**
  * @summary Short summary of the component's intended use.
@@ -127,40 +127,37 @@ export default class ZnIcon extends ZincElement {
   connectedCallback() {
     super.connectedCallback();
 
+    let hashFragment = '';
 
     if (this.src && this.src.includes('#')) {
-      const split = this.src.split('#');
+      const split = this.src.split('#', 2);
       this.src = split[0];
-      const attributes = split[1].split(',');
-      attributes.forEach(attr => {
-        if (attr === "round") {
-          this.round = true;
-        }
-        if (attr === "tile") {
-          this.tile = true;
-        }
-        if (attr === "depth") {
-          this.depth = true;
-        }
-      });
+      hashFragment = split[1] ?? '';
     }
 
     if (this.src && this.src.includes('@')) {
-      const split = this.src.split('@');
-      if (split[1].includes('.')) {
-        this.library = "gravatar";
-      } else if ((this.library === undefined) && split[1] !== "") {
+      const atIndex = this.src.lastIndexOf('@');
+      const libraryOrDomain = this.src.slice(atIndex + 1);
+
+      if (libraryOrDomain.includes('.')) {
+        this.library = this.library ?? "gravatar";
+      } else if ((this.library === undefined) && libraryOrDomain !== "") {
         // if split[1] is a valid library name, set it
-        this.library = this.convertToLibrary(split[1]);
-        this.src = split[0];
+        this.library = this.convertToLibrary(libraryOrDomain);
+        this.src = this.src.slice(0, atIndex);
       }
 
       if (this.library === "gravatar" || this.library === "libravatar") {
-        this.ravatarOptions();
-        this.src = md5(this.src);
+        this.applyHashFragment(hashFragment);
+        this.src = sha256(this.normalizeRavatarEmail(this.src));
+      } else {
+        this.applyHashFragment(hashFragment);
       }
     } else if (!this.library && this.src && !this.src.includes('/')) {
+      this.applyHashFragment(hashFragment);
       this.library = this.defaultLibrary;
+    } else {
+      this.applyHashFragment(hashFragment);
     }
 
     // load the material icons font if the library is set to material
@@ -174,18 +171,42 @@ export default class ZnIcon extends ZincElement {
       <link
         href="https://fonts.googleapis.com/icon?family=Material+Symbols+Outlined|Material+Icons|Material+Icons+Round|Material+Icons+Sharp|Material+Icons+Two+Tone|Material+Icons+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200"
         rel="stylesheet">`, document.head);
-
-    this.ravatarOptions();
   }
 
-  ravatarOptions() {
-    if ((this.library === "gravatar" || this.library === "libravatar") && this.src.includes('#')) {
-      const split = this.src.split('#');
-      this.gravatarOptions = "&d=" + split[1];
-      this.src = split[0];
+  private applyHashFragment(hashFragment: string) {
+    if (!hashFragment) {
+      return;
+    }
+
+    const attributes = hashFragment.split(',');
+
+    attributes.forEach(attr => {
+      if (attr === 'round') {
+        this.round = true;
+      }
+
+      if (attr === 'tile') {
+        this.tile = true;
+      }
+
+      if (attr === 'depth') {
+        this.depth = true;
+      }
+    });
+
+    if ((this.library === 'gravatar' || this.library === 'libravatar')) {
+      const defaultOption = attributes.find(attr => !['round', 'tile', 'depth'].includes(attr));
+
+      if (defaultOption) {
+        this.gravatarOptions = `&d=${defaultOption}`;
+      }
     }
   }
 
+  private normalizeRavatarEmail(email: string) {
+    return email.trim().toLowerCase();
+  }
+
   render() {
     return html`
       <div class="icon-wrapper">

package/src/components/icon/icon.test.ts

@@ -1,5 +1,6 @@
 import '../../../dist/zn.min.js';
 import { expect, fixture, html } from '@open-wc/testing';
+import type ZnIcon from './icon.component';
 
 describe('<zn-icon>', () => {
   it('should render a component', async () => {
@@ -7,4 +8,26 @@ describe('<zn-icon>', () => {
 
     expect(el).to.exist;
   });
+
+  it('should build Gravatar URLs with a normalized SHA-256 hash', async () => {
+    const el = await fixture<ZnIcon>(html`
+      <zn-icon src="MyEmailAddress@example.com " library="gravatar" size="48"></zn-icon>
+    `);
+
+    const image = el.shadowRoot?.querySelector('img');
+    expect(image?.getAttribute('src')).to.equal(
+      'https://www.gravatar.com/avatar/84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee?s=48'
+    );
+  });
+
+  it('should pass fallback options through to Libravatar', async () => {
+    const el = await fixture<ZnIcon>(html`
+      <zn-icon src="nonexistent@example.com#identicon" library="libravatar" size="48"></zn-icon>
+    `);
+
+    const image = el.shadowRoot?.querySelector('img');
+    expect(image?.getAttribute('src')).to.equal(
+      'https://seccdn.libravatar.org/avatar/04e8703fcfb60849fb5c596abc8f3d7547c7e0099c3806a3ffec77a95dc02e25?s=48&d=identicon'
+    );
+  });
 });

package/src/components/input/input.component.ts

@@ -547,6 +547,12 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
   }
 
   private handleKeyDown(event: KeyboardEvent) {
+    if (event.key === 'Escape') {
+      this.input.blur();
+      event.stopPropagation();
+      return;
+    }
+
     const hasModifier = event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
 
     // Pressing enter when focused on the input should submit the form like a native input, be we wait a tick before

package/src/components/input/input.test.ts

@@ -1,5 +1,6 @@
 import '../../../dist/zn.min.js';
-import { expect, fixture, html } from '@open-wc/testing';
+import {expect, fixture, html} from '@open-wc/testing';
+import type ZnInput from './input.component';
 
 describe('<zn-input>', () => {
   it('should render a component', async () => {
@@ -7,4 +8,36 @@ describe('<zn-input>', () => {
 
     expect(el).to.exist;
   });
+
+  describe('Escape key', () => {
+    it('blurs the inner input and stops propagation when focused', async () => {
+      const wrapper = await fixture<HTMLDivElement>(html`
+        <div>
+          <zn-input></zn-input>
+        </div>
+      `);
+      const el = wrapper.querySelector('zn-input') as ZnInput;
+      await el.updateComplete;
+
+      let wrapperEscapes = 0;
+      wrapper.addEventListener('keydown', (e) => {
+        if ((e as KeyboardEvent).key === 'Escape') wrapperEscapes++;
+      });
+
+      el.focus();
+      await el.updateComplete;
+      expect(el.shadowRoot!.activeElement).to.equal(el.input);
+
+      el.input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+      await el.updateComplete;
+
+      expect(el.shadowRoot!.activeElement, 'inner input should be blurred').to.not.equal(el.input);
+      expect(wrapperEscapes, 'wrapper should not see Escape on press 1').to.equal(0);
+    });
+  });
 });

package/src/components/markdown-editor/markdown-editor.component.ts

@@ -269,6 +269,8 @@ export default class ZnMarkdownEditor extends ZnPanel implements ZincFormControl
         'panel--cosmic': this.cosmic,
         'panel--shadow': this.shadow,
       })}>
+
+
         <div class="panel__inner">
           ${hasHeader ? html`
             <zn-header class=${classMap({
@@ -297,6 +299,7 @@ export default class ZnMarkdownEditor extends ZnPanel implements ZincFormControl
                   </label>` : ''}
 
                 <div part="toolbar" class="markdown-editor__toolbar">
+                  ${this.markdownHelperBtn()}
                   <zn-button-group class="markdown-editor__view-toggle" @click=${this.handleViewToggle}>
                     ${VIEW_MODES.map(v => this.renderViewButton(v.mode, v.icon, v.label))}
                   </zn-button-group>
@@ -351,6 +354,21 @@ export default class ZnMarkdownEditor extends ZnPanel implements ZincFormControl
     `;
   }
 
+  markdownHelperBtn() {
+    return html`
+      <a
+        class="markdown-editor__markdown-link"
+        href="https://www.markdownguide.org/cheat-sheet"
+        target="_blank"
+        rel="noopener noreferrer"
+        title="Markdown is supported"
+      >
+        <zn-icon src="markdown"></zn-icon>
+        <span>Markdown is supported</span>
+      </a>
+    `;
+  }
+
   private renderViewButton(mode: ViewMode, icon: string, label: string) {
     const isActive = this.viewMode === mode;
     return html`
@@ -372,4 +390,7 @@ export default class ZnMarkdownEditor extends ZnPanel implements ZincFormControl
       ></zn-button>
     `;
   }
+
+
+
 }

package/src/components/markdown-editor/markdown-editor.scss

@@ -44,9 +44,32 @@
 
 .markdown-editor__toolbar {
   display: flex;
-  align-items: center;
+  align-items: end;
   gap: var(--zn-spacing-small);
   justify-content: flex-end;
+  flex-wrap: wrap;
+}
+
+.markdown-editor__markdown-link {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zn-spacing-x-small);
+  margin-right: auto;
+  font-size: var(--zn-input-label-font-size-small);
+  line-height: 1;
+  color: var(--zn-color-neutral-500, #656d76);
+  text-decoration: none;
+  cursor: pointer;
+  transition: color 0.15s ease;
+  padding-left: var(--zn-spacing-x-small);
+
+  &:hover {
+    color: var(--zn-color-primary-600, #0969da);
+  }
+
+  span {
+    white-space: nowrap;
+  }
 }
 
 .markdown-editor__view-toggle {

package/src/components/select/select.component.ts

@@ -484,6 +484,13 @@ export default class ZnSelect extends ZincElement implements ZincFormControl {
       this.displayInput.focus({preventScroll: true});
     }
 
+    // Blur the display input when Escape is pressed and the dropdown is closed,
+    // so a second Escape press can bubble (e.g. close a containing dialog).
+    if (event.key === 'Escape' && !this.open) {
+      event.stopPropagation();
+      this.displayInput.blur();
+    }
+
     // Handle enter and space. When pressing space, we allow for type to select behaviors so if there's anything in the
     // buffer we _don't_ close it. When search is enabled, space should type into the input, not toggle.
     if (event.key === 'Enter' || (event.key === ' ' && !this.search && this.typeToSelectString === '')) {

package/src/components/select/select.test.ts

@@ -152,4 +152,28 @@ describe('<zn-select>', () => {
       expect(visibleOptions[0].value).to.equal('apple');
     });
   });
+
+  describe('Escape key', () => {
+    it('blurs the display input when dropdown is closed and Escape is pressed', async () => {
+      const el = await fixture<ZnSelect>(html`<zn-select></zn-select>`);
+      await el.updateComplete;
+
+      const displayInput = el.shadowRoot!.querySelector<HTMLInputElement>('.select__display-input')!;
+      el.focus();
+      await el.updateComplete;
+      expect(el.shadowRoot!.activeElement).to.equal(displayInput);
+      expect(el.open).to.be.false;
+
+      displayInput.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+      await el.updateComplete;
+
+      expect(el.shadowRoot!.activeElement, 'display input should be blurred').to.not.equal(displayInput);
+    });
+
+  });
 });