@zeyos/zx 2.1.0 → 2.2.0

package/src/components/skeleton/skeleton.css

@@ -0,0 +1,76 @@
+.zx-skeleton {
+  display: block;
+  background: var(--zx-color-bg-muted);
+  border-radius: var(--zx-radius-sm);
+}
+
+.zx-skeleton[data-radius="md"] {
+  border-radius: var(--zx-radius-md);
+}
+
+.zx-skeleton[data-radius="full"] {
+  border-radius: var(--zx-radius-full);
+}
+
+.zx-skeleton-text {
+  display: flex;
+  flex-direction: column;
+  gap: var(--zx-space-2);
+}
+
+.zx-skeleton-table {
+  display: flex;
+  flex-direction: column;
+  gap: var(--zx-space-1);
+  inline-size: 100%;
+}
+
+.zx-skeleton-table__row {
+  display: grid;
+  grid-template-columns: repeat(var(--zx-skeleton-columns, 4), minmax(0, 1fr));
+  gap: var(--zx-space-4);
+  align-items: center;
+  padding-block: var(--zx-space-3);
+  padding-inline: var(--zx-space-3);
+  border-block-end: 1px solid var(--zx-color-border);
+}
+
+/*
+ * The header reads through its blocks, not through a filled band: a muted row behind muted
+ * placeholders is one solid bar with no cells visible in it.
+ */
+.zx-skeleton-table__row[data-kind="header"] {
+  border-block-end-color: var(--zx-color-border-strong);
+}
+
+.zx-skeleton-table__row[data-kind="header"] .zx-skeleton {
+  background: var(--zx-color-border);
+}
+
+.zx-skeleton-table__row:last-child {
+  border-block-end: 0;
+}
+
+/*
+ * The pulse is the whole animation: a gradient sweep would need colours the token layer does not
+ * define, and reduced motion has to leave a legible static block behind either way.
+ */
+@media (prefers-reduced-motion: no-preference) {
+  .zx-skeleton {
+    animation: zx-skeleton-pulse 1400ms var(--zx-ease) infinite;
+  }
+
+  .zx-skeleton-text .zx-skeleton:nth-child(2n) {
+    animation-delay: 120ms;
+  }
+
+  .zx-skeleton-table__row:nth-child(2n) .zx-skeleton {
+    animation-delay: 120ms;
+  }
+}
+
+@keyframes zx-skeleton-pulse {
+  50% {
+    opacity: 0.5;
+  }
+}

package/src/components/skeleton/skeleton.js

