@zeyos/zx 2.1.0 → 2.2.1

package/src/components/stepper/steps.js

@@ -0,0 +1,131 @@
+/**
+ * DOM-free step-list logic shared by {@link Stepper}: validation, normalization, and the
+ * index arithmetic behind `next()` / `previous()`.
+ * @module components/stepper/steps
+ */
+
+/**
+ * @typedef {Object} StepDefinition
+ * @property {string} name Stable step name, unique within the stepper.
+ * @property {string} title Visible step title.
+ * @property {string} [description] Secondary line rendered under the title.
+ * @property {boolean} [optional=false] Marks the step as skippable.
+ * @property {boolean} [disabled=false] Whether the step can be activated.
+ */
+
+/**
+ * @typedef {Object} NormalizedStep
+ * @property {string} name Stable step name.
+ * @property {string} title Visible step title.
+ * @property {string|null} description Secondary line, or null.
+ * @property {boolean} optional Whether the step is skippable.
+ * @property {boolean} disabled Whether the step can be activated.
+ */
+
+/**
+ * Validates and normalizes a step list. Every step needs a unique non-empty name; every other
+ * property is coerced to its documented type.
+ * @param {StepDefinition[]} list Step definitions.
+ * @returns {NormalizedStep[]} Normalized copies — the input objects are never mutated.
+ * @throws {TypeError} When the list or a step is malformed.
+ * @throws {RangeError} When two steps share a name.
+ */
+export function normalizeSteps(list) {
+  if (!Array.isArray(list)) throw new TypeError('Stepper steps must be an array');
+  const names = new Set();
+  return list.map((step) => {
+    if (!step || typeof step !== 'object' || Array.isArray(step)) {
+      throw new TypeError('Step definition must be an object');
+    }
+    if (typeof step.name !== 'string' || step.name === '') {
+      throw new TypeError('Step name must be a non-empty string');
+    }
+    if (names.has(step.name)) throw new RangeError(`Step already exists: ${step.name}`);
+    names.add(step.name);
+    return {
+      name: step.name,
+      title: String(step.title ?? ''),
+      description: step.description == null ? null : String(step.description),
+      optional: Boolean(step.optional),
+      disabled: Boolean(step.disabled)
+    };
+  });
+}
+
+/**
+ * Returns the index of a step by name.
+ * @param {NormalizedStep[]} steps Normalized steps.
+ * @param {string|null} name Step name.
+ * @returns {number} Zero-based index, or -1 when the name is unknown or null.
+ */
+export function stepIndex(steps, name) {
+  if (name === null) return -1;
+  return steps.findIndex((step) => step.name === name);
+}
+
+/**
+ * Resolves the next enabled step in a direction, skipping disabled steps. Starting from -1 walks
+ * in from the matching end, so `resolveStepIndex(steps, -1, 1)` is the first enabled step.
+ * @param {NormalizedStep[]} steps Normalized steps.
+ * @param {number} from Zero-based index to start from, or -1 for "outside the list".
+ * @param {number} direction Positive to move forward, negative to move backward.
+ * @returns {number} Zero-based index, or -1 when no enabled step lies that way.
+ */
+export function resolveStepIndex(steps, from, direction) {
+  const step = direction < 0 ? -1 : 1;
+  let cursor = from < 0 ? (step > 0 ? 0 : steps.length - 1) : from + step;
+  while (cursor >= 0 && cursor < steps.length) {
+    if (!steps[cursor].disabled) return cursor;
+    cursor += step;
+  }
+  return -1;
+}
+
+/**
+ * Names of the steps a move marks complete. Advancing past a step completes it — including every
+ * step skipped over by a jump — while moving backwards completes nothing, so a user can walk back
+ * through a wizard without erasing their progress.
+ * @param {NormalizedStep[]} steps Normalized steps.
+ * @param {number} from Zero-based index being left, or -1 when nothing was active.
+ * @param {number} to Zero-based index being activated.
+ * @returns {string[]} Names to add to the completed set, in step order.
+ */
+export function completedByAdvance(steps, from, to) {
+  if (from < 0 || to <= from) return [];
+  return steps.slice(from, to).map((step) => step.name);
+}
+
+/**
+ * @typedef {Object} StepStateContext
+ * @property {number} [activeIndex=-1] Zero-based active index, or -1 when nothing is active.
+ * @property {Set<string>|string[]} [completed] Completed step names.
+ * @property {Set<string>|string[]} [errored] Errored step names.
+ */
+
+/**
+ * Resolves the rendered state of one step. Errors win over everything, so a step the user has to
+ * come back and fix stays visible as a problem even while it is the active one; being active in
+ * turn wins over being complete, because where the user stands matters more than where they have
+ * already been.
+ * @param {NormalizedStep} step Normalized step.
+ * @param {number} index Zero-based index of the step.
+ * @param {StepStateContext} [context={}] Rail state.
+ * @returns {'upcoming'|'active'|'complete'|'error'}
+ */
+export function stepState(step, index, context = {}) {
+  const { activeIndex = -1, completed, errored } = context;
+  if (contains(errored, step.name)) return 'error';
+  if (index === activeIndex) return 'active';
+  if (contains(completed, step.name)) return 'complete';
+  return 'upcoming';
+}
+
+/**
+ * @param {Set<string>|string[]|undefined|null} source Set or array of names.
+ * @param {string} name Name to look for.
+ * @returns {boolean}
+ */
+function contains(source, name) {
+  if (!source) return false;
+  return source instanceof Set ? source.has(name) : source.includes(name);
+}

