@zeyos/zx 4.3.0 → 4.3.4

package/docs/api.json

@@ -1468,7 +1468,7 @@
       {
         "name": "minCardWidth",
         "type": "number|string",
-        "default": "'18rem'",
+        "default": "'15rem'",
         "description": "Responsive minimum card width."
       },
       {
@@ -4330,6 +4330,132 @@
         "default": "'local'",
         "description": "Whether accepted moves update local data."
       },
+      {
+        "name": "dragFrom",
+        "type": "'card'|'handle'",
+        "default": "'card'",
+        "description": "Whether the whole card or only its handle starts a pointer drag. Touch drags from the card body require a long press so the board still scrolls."
+      },
+      {
+        "name": "multiMove",
+        "type": "boolean",
+        "default": "true",
+        "description": "Move the whole selection when a selected card is picked up."
+      },
+      {
+        "name": "autoScroll",
+        "type": "boolean",
+        "default": "true",
+        "description": "Scroll the board and columns while dragging near an edge."
+      },
+      {
+        "name": "wipPolicy",
+        "type": "'warn'|'block'",
+        "default": "'warn'",
+        "description": "Whether exceeding a limit warns or refuses."
+      },
+      {
+        "name": "rules",
+        "type": "KanbanRule[]",
+        "default": "[]",
+        "description": "Ordered visual card rules."
+      },
+      {
+        "name": "search",
+        "type": "string",
+        "default": "''",
+        "description": "Board search text."
+      },
+      {
+        "name": "searchFields",
+        "type": "string[]|null",
+        "default": "null",
+        "description": "Field ids searched; null searches visible fields plus the title and subtitle sources."
+      },
+      {
+        "name": "filter",
+        "type": "((record:KanbanRecord,index:number)=>boolean)|null",
+        "default": "null",
+        "description": "Extra card predicate."
+      },
+      {
+        "name": "searchControl",
+        "type": "boolean",
+        "default": "false",
+        "description": "Render the built-in board search control."
+      },
+      {
+        "name": "history",
+        "type": "boolean",
+        "default": "true",
+        "description": "Record committed local moves for undo and redo."
+      },
+      {
+        "name": "historyLimit",
+        "type": "number",
+        "default": "50",
+        "description": "Maximum remembered move steps."
+      },
+      {
+        "name": "historyControls",
+        "type": "boolean",
+        "default": "false",
+        "description": "Render built-in undo and redo controls."
+      },
+      {
+        "name": "columnHeight",
+        "type": "string|null",
+        "default": "null",
+        "description": "CSS length turning each column into a scroll region."
+      },
+      {
+        "name": "allowAdd",
+        "type": "boolean|((column:KanbanColumn,swimlane:KanbanSwimlane|null)=>boolean)",
+        "default": "false",
+        "description": "Render a per-column add control that emits `recordadd`."
+      },
+      {
+        "name": "contextMenu",
+        "type": "boolean|MenuItem[]|((context:KanbanCardContext)=>MenuItem[])",
+        "default": "false",
+        "description": "Card context menu. `true` offers move commands; an array or function appends application items."
+      },
+      {
+        "name": "renderCard",
+        "type": "((context:KanbanCardContext)=>Node|null|undefined)|null",
+        "default": "null",
+        "description": "Replaces card content."
+      },
+      {
+        "name": "renderColumnHeader",
+        "type": "((context:KanbanHeaderContext)=>Node|null|undefined)|null",
+        "default": "null",
+        "description": "Replaces column header content."
+      },
+      {
+        "name": "renderSwimlaneHeader",
+        "type": "((context:KanbanHeaderContext)=>Node|null|undefined)|null",
+        "default": "null",
+        "description": "Replaces lane header content."
+      },
+      {
+        "name": "renderColumnEmpty",
+        "type": "((context:KanbanHeaderContext)=>Node|null|undefined)|null",
+        "default": "null",
+        "description": "Empty-column placeholder."
+      },
+      {
+        "name": "renderDragPreview",
+        "type": "((context:{records:KanbanRecord[],ids:unknown[],count:number})=>Node|null|undefined)|null",
+        "default": "null",
+        "description": "Replaces the floating drag preview."
+      },
+      {
+        "name": "labels",
+        "type": "Record<string,string>",
+        "default": "{}",
+        "description": "Overrides for every visible and announced string."
+      },
       {
         "name": "columnOrder",
         "type": "string[]",
@@ -4385,10 +4511,30 @@
         "payload": "Record<string,unknown>",
         "description": ""
       },