@@ -0,0 +1,139 @@
+import { h } from '../../core/dom.js';
+import { clamp } from '../../core/util.js';
+
+/**
+ * @typedef {Object} SkeletonOptions
+ * @property {string|number} [width='100%'] Block width; a number is read as pixels.
+ * @property {string|number} [height='1rem'] Block height; a number is read as pixels.
+ * @property {'sm'|'md'|'full'} [radius='sm'] Corner rounding. `full` with equal width and height
+ *   gives the circle an avatar or icon placeholder needs.
+ */
+
+/**
+ * @typedef {Object} SkeletonTextOptions
+ * @property {number} [lines=3] Number of text lines.
+ * @property {string|number} [width='100%'] Width of the block as a whole.
+ * @property {boolean} [heading=false] Whether the first line is drawn taller, as a title.
+ * @property {string|number} [lastLineWidth='60%'] Width of the final line, which reads as prose
+ *   rather than as a filled rectangle.
+ */
+
+/**
+ * @typedef {Object} SkeletonTableOptions
+ * @property {number} [rows=5] Number of body rows.
+ * @property {number} [columns=4] Number of columns.
+ * @property {boolean} [header=true] Whether a header row is drawn.
+ */
+
+/**
+ * Creates one placeholder block.
+ *
+ * Skeletons stand in for content whose shape is already known, which is what makes them worth
+ * more than a spinner: the layout does not jump when the data arrives. Every skeleton is
+ * `aria-hidden`, because a screen reader gains nothing from an announced grey box — set
+ * `aria-busy="true"` on the region being filled instead, and remove it with the skeleton.
+ *
+ * @param {SkeletonOptions} [opts={}] Block options.
+ * @returns {HTMLSpanElement}
+ */
+export function skeleton(opts = {}) {
+  const options = { width: '100%', height: '1rem', radius: 'sm', ...opts };
+  return /** @type {HTMLSpanElement} */ (h('span', {
+    class: 'zx-skeleton',
+    ariaHidden: 'true',
+    dataset: { radius: RADII.has(options.radius) ? options.radius : 'sm' },
+    style: { 'inline-size': size(options.width), 'block-size': size(options.height) }
+  }));
+}
+
+/**
+ * Creates a stack of placeholder lines standing in for a paragraph or a labelled value.
+ * @param {SkeletonTextOptions} [opts={}] Text options.
+ * @returns {HTMLDivElement}
+ */
+export function skeletonText(opts = {}) {
+  const options = { lines: 3, width: '100%', heading: false, lastLineWidth: '60%', ...opts };
+  const lines = clamp(Math.trunc(Number(options.lines) || 0), 1, 20);
+  const element = /** @type {HTMLDivElement} */ (h('div', {
+    class: 'zx-skeleton-text',
+    ariaHidden: 'true',
+    style: { 'inline-size': size(options.width) }
+  }));
+
+  for (let index = 0; index < lines; index += 1) {
+    const heading = options.heading && index === 0;
+    const last = index === lines - 1 && lines > 1;
+    element.append(skeleton({
+      width: last ? options.lastLineWidth : '100%',
+      height: heading ? '1.5rem' : '0.75rem'
+    }));
+  }
+  return element;
+}
+
+/**
+ * Creates a placeholder grid the shape of a table that has not loaded yet.
+ *
+ * Rendered as plain elements rather than a `<table>`: there is no data to expose, and a table
+ * whose cells are all empty is worse for assistive technology than no table at all.
+ *
+ * @param {SkeletonTableOptions} [opts={}] Table options.
+ * @returns {HTMLDivElement}
+ */
+export function skeletonTable(opts = {}) {
+  const options = { rows: 5, columns: 4, header: true, ...opts };
+  const rows = clamp(Math.trunc(Number(options.rows) || 0), 1, 50);
+  const columns = clamp(Math.trunc(Number(options.columns) || 0), 1, 20);
+  const element = /** @type {HTMLDivElement} */ (h('div', {
+    class: 'zx-skeleton-table',
+    ariaHidden: 'true',
+    style: { '--zx-skeleton-columns': String(columns) }
+  }));
+
+  if (options.header !== false) {
+    element.append(row(columns, 'header'));
+  }
+  for (let index = 0; index < rows; index += 1) element.append(row(columns, 'body'));
+  return element;
+}
+
+const RADII = new Set(['sm', 'md', 'full']);
+
+/**
+ * Builds one placeholder row.
+ * @param {number} columns Number of cells.
+ * @param {'header'|'body'} kind Row kind.
+ * @returns {HTMLDivElement}
+ */
+function row(columns, kind) {
+  const element = /** @type {HTMLDivElement} */ (h('div', {
+    class: 'zx-skeleton-table__row',
+    dataset: { kind }
+  }));
+  for (let index = 0; index < columns; index += 1) {
+    element.append(h('span', { class: 'zx-skeleton-table__cell' },
+      skeleton({ width: cellWidth(index, columns), height: '0.75rem' })));
+  }
+  return element;
+}
+
+/**
+ * Cell widths that vary a little, so the placeholder reads as a table of values rather than as a
+ * bar chart of identical blocks.
+ * @param {number} index Column index.
+ * @param {number} columns Column count.
+ * @returns {string}
+ */
+function cellWidth(index, columns) {
+  if (index === columns - 1) return '55%';
+  return index % 2 === 0 ? '80%' : '65%';
+}
+
+/**
+ * Normalizes a CSS length, reading a bare number as pixels.
+ * @param {string|number} value Width or height.
+ * @returns {string}
+ */
+function size(value) {
+  return typeof value === 'number' ? `${value}px` : String(value ?? '');
+}

package/src/components/slider/field-adapter.js

@@ -0,0 +1,36 @@
+import { Field } from '../field/field.js';
+import { Slider } from './slider.js';
+
+/**
+ * Registers the Slider-backed `slider` field type.
+ * @returns {void}
+ */
+export function registerSliderFieldAdapter() {
+  Field.register('slider', (field, options) => {
+    const slider = field.own(new Slider(null, {
+      // The Field already renders the label, so the slider keeps it only for its own control.
+      label: options.label ? String(options.label) : undefined,
+      hideLabel: true,
+      disabled: Boolean(options.disabled),
+      ...(options.props ?? {})
+    }));
+    let setting = false;
+    slider.on('change', (event) => {
+      if (!setting) field.emit('change', { value: event.detail.value });
+    });
+    return {
+      el: slider.el,
+      get: () => slider.get(),
+      set: (value) => {
+        setting = true;
+        try {
+          slider.set(Number(value) || 0, { silent: true });
+        } finally {
+          setting = false;
+        }
+      },
+      focus: () => slider.focus(),
+      setDisabled: (value) => (value ? slider.disable() : slider.enable())
+    };
+  });
+}

package/src/components/slider/slider.css

