@kubex/zinc 1.1.184 → 2.0.0

package/src/events/zn-report-change.ts

@@ -0,0 +1,7 @@
+export type ZnReportChangeEvent = CustomEvent<{type: string; groupBy: string; from: string; to: string; filter: string}>;
+
+declare global {
+  interface GlobalEventHandlersEventMap {
+    'zn-report-change': ZnReportChangeEvent;
+  }
+}

package/src/form-control.scss

@@ -1,5 +1,5 @@
 .form-control-input {
-  margin: var(--zn-spacing-2x-small) 3px 3px 0;
+  margin: var(--zn-form-control-input-margin, var(--zn-spacing-2x-small) 3px 3px 0);
 }
 
 .form-control-input--flush {
@@ -15,12 +15,13 @@
 }
 
 /* Label */
+// Inline-block sits in the inherited line box, which can be taller than the label; block sizes it to its own line.
 .form-control--has-label .form-control__label {
-  display: inline-block;
+  display: var(--zn-input-label-display, inline-block);
   color: var(--zn-input-label-color);
   font-weight: var(--zn-input-label-font-weight);
   line-height: var(--zn-input-label-line-height);
-  margin-bottom: var(--zn-spacing-x-small);
+  margin-bottom: var(--zn-input-label-spacing, var(--zn-spacing-x-small));
 }
 
 .form-control--has-label.form-control--medium .form-control__label {
@@ -37,6 +38,28 @@
   color: var(--zn-input-required-content-color);
 }
 
+.form-control__label-note {
+  margin-inline-start: var(--zn-input-label-note-offset, var(--zn-spacing-2x-small));
+  color: var(--zn-input-help-text-color);
+  font-weight: var(--zn-font-weight-normal, 400);
+}
+
+.form-control--has-label-tooltip .form-control__label-note {
+  margin-inline-start: 0;
+}
+
+.form-control--small .form-control__label-note {
+  font-size: var(--zn-input-help-text-font-size-small);
+}
+
+.form-control--medium .form-control__label-note {
+  font-size: var(--zn-input-help-text-font-size-medium);
+}
+
+.form-control--large .form-control__label-note {
+  font-size: var(--zn-input-help-text-font-size-large);
+}
+
 .form-control--has-label.form-control--radio-group .form-control__label,
 .form-control--has-label.form-control--checkbox-group .form-control__label {
   margin-bottom: 0;
@@ -60,6 +83,11 @@
   zn-icon {
     --icon-color: var(--zn-color-neutral-700);
     --icon-size: var(--zn-font-size-small);
+
+    &:focus-visible {
+      outline: var(--zn-focus-ring);
+      border-radius: var(--zn-border-radius-small);
+    }
   }
 }
 
@@ -100,6 +128,11 @@
   margin-top: var(--zn-spacing-small);
 }
 
+// Unset, the declaration is invalid at computed time and the line height inherits as before.
+.form-control--has-help-text .form-control__help-text {
+  line-height: var(--zn-input-help-text-line-height);
+}
+
 .form-control--has-help-text.form-control--small .form-control__help-text {
   font-size: var(--zn-input-help-text-font-size-small);
 }

package/src/internal/anchored-popover.ts