+      {
+        "name": "movereject",
+        "payload": "Record<string,unknown>",
+        "description": ""
+      },
       {
         "name": "recordaction",
         "payload": "Record<string,unknown>",
         "description": ""
+      },
+      {
+        "name": "recordadd",
+        "payload": "Record<string,unknown>",
+        "description": ""
+      },
+      {
+        "name": "searchchange",
+        "payload": "{search:string}",
+        "description": ""
+      },
+      {
+        "name": "historychange",
+        "payload": "{canUndo:boolean,canRedo:boolean,depth:{undo:number,redo:number}}",
+        "description": ""
       }
     ],
     "methods": [
@@ -4492,7 +4638,73 @@
         "name": "moveRecord",
         "signature": "moveRecord(id, destination)",
         "returns": "this",
-        "description": "Proposes and, in local mode, commits a record move. Destination acceptance is checked before a cancelable `recordmove` event. WIP limits are reported but remain advisory."
+        "description": "Proposes and, in local mode, commits a record move. Equivalent to `moveRecords([id], …)`."
+      },
+      {
+        "name": "moveRecords",
+        "signature": "moveRecords(ids, destination)",
+        "returns": "this",
+        "description": "Proposes and, in local mode, commits an atomic move of one or more records. Destination eligibility, transition rules, and work-in-progress policy are all checked before a single cancelable `recordmove` event; the move commits completely or not at all, and the moving records keep their relative order at the destination."
+      },
+      {
+        "name": "canUndo",
+        "signature": "canUndo()",
+        "returns": "boolean",
+        "description": "Whether a committed local move can be reverted."
+      },
+      {
+        "name": "canRedo",
+        "signature": "canRedo()",
+        "returns": "boolean",
+        "description": "Whether a reverted local move can be reapplied."
+      },
+      {
+        "name": "undo",
+        "signature": "undo()",
+        "returns": "this",
+        "description": "Reverts the last committed local move, restoring the exact record order and selection."
+      },
+      {
+        "name": "redo",
+        "signature": "redo()",
+        "returns": "this",
+        "description": "Reapplies the last reverted local move."
+      },
+      {
+        "name": "clearHistory",
+        "signature": "clearHistory()",
+        "returns": "this",
+        "description": "Empties both history stacks."
+      },
+      {
+        "name": "getSearch",
+        "signature": "getSearch()",
+        "returns": "string",
+        "description": "Returns the current board search text."
+      },
+      {
+        "name": "setSearch",
+        "signature": "setSearch(search, [options])",
+        "returns": "this",
+        "description": "Narrows visible cards to those matching a search. Hidden records keep their position in the data, so a card dropped between two visible cards still lands between them."
+      },
+      {
+        "name": "setFilter",
+        "signature": "setFilter(filter)",
+        "returns": "this",
+        "description": "Replaces the extra card predicate. Pass null to clear it."
+      },
+      {
+        "name": "getVisibleRecords",
+        "signature": "getVisibleRecords()",
+        "returns": "KanbanRecord[]",
+        "description": "Returns the records currently rendered, in board order."
+      },
+      {
+        "name": "setData",
+        "signature": "setData(records)",
+        "returns": "this",
+        "description": "Replaces every record. History is dropped because its snapshots describe records the host has just replaced, and reinstating them would resurrect data the application no longer owns."
       },
       {
         "name": "getViewState",

package/docs/llms.md

@@ -31,6 +31,8 @@ const t = new Table(target, options);
   (always an object, e.g. `{ value, item }`).
 - Every `emit` also dispatches a **bubbling, composed** `zx-<type>` `CustomEvent` on `t.el`, so
   `t.el.addEventListener('zx-change', …)` and event delegation work.
+- Mutation boundaries may opt into honoring cancellation of that mirrored DOM event; Kanban's
+  `zx-recordmove` does, so delegated hosts can veto a move without a component reference.
 - `t.destroy()` aborts all listeners (one AbortController), unregisters the element, and removes an
   owned root. `Component.from(el)` returns the component for a root element (replaces the legacy
   `el.retrieve('com')`).
@@ -253,28 +255,6 @@ reflection and ElementInternals form association: `<zx-toggle>`, `<zx-check-butt
 `<zx-checklist>`, `<zx-datebox>`, `<zx-timebox>`, `<zx-search>`, `<zx-groupbox>`, `<zx-tabbox>`,
 `<zx-table>`, `<zx-dialog>`.
 
-## Conventions (editing component source)
-
-Follow `AGENTS.md`. Key rules: never declare instance class fields for state used in `render()`
-(render runs inside the base constructor before field initializers); route all DOM listeners
-through `this.listen()`; no `innerHTML` outside `h.raw()`; express state via ARIA/`data-*`, not
-state classes; small glyph buttons use the shared `.zx-icon-btn` utility; follow the named APG
-pattern with `:focus-visible` rings and `prefers-reduced-motion` guards.
-
-## File map & commands
-
-```
-src/components/<name>/   component + CSS      src/core/   kernel (component, dom, http, i18n, date…)
-website/                 marketing page + docs.html (docs.js)          specs/  per-component specs
-website/demos/           per-component demo modules    website/layouts/  application layout examples
-tests/                   node unit + smoke    dist/       built bundles
-
-npm run serve   # http://127.0.0.1:8321/website/docs.html  (no build)
-npm test        # node --test tests/unit/*.test.js  +  node tests/lint-tokens.js
-npm run build   # dist/: ESM, global, ZeyOS binding, and CSS assets
-node tools/build-module-tokens.js   # regenerate styles/tokens/modules.css from src/zeyos/modules.js
-```
-
 ---
 
 # Components
@@ -1151,8 +1131,15 @@ portable state as TableView and KanbanView.
   `previewAlt`, `link`, `actions`, `groupBy`, `groupOrder`, `minCardWidth`, `maxColumns`,
   `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, and `label`.
 - **Cards** — each record is a focusable `<li>` with a native title link, separate secondary
-  actions, optional native multi-select checkbox, labelled metadata, and `aria-selected` state.
-  Title/subtitle fields are not duplicated in metadata unless their field sets `duplicate:true`.
+  actions, optional native multi-select checkbox, labelled metadata, and a global ARIA selection
+  description that retains valid listitem semantics.
+  CardView uses a dense collection rhythm: titles clamp to two lines, previews stay at
+  thumbnail/avatar scale, and visible fields become compact labelled metadata chips. Title/subtitle
+  fields are not duplicated in metadata unless their field sets `duplicate:true`.
+- **Shared card slots** — a visible field may set
+  `view.card.slot: 'eyebrow-start'|'eyebrow-end'|'title-prefix'`. These slots create a semantic
+  eyebrow row or put labelled content immediately before (and outside) the title heading/link.
+  Unknown slots remain ordinary metadata; visibility and field order still control rendering.
 - **Media and URLs** — `preview` accepts a field ID or callback returning an image URL,
   `{src,alt,fit}`, Node, or null. Executable/non-image schemes are rejected and image failures show
   a stable fallback. Title/action links are normalized; `_blank` links receive `noopener`.
@@ -1176,14 +1163,25 @@ cards, advisory work-in-progress limits, and equivalent pointer/programmatic/key
   columns may also declare an advisory `limit`.
 - **Methods** — configure/get/move columns and swim lanes, collapse either axis, and
   `moveRecord(id,{column?,lane?,index?})`. Board-specific order/collapse joins the common view
-  state; record order, movement history, and selection do not.
+  state; record order, movement history, and selection do not. Saved preferences for data-derived
+  axes survive an empty/partial result set and reconcile as later records introduce their IDs.
+- **Dense board layout** — bounded muted columns use a stable 20rem rail with native horizontal
+  overflow, 48px headings, compact counts, 8–12px card padding, and 8px card gaps. Surface cards
+  use an optional square thumbnail and a two-tier hierarchy from shared card field slots:
+  `eyebrow-start`, `eyebrow-end`, and `title-prefix`. Unslotted metadata stays as quiet inline
+  facts. Titles clamp visually to two lines while retaining their complete accessible text. Move
+  and action controls reveal on hover/focus/selection/grab, and remain visible on touch devices.
 - **Movement boundary** — `recordmove {record,id,from,to,column,swimlane,limitExceeded}` is
-  cancelable and fires before a commit/request. `accept` is a hard eligibility gate; WIP is visual
-  advice. Local mode clones the moved record and never mutates host data. External mode emits only,
-  for server validation and optimistic rollback owned by ZeyOS.
+  cancelable and fires before a commit/request; either the component event or bubbling
+  `zx-recordmove` mirror may veto it. `accept` is a hard eligibility gate; WIP is visual advice.
+  Local mode clones the moved record and never mutates host data, and a manual local move clears an
+  active local sort so saved state matches visible order. External mode emits only, for server
+  validation and optimistic rollback owned by ZeyOS.
 - **Keyboard** — focus the move handle; Enter/Space grabs or drops, Escape cancels, Left/Right
   chooses a column, Up/Down chooses a bucket-relative position, and Alt+Up/Down chooses a swim
-  lane. A polite live region announces every target and result. Native drag is an enhancement.
+  lane. A polite live region announces every target, result, and reached/exceeded WIP limit.
+  Collapse keeps focus on its control, including when a programmatic collapse hides the focused
+  card. Native drag is an enhancement.
 <!-- /doc -->
 
 <!-- doc:grid -->
@@ -1256,7 +1254,9 @@ windowed loader.
   HTML, and suspicious CSS colour strings are ignored.
 - **Methods** — `getEvents()`, `setEvents()`, `addEvent()`, `updateEvent()`, `removeEvent()`,
   `getDate()`, `setDate()`, `getView()`, `setView()`, `prev()`, `next()`, `today()`,
-  `setLoading()`, `focusEvent()`, `destroy()`.
+  `setLoading()`, `focusEvent()`, `destroy()`. `prev()`/`next()` step one visible period and clamp
+  the day of month into the target month, so a 29th–31st anchor cannot skip a shorter month; the
+  same arithmetic is exported as `calendarPageDate()` and `addCalendarMonths()`.
 - **Events** — `dateschange {view,start,end}`, `viewchange {view,oldView}`, `eventclick`,
   `eventdblclick`, `dateclick {date,allDay,view}`, `select {start,end,allDay,view}`,
   `new {date,view}`, `moreclick {date,count}`, `eventschange {events}`, and cancelable

package/docs/llms.txt

@@ -16,9 +16,7 @@ exports and as `window.zx.*`.
 - [Documentation site](https://zx.zeyos.com/docs.html): getting started, every component with a live demo and its JavaScript source, and the application layouts. Machine index: [llms.txt](https://zx.zeyos.com/llms.txt).
 - [README](../README.md): what Zx is, quick start (ESM + global script), component index, theming, and browser support.
 - [API reference](llms.md): per-component constructor options, methods, and events for all public components plus the core helpers.
-- [Skill](https://zx.zeyos.com/skills/zx/SKILL.md): task-oriented guide — mental model, recipes, ZeyOS HTTP client, theming, gotchas, commands.
 - [Changelog](../CHANGELOG.md): what changed in each release, including behaviour changes an upgrade has to account for.
-- [Contributor contract](https://github.com/zeyos/zx/blob/main/AGENTS.md): conventions for editing component source (token rules, render-time state, listeners, ARIA/APG).
 
 ## Components
 - Inputs: `button()`, `buttonGroup()`, `badge()`/`badgeGroup()`, `CheckButton`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/zx",
-  "version": "4.3.0",
+  "version": "4.3.4",
   "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
   "type": "module",
   "license": "MIT",
@@ -65,7 +65,6 @@
     "docs/api.json",
     "CHANGELOG.md",
     "README.md",
-    "DESIGN-SYSTEM.md",
     "LICENSE"
   ],
   "engines": {

package/src/components/calendar/calendar-model.js

@@ -70,6 +70,51 @@ export function calendarRange(view, anchor, options = {}) {
   return { start, end };
 }
 
+/**
+ * Returns the anchor date one visible period away from `anchor`.
+ *
+ * Month and year steps clamp the day of month into the target month instead of letting it
+ * overflow: `setMonth()` alone turns 31 January into 3 March, which makes February unreachable
+ * from a month-end anchor and leaves `prev()` on 31 March landing back inside March.
+ * @param {CalendarView} view Current view.
+ * @param {Date} anchor Current anchor date.
+ * @param {number} direction -1 for the previous period, 1 for the next.
+ * @param {{agendaDays?: number}} [options={}] Paging options.
+ * @returns {Date}
+ */
+export function calendarPageDate(view, anchor, direction, options = {}) {
+  const date = validDate(anchor, 'Calendar date');
+  const step = integer(direction, 'direction');
+  if (view === 'day') date.setDate(date.getDate() + step);
+  else if (view === 'agenda') {
+    date.setDate(date.getDate() + step * positiveInteger(options.agendaDays ?? 14, 'agendaDays'));
+  } else if (view === 'week') date.setDate(date.getDate() + step * 7);
+  else if (view === 'month') return addCalendarMonths(date, step);
+  else if (view === 'year') return addCalendarMonths(date, step * 12);
+  else throw new RangeError(`Unknown calendar view: ${view}`);
+  return date;
+}
+
+/**
+ * Adds whole months, clamping the day of month to the last day the target month actually has.
+ * @param {Date} value Local date.
+ * @param {number} months Months to add.
+ * @returns {Date}
+ */
+export function addCalendarMonths(value, months) {
+  const date = validDate(value, 'Calendar date');
+  const day = date.getDate();
+  date.setDate(1);
+  date.setMonth(date.getMonth() + integer(months, 'month amount'));
+  date.setDate(Math.min(day, daysInCalendarMonth(date.getFullYear(), date.getMonth())));
+  return date;
+}
+
+/** @param {number} year @param {number} month @returns {number} */
+function daysInCalendarMonth(year, month) {
+  return new Date(year, month + 1, 0).getDate();
+}
+
 /**
  * Normalizes caller records atomically into the Calendar event contract.
  * @param {Record<string, any>[]} records Source records.

package/src/components/calendar/calendar.css

@@ -9,15 +9,20 @@
   min-inline-size: 0;
   overflow: hidden;
   border: 1px solid var(--zx-color-border);
-  border-radius: var(--zx-radius-lg);
+  border-radius: 0;
   background: var(--zx-color-bg-surface);
   color: var(--zx-color-text);
   font-size: var(--zx-text-sm);
 }
 
+/*
+ * The heading is the only elastic track. With `1fr auto 1fr` the end-justified commands group
+ * kept its min-content width inside a narrower `1fr` track and bled back over the centered
+ * heading; giving navigation and commands their natural width lets the heading ellipsize instead.
+ */
 .zx-calendar__toolbar {
   display: grid;
-  grid-template-columns: 1fr auto 1fr;
+  grid-template-columns: auto minmax(0, 1fr) auto;
   align-items: center;
   gap: var(--zx-space-3);
   min-inline-size: 0;
@@ -35,7 +40,14 @@
 
 .zx-calendar__navigation { justify-self: start; gap: var(--zx-space-1); }
 .zx-calendar__commands { justify-self: end; gap: var(--zx-space-3); }
-.zx-calendar__views { overflow-x: auto; }
+.zx-calendar__views {
+  block-size: var(--zx-control-height);
+  gap: 2px;
+  overflow-x: auto;
+  border-radius: 0;
+  background: var(--zx-color-bg-muted);
+  padding: 3px;
+}
 
 .zx-calendar__toolbar-button,
 .zx-calendar__view-button,
@@ -59,15 +71,21 @@
 }
 
 .zx-calendar__toolbar-button:has(.zx-icon) { padding-inline: var(--zx-space-2); }
-.zx-calendar__view-button { border-inline-end-width: 0; padding-inline: var(--zx-space-3); }
-.zx-calendar__view-button:first-child { border-start-start-radius: var(--zx-control-radius); border-end-start-radius: var(--zx-control-radius); }
-.zx-calendar__view-button:last-child { border-inline-end-width: 1px; border-start-end-radius: var(--zx-control-radius); border-end-end-radius: var(--zx-control-radius); }
+.zx-calendar__view-button {
+  block-size: 100%;
+  min-block-size: 0;
+  border-color: transparent;
+  border-radius: 0;
+  background: transparent;
+  padding-inline: var(--zx-space-3);
+}
 .zx-calendar__view-button[aria-pressed="true"] {
   position: relative;
   z-index: 1;
-  border-color: var(--zx-color-accent);
-  background: var(--zx-color-bg-selected);
-  color: var(--zx-color-accent);
+  border-color: var(--zx-color-border-control);
+  background: var(--zx-color-bg-control);
+  box-shadow: var(--zx-shadow-2);
+  color: var(--zx-color-text);
 }
 
 .zx-calendar__new {
@@ -81,7 +99,7 @@
 }
 
 .zx-calendar__toolbar-button:hover:not(:disabled),
-.zx-calendar__view-button:hover:not(:disabled) { background: var(--zx-color-bg-hover); }
+.zx-calendar__view-button:hover:not(:disabled):not([aria-pressed="true"]) { background: var(--zx-color-bg-hover); }
 .zx-calendar__new:hover:not(:disabled) { background: var(--zx-color-accent-hover); }
 .zx-calendar button:disabled { cursor: default; opacity: .55; }
 
@@ -148,6 +166,7 @@
   min-block-size: calc(var(--zx-control-height) + var(--zx-space-2));
   place-content: center;
   border: 0;
+  border-radius: 0;
   border-inline-end: 1px solid var(--zx-color-border);
   background: var(--zx-color-bg-surface);
   color: var(--zx-color-text);
@@ -227,6 +246,7 @@
 .zx-calendar__slot {
   min-inline-size: 0;
   border: 0;
+  border-radius: 0;
   border-block-start: 1px solid var(--zx-color-border);
   border-inline-end: 1px solid var(--zx-color-border);
   background: var(--zx-color-bg-surface);

package/src/components/calendar/calendar.js

@@ -3,8 +3,8 @@ import { h } from '../../core/dom.js';
 import { icon } from '../../core/icons.js';
 import {
   CALENDAR_VIEWS, addCalendarDays, calendarDayDifference, calendarDayKey,
-  calendarEventIntersects, calendarEventSpansDays, calendarRange, cloneCalendarEvent,
-  layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents,
+  calendarEventIntersects, calendarEventSpansDays, calendarPageDate, calendarRange,
+  cloneCalendarEvent, layoutCalendarSpans, layoutTimedCalendarEvents, normalizeCalendarEvents,
   shiftCalendarEvent, startOfCalendarDay
 } from './calendar-model.js';
 
@@ -289,7 +289,9 @@ export class Calendar extends Component {
         ? changes.durationEditable : current.durationEditable,
       data: changes.data ?? current.data
     };
-    const [next] = normalizeCalendarEvents([source]);
+    // `source` is assembled from canonical keys, so the configured readers must not be reapplied
+    // here — but `dateUnit` must, or a numeric change is read in the wrong unit.
+    const [next] = normalizeCalendarEvents([source], { dateUnit: this.options.dateUnit });
     next.data = source.data;
     this._events = this._events.map((event, eventIndex) => eventIndex === index ? next : event);
     this._mutationVersions.delete(String(id));
@@ -1335,13 +1337,9 @@ export class Calendar extends Component {
 
   /** @param {number} direction @returns {this} */
   _page(direction) {
-    const date = new Date(this._date.getTime());
-    if (this._view === 'day') date.setDate(date.getDate() + direction);
-    else if (this._view === 'agenda') date.setDate(date.getDate() + direction * this.options.agendaDays);
-    else if (this._view === 'week') date.setDate(date.getDate() + direction * 7);
-    else if (this._view === 'month') date.setMonth(date.getMonth() + direction);
-    else date.setFullYear(date.getFullYear() + direction);
-    return this.setDate(date);
+    return this.setDate(calendarPageDate(this._view, this._date, direction, {
+      agendaDays: this.options.agendaDays
+    }));
   }
 
   /** @param {{start: Date, end: Date}} range @returns {string} */