@@ -0,0 +1,181 @@
+.zx-slider {
+  display: flex;
+  flex-direction: column;
+  gap: var(--zx-space-2);
+  inline-size: 100%;
+  --zx-slider-thumb: 16px;
+  --zx-slider-rail: 4px;
+}
+
+.zx-slider[data-size="sm"] {
+  --zx-slider-thumb: 12px;
+  --zx-slider-rail: 3px;
+}
+
+.zx-slider__head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: var(--zx-space-3);
+  font-size: var(--zx-control-font-size);
+}
+
+.zx-slider__label {
+  color: var(--zx-color-text);
+  font-weight: 500;
+}
+
+.zx-slider__value {
+  color: var(--zx-color-text-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+.zx-slider__value:empty {
+  display: none;
+}
+
+.zx-slider[data-hide-label] .zx-slider__label {
+  position: absolute;
+  clip-path: inset(50%);
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.zx-slider__control {
+  display: flex;
+  align-items: start;
+  gap: var(--zx-space-3);
+}
+
+/*
+ * The bounds centre on the RAIL, not on the control: with marks below it the track grows taller,
+ * and centring on the whole box would float `0` up beside the first mark label instead of beside
+ * the value it bounds. The offset is half the difference between the rail row and this line box.
+ */
+.zx-slider__bound {
+  flex: none;
+  align-self: start;
+  margin-block-start: calc((var(--zx-slider-thumb) - 1.5em) / 2);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-sm);
+  font-variant-numeric: tabular-nums;
+}
+
+.zx-slider__track {
+  position: relative;
+  flex: 1 1 auto;
+  min-inline-size: 0;
+}
+
+/*
+ * base.css gives every bare input the control box — a minimum height, a border, a radius, and
+ * inline padding. A range input wants none of them: the element IS the rail, so all four are
+ * cleared here rather than fought with later.
+ */
+.zx-slider__input {
+  display: block;
+  appearance: none;
+  inline-size: 100%;
+  min-block-size: 0;
+  block-size: var(--zx-slider-thumb);
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: none;
+  cursor: pointer;
+}
+
+.zx-slider__input::-webkit-slider-runnable-track {
+  block-size: var(--zx-slider-rail);
+  border-radius: var(--zx-radius-full);
+  background: linear-gradient(
+    to right,
+    var(--zx-color-accent) 0 var(--zx-slider-fill, 0%),
+    var(--zx-color-bg-muted) var(--zx-slider-fill, 0%) 100%
+  );
+}
+
+.zx-slider__input::-moz-range-track {
+  block-size: var(--zx-slider-rail);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-bg-muted);
+}
+
+.zx-slider__input::-moz-range-progress {
+  block-size: var(--zx-slider-rail);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+}
+
+.zx-slider__input::-webkit-slider-thumb {
+  appearance: none;
+  inline-size: var(--zx-slider-thumb);
+  block-size: var(--zx-slider-thumb);
+  /* Centres the thumb on the rail: half the difference between the two heights. */
+  margin-block-start: calc((var(--zx-slider-rail) - var(--zx-slider-thumb)) / 2);
+  border: 2px solid var(--zx-color-bg-surface);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  box-shadow: var(--zx-shadow-1);
+}
+
+.zx-slider__input::-moz-range-thumb {
+  inline-size: var(--zx-slider-thumb);
+  block-size: var(--zx-slider-thumb);
+  border: 2px solid var(--zx-color-bg-surface);
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  box-shadow: var(--zx-shadow-1);
+}
+
+.zx-slider__input:focus-visible {
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+  box-shadow: var(--zx-focus-ring);
+  border-radius: var(--zx-radius-full);
+}
+
+/* Wide enough for five digits beside the native spin buttons, which eat more room than they look. */
+.zx-slider__number {
+  flex: none;
+  align-self: start;
+  inline-size: 10ch;
+  text-align: end;
+  font-variant-numeric: tabular-nums;
+}
+
+.zx-slider__marks {
+  position: relative;
+  block-size: var(--zx-space-5);
+  margin-block-start: var(--zx-space-1);
+}
+
+.zx-slider__mark {
+  position: absolute;
+  inset-block-start: 0;
+  inset-inline-start: var(--zx-slider-mark, 0%);
+  transform: translateX(-50%);
+  color: var(--zx-color-text-muted);
+  font-size: var(--zx-text-xs);
+  white-space: nowrap;
+}
+
+.zx-slider[data-disabled] {
+  opacity: 0.55;
+}
+
+.zx-slider[data-disabled] .zx-slider__input,
+.zx-slider[data-readonly] .zx-slider__input {
+  cursor: not-allowed;
+}
+
+.zx-slider[data-readonly] .zx-slider__input::-webkit-slider-thumb {
+  background: var(--zx-color-text-muted);
+}
+
+.zx-slider[data-readonly] .zx-slider__input::-moz-range-thumb {
+  background: var(--zx-color-text-muted);
+}