package/src/components/tabbox/tabbox.css

@@ -0,0 +1,281 @@
+/*
+ * Four tab appearances, all square-cornered by default:
+ *
+ *   divided    (default) flat blocks on a muted track, split by hairline dividers, the active
+ *              block lifted onto the panel surface under an accent rule — the workhorse for a
+ *              record page or a panel that owns its content box.
+ *   bracket    folder tabs that outline and fuse into the panel below, the active tab bridging
+ *              the seam — for document-like views where the tabs belong to the sheet.
+ *   segmented  a compact group on a muted fill, the active tab raised onto a control surface —
+ *              for switching a view inside a toolbar or card header, where the row reads as one
+ *              control rather than as navigation.
+ *   line       a full-width rule with the active tab underlined — for page- and section-level
+ *              navigation, where the row spans the content it switches.
+ *
+ * `divided` and `bracket` draw the panel box themselves; `line` and `segmented` leave the panel
+ * bare so the surrounding layout supplies the chrome.
+ */
+
+.zx-tabbox {
+  /* Corner rounding for the boxed variants. 0 keeps every corner square; set it to
+     `var(--zx-radius-lg)` on the root for the rounded pill group Zx shipped previously. */
+  --zx-tabbox-radius: 0px;
+  min-inline-size: 0;
+}
+
+.zx-tabbox__tablist {
+  display: flex;
+  align-items: stretch;
+  /* Horizontal-only scroll for overflowing tab rows. Setting overflow-x alone would
+     compute overflow-y to auto and reveal a phantom vertical scrollbar, so pin it. */
+  overflow-x: auto;
+  overflow-y: hidden;
+  scrollbar-width: none;
+  scrollbar-gutter: auto;
+}
+
+.zx-tabbox__tablist::-webkit-scrollbar {
+  display: none;
+}
+
+.zx-tabbox__tab {
+  position: relative;
+  display: inline-flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: center;
+  gap: var(--zx-space-2);
+  /* `styles/base.css` gives every bare button the control height as a minimum and the control
+     radius as its corners. Both have to be cleared here: the tab sets its own height per variant —
+     and segmented asks for 100% of a track shorter than that — while the corners belong to
+     `--zx-tabbox-radius`, which is square by default. Left in place, `divided` and `line` would
+     keep a rounded fill inside a squared row. The variants that want corners set them below. */
+  min-block-size: 0;
+  border: 0;
+  border-radius: 0;
+  background: none;
+  color: var(--zx-color-text-muted);
+  font: inherit;
+  font-size: var(--zx-control-font-size);
+  font-weight: 500;
+  white-space: nowrap;
+  cursor: pointer;
+}
+
+.zx-tabbox__tab:hover:not([aria-disabled="true"]) {
+  color: var(--zx-color-text);
+}
+
+.zx-tabbox__tab[aria-selected="true"] {
+  color: var(--zx-color-text);
+}
+
+.zx-tabbox__tab[aria-disabled="true"] {
+  color: var(--zx-color-text-placeholder);
+  cursor: not-allowed;
+}
+
+.zx-tabbox__icon {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+}
+
+/* ------------------------------------------------------------- divided variant -- */
+
+.zx-tabbox[data-variant="divided"] .zx-tabbox__tablist {
+  border-block-end: 1px solid var(--zx-color-border);
+  background: var(--zx-color-bg-muted);
+}
+
+.zx-tabbox[data-variant="divided"] .zx-tabbox__tab {
+  block-size: calc(var(--zx-control-height) + 8px);
+  /* The top rule is the selected marker; transparent here keeps every block the same height. */
+  border-block-start: 2px solid transparent;
+  border-inline-end: 1px solid var(--zx-color-border);
+  padding-inline: var(--zx-space-4);
+}
+
+.zx-tabbox[data-variant="divided"] .zx-tabbox__tab:last-child {
+  border-inline-end: 0;
+}
+
+.zx-tabbox[data-variant="divided"] .zx-tabbox__tab:hover:not([aria-disabled="true"]):not([aria-selected="true"]) {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-tabbox[data-variant="divided"] .zx-tabbox__tab[aria-selected="true"] {
+  border-block-start-color: var(--zx-color-accent);
+  background: var(--zx-color-bg-surface);
+  font-weight: 650;
+}
+
+.zx-tabbox[data-variant="divided"] .zx-tabbox__tab:focus-visible {
+  z-index: 1;
+  outline: 0;
+  box-shadow: inset var(--zx-focus-ring);
+}
+
+/* ------------------------------------------------------------- bracket variant -- */
+
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__tablist {
+  border-block-end: 1px solid var(--zx-color-border);
+  padding-inline-start: var(--zx-space-2);
+}
+
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__tab {
+  block-size: calc(var(--zx-control-height) + 8px);
+  /* Pulled down over the tablist rule so the active tab's own fill erases the seam below it. */
+  margin-block-end: -1px;
+  border: 1px solid transparent;
+  border-block-end: 0;
+  border-start-start-radius: var(--zx-tabbox-radius);
+  border-start-end-radius: var(--zx-tabbox-radius);
+  padding-inline: var(--zx-space-4);
+}
+
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__tab:hover:not([aria-disabled="true"]):not([aria-selected="true"]) {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__tab[aria-selected="true"] {
+  border-color: var(--zx-color-border);
+  background: var(--zx-color-bg-surface);
+  font-weight: 650;
+}
+
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__tab[aria-selected="true"]::after {
+  content: "";
+  position: absolute;
+  inset-inline: -1px;
+  inset-block-end: -1px;
+  block-size: 1px;
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__tab:focus-visible {
+  z-index: 1;
+  outline: 0;
+  box-shadow: inset var(--zx-focus-ring);
+}
+
+/* ----------------------------------------------------------------- line variant -- */
+
+.zx-tabbox[data-variant="line"] .zx-tabbox__tablist {
+  border-block-end: 1px solid var(--zx-color-border);
+}
+
+.zx-tabbox[data-variant="line"] .zx-tabbox__tab {
+  block-size: calc(var(--zx-control-height) + 8px);
+  border-block-end: 2px solid transparent;
+  padding-inline: var(--zx-space-4);
+}
+
+.zx-tabbox[data-variant="line"] .zx-tabbox__tab:hover:not([aria-disabled="true"]) {
+  border-block-end-color: var(--zx-color-border-strong);
+}
+
+.zx-tabbox[data-variant="line"] .zx-tabbox__tab[aria-selected="true"] {
+  border-block-end-color: var(--zx-color-accent);
+  font-weight: 600;
+}
+
+.zx-tabbox[data-variant="line"] .zx-tabbox__tab:focus-visible {
+  z-index: 1;
+  outline: 0;
+  box-shadow: inset var(--zx-focus-ring);
+}
+
+/* ------------------------------------------------------------- segmented variant -- */
+
+.zx-tabbox[data-variant="segmented"] .zx-tabbox__tablist {
+  inline-size: fit-content;
+  max-inline-size: 100%;
+  align-items: center;
+  gap: 2px;
+  block-size: var(--zx-control-height);
+  border-radius: var(--zx-tabbox-radius);
+  background: var(--zx-color-bg-muted);
+  padding: 3px;
+}
+
+.zx-tabbox[data-variant="segmented"] .zx-tabbox__tab {
+  block-size: 100%;
+  /* A transparent border keeps the active and inactive boxes the same size. */
+  border: 1px solid transparent;
+  /* Nested inside the track's 3px padding, so the inner corner is one step tighter. */
+  border-radius: max(0px, calc(var(--zx-tabbox-radius) - 2px));
+  padding-inline: var(--zx-space-3);
+  font-size: var(--zx-text-sm);
+}
+
+.zx-tabbox[data-variant="segmented"] .zx-tabbox__tab:hover:not([aria-disabled="true"]):not([aria-selected="true"]) {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-tabbox[data-variant="segmented"] .zx-tabbox__tab[aria-selected="true"] {
+  border-color: var(--zx-color-border-control);
+  background: var(--zx-color-bg-control);
+  box-shadow: var(--zx-shadow-2);
+}
+
+.zx-tabbox[data-variant="segmented"] .zx-tabbox__tab:focus-visible {
+  z-index: 1;
+  outline: 0;
+  border-color: var(--zx-color-ring);
+  box-shadow: var(--zx-focus-ring);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-tabbox__tab {
+    transition: color var(--zx-dur-fast) var(--zx-ease),
+      background-color var(--zx-dur-fast) var(--zx-ease),
+      border-color var(--zx-dur-fast) var(--zx-ease),
+      box-shadow var(--zx-dur-fast) var(--zx-ease);
+  }
+}
+
+/* ---------------------------------------------------------------- badge & close -- */
+
+.zx-tabbox__badge {
+  min-inline-size: 1.25rem;
+  border-radius: var(--zx-radius-full);
+  background: var(--zx-color-accent);
+  padding-inline: var(--zx-space-1);
+  color: var(--zx-color-on-accent);
+  font-size: var(--zx-text-xs);
+  font-weight: 700;
+  line-height: 1.25rem;
+  text-align: center;
+}
+
+.zx-tabbox__close {
+  margin-inline-start: calc(-1 * var(--zx-space-1));
+  color: var(--zx-color-text-muted);
+}
+
+/* ----------------------------------------------------------------------- panels -- */
+
+.zx-tabbox__panel {
+  padding-block-start: var(--zx-space-4);
+}
+
+/* The boxed variants own their panel chrome, so the tabs read as attached to the sheet. */
+.zx-tabbox[data-variant="divided"] .zx-tabbox__panels,
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__panels {
+  border: 1px solid var(--zx-color-border);
+  border-block-start: 0;
+  border-end-start-radius: var(--zx-tabbox-radius);
+  border-end-end-radius: var(--zx-tabbox-radius);
+  background: var(--zx-color-bg-surface);
+}
+
+.zx-tabbox[data-variant="divided"] .zx-tabbox__panel,
+.zx-tabbox[data-variant="bracket"] .zx-tabbox__panel {
+  padding: var(--zx-space-4);
+}
+
+.zx-tabbox__panel:focus-visible {
+  outline: 0;
+  box-shadow: inset var(--zx-focus-ring);
+}