@@ -0,0 +1,175 @@
+import type {ReactiveController, ReactiveControllerHost} from 'lit';
+
+export type PopoverHideReason = 'escape' | 'outside' | 'api';
+
+interface AnchoredPopoverOptions {
+  /** Selector, in the host's shadow root, of the element the popover hangs from. */
+  trigger: string;
+  /** Selector, in the host's shadow root, of the popover. */
+  popover: string;
+  /** The popover's rendered width in px, used to keep it on screen. */
+  width: () => number;
+  /** Which trigger edge the popover lines up with; it flips when that would run off screen. */
+  align: 'start' | 'end';
+  /** Called whenever the popover closes, with how it was closed. */
+  onHide?: (reason: PopoverHideReason) => void;
+  /**
+   * Selectors, in the popover, tried in order for the element to focus once it opens. When set, focus goes back to the
+   * trigger as it closes, unless it has already moved somewhere else.
+   */
+  focus?: string[];
+}
+
+/**
+ * A fixed-position popover anchored under a trigger in the host's shadow root, closed by Escape or a click outside
+ * both. Fixed so a panel's overflow can't clip it.
+ */
+export class AnchoredPopoverController implements ReactiveController {
+  open = false;
+  position = {top: 0, left: 0};
+  private readonly host: ReactiveControllerHost & HTMLElement;
+  private readonly opts: AnchoredPopoverOptions;
+  private observed: HTMLElement | null = null;
+  // Children such as zn-input render after the host, so the height settles later; refitting inside the callback
+  // itself trips WebKit's ResizeObserver loop error
+  private readonly resizes = new ResizeObserver(() => requestAnimationFrame(() => this.refit()));
+
+  constructor(host: ReactiveControllerHost & HTMLElement, opts: AnchoredPopoverOptions) {
+    this.host = host;
+    this.opts = opts;
+    host.addController(this);
+  }
+
+  hostConnected() {
+    this.host.addEventListener('keydown', this.keydown);
+    document.addEventListener('keydown', this.keydown);
+    document.addEventListener('click', this.outsideClick);
+    window.addEventListener('resize', this.reposition);
+    window.addEventListener('scroll', this.reposition, true);
+  }
+
+  hostDisconnected() {
+    this.host.removeEventListener('keydown', this.keydown);
+    document.removeEventListener('keydown', this.keydown);
+    document.removeEventListener('click', this.outsideClick);
+    window.removeEventListener('resize', this.reposition);
+    window.removeEventListener('scroll', this.reposition, true);
+    this.resizes.disconnect();
+    this.observed = null;
+  }
+
+  // The height is only known once rendered; a fixed popover running off the bottom can't be scrolled to
+  hostUpdated() {
+    const pop = this.open ? this.popover() : null;
+    if (pop !== this.observed) {
+      this.resizes.disconnect();
+      if (pop) this.resizes.observe(pop);
+      this.observed = pop;
+    }
+    this.refit();
+  }
+
+  private refit() {
+    if (!this.open) return;
+    const top = this.position.top;
+    this.place();
+    if (this.position.top !== top) {
+      this.host.requestUpdate();
+    }
+  }
+
+  get style(): string {
+    return `top: ${this.position.top}px; left: ${this.position.left}px`;
+  }
+
+  show() {
+    this.place();
+    this.open = true;
+    this.host.requestUpdate();
+    const selectors = this.opts.focus;
+    if (selectors) {
+      void this.host.updateComplete.then(() => {
+        const pop = this.popover();
+        selectors.map(selector => pop?.querySelector<HTMLElement>(selector)).find(Boolean)?.focus();
+      });
+    }
+  }
+
+  hide(reason: PopoverHideReason = 'api') {
+    if (!this.open) return;
+    if (this.opts.focus && this.focusIsLost()) {
+      this.focusTrigger();
+    }
+    this.open = false;
+    this.host.requestUpdate();
+    this.opts.onHide?.(reason);
+  }
+
+  trigger(): HTMLElement | null {
+    return this.host.shadowRoot?.querySelector<HTMLElement>(this.opts.trigger) ?? null;
+  }
+
+  private popover(): HTMLElement | null {
+    return this.host.shadowRoot?.querySelector<HTMLElement>(this.opts.popover) ?? null;
+  }
+
+  private focusIsLost(): boolean {
+    const active = this.host.shadowRoot?.activeElement;
+    if (active) return !!this.popover()?.contains(active);
+    return !document.activeElement || document.activeElement === document.body;
+  }
+
+  private focusTrigger() {
+    const trigger = this.trigger();
+    (trigger?.shadowRoot?.querySelector<HTMLElement>('button, a') ?? trigger)?.focus();
+  }
+
+  private place() {
+    const trigger = this.trigger();
+    if (!trigger) return;
+    const rect = trigger.getBoundingClientRect();
+    const width = this.opts.width();
+    const start = rect.left;
+    const end = rect.right - width;
+    const fitsStart = start + width <= window.innerWidth - 8;
+    const fitsEnd = end >= 8;
+    const left = this.opts.align === 'start'
+      ? (fitsStart || !fitsEnd ? start : end)
+      : (fitsEnd || !fitsStart ? end : start);
+    const height = this.popover()?.offsetHeight ?? 0;
+    const below = rect.bottom + 4;
+    const above = rect.top - 4 - height;
+    let top = below;
+    if (below + height > window.innerHeight - 8) {
+      top = above >= 8 ? above : Math.max(8, window.innerHeight - height - 8);
+    }
+    this.position = {
+      top,
+      left: Math.max(8, Math.min(left, window.innerWidth - width - 8)),
+    };
+  }
+
+  private outsideClick = (e: MouseEvent) => {
+    if (!this.open) return;
+    const path = e.composedPath();
+    const pop = this.popover();
+    const trigger = this.trigger();
+    if ((pop && path.includes(pop)) || (trigger && path.includes(trigger))) return;
+    this.hide('outside');
+  };
+
+  // Also bound on the host so it runs before an enclosing dialog's own Escape handling
+  private keydown = (e: KeyboardEvent) => {
+    if (e.key !== 'Escape' || !this.open) return;
+    e.stopPropagation();
+    e.preventDefault();
+    this.hide('escape');
+  };
+
+  private reposition = () => {
+    if (this.open) {
+      this.place();
+      this.host.requestUpdate();
+    }
+  };
+}

package/src/internal/animate.ts

@@ -1,22 +1,36 @@
+// Keep in sync with --zn-ease-* in scss/themes/_light.scss; WAAPI easing can't read var().
+export const EASE_OUT = 'cubic-bezier(0.23, 1, 0.32, 1)';
+export const EASE_DRAWER = 'cubic-bezier(0.32, 0.72, 0, 1)';
+
 /**
  * Animates an element using keyframes. Returns a promise that resolves after the animation completes or gets canceled.
  */
-export function animateTo(el: HTMLElement, keyframes: Keyframe[], options?: KeyframeAnimationOptions) {
+export function animateTo(el: Element, keyframes: Keyframe[], options?: KeyframeAnimationOptions) {
   return new Promise(resolve => {
     if (options?.duration === Infinity) {
       throw new Error('Promise-based animations must be finite.');
     }
 
-    const animation = el.animate(keyframes, {
-      ...options,
-      duration: prefersReducedMotion() ? 0 : options!.duration
-    });
+    let animation: Animation;
+    if (prefersReducedMotion()) {
+      const fade = reduceKeyframes(keyframes);
+      const fades = fade.some(keyframe => 'opacity' in keyframe);
+      animation = el.animate(fade, {...options, duration: fades ? Math.min(Number(options?.duration ?? 0), 150) : 0});
+    } else {
+      animation = el.animate(keyframes, options);
+    }
 
     animation.addEventListener('cancel', resolve, {once: true});
     animation.addEventListener('finish', resolve, {once: true});
   });
 }
 
+/** Keeps only the opacity of each keyframe: fades still aid comprehension under reduced motion, movement doesn't. */
+function reduceKeyframes(keyframes: Keyframe[]): Keyframe[] {
+  const kept = ['offset', 'easing', 'composite', 'opacity'];
+  return keyframes.map(keyframe => Object.fromEntries(Object.entries(keyframe).filter(([key]) => kept.includes(key))));
+}
+
 /** Parses a CSS duration and returns the number of milliseconds. */
 export function parseDuration(delay: number | string) {
   delay = delay.toString().toLowerCase();

package/src/internal/cosmic-border.ts

@@ -0,0 +1,15 @@
+let registered = false;
+
+/** Registers `--rotate` so the cosmic border's gradient can animate; `@property` rules inside a shadow root are ignored. */
+export function registerCosmicBorder() {
+  if (registered || !window.CSS.registerProperty) {
+    return;
+  }
+
+  registered = true;
+  try {
+    window.CSS.registerProperty({name: '--rotate', syntax: '<angle>', inherits: false, initialValue: '0deg'});
+  } catch {
+    // Already registered by another copy of zinc on the page
+  }
+}

package/src/internal/form.ts

@@ -442,7 +442,7 @@ export class FormControlController implements ReactiveController {
       this.host.isConnected &&
       !disabled &&
       !isButton &&
-      name.length > 0 &&
+      !!name &&
       typeof value !== 'undefined'
     ) {
       const isPassword = (this.host as HTMLElement & { type?: string }).type === 'password';

package/src/internal/hover-intent.ts

@@ -0,0 +1,15 @@
+/** How long the pointer must rest on an element before hover preloading starts. */
+export const HOVER_INTENT_DELAY = 150;
+
+/**
+ * Calls `callback` once the pointer has rested on `element` for `delay` ms. Preloads hang off this
+ * so sweeping across a row of tabs doesn't fetch and render every panel on the way past.
+ */
+export function onHoverIntent(element: HTMLElement, callback: () => void, delay = HOVER_INTENT_DELAY): void {
+  let timer = 0;
+  element.addEventListener('mouseenter', () => {
+    clearTimeout(timer);
+    timer = window.setTimeout(callback, delay);
+  });
+  element.addEventListener('mouseleave', () => clearTimeout(timer));
+}

package/src/internal/input-modality.ts

@@ -0,0 +1,15 @@
+let lastPointerAt = -Infinity;
+let lastPointerPath: EventTarget[] = [];
+let lastKeyAt = -Infinity;
+
+// Capture phase, so a component that stops propagation can't hide the input.
+document.addEventListener('pointerdown', (e) => {
+  lastPointerAt = performance.now();
+  lastPointerPath = e.composedPath();
+}, {capture: true, passive: true});
+document.addEventListener('keydown', () => (lastKeyAt = performance.now()), {capture: true, passive: true});
+
+/** Whether the latest user input was a pointer press inside `within`, made within the last `withinMs`. */
+export function pointerInitiated(within: Element, withinMs = 300): boolean {
+  return lastPointerAt > lastKeyAt && performance.now() - lastPointerAt < withinMs && lastPointerPath.includes(within);
+}

package/src/internal/pointer-intent.ts

@@ -0,0 +1,37 @@
+import type {ReactiveController, ReactiveControllerHost} from 'lit';
+
+/**
+ * Tells a control whether its latest state change came from a pointer press, so keyboard and
+ * programmatic changes (arrow keys, select-all, value sync) can skip their animation.
+ */
+export class PointerIntentController implements ReactiveController {
+  private host: ReactiveControllerHost & HTMLElement;
+  private pressed = false;
+  private readonly handlePointerDown = () => (this.pressed = true);
+  private readonly handleKeyDown = () => (this.pressed = false);
+  // A press that changed nothing (dragged off, disabled) mustn't leak into the next change
+  private readonly handleClick = () => setTimeout(() => (this.pressed = false));
+
+  constructor(host: ReactiveControllerHost & HTMLElement) {
+    (this.host = host).addController(this);
+  }
+
+  hostConnected() {
+    this.host.addEventListener('pointerdown', this.handlePointerDown);
+    this.host.addEventListener('keydown', this.handleKeyDown);
+    this.host.addEventListener('click', this.handleClick);
+  }
+
+  hostDisconnected() {
+    this.host.removeEventListener('pointerdown', this.handlePointerDown);
+    this.host.removeEventListener('keydown', this.handleKeyDown);
+    this.host.removeEventListener('click', this.handleClick);
+  }
+
+  /** Whether the change being handled now was pointer-initiated. Call synchronously from the state-change handler. */
+  consume() {
+    const pressed = this.pressed;
+    this.pressed = false;
+    return pressed;
+  }
+}