@tensor_1/react 2.31.0 → 2.32.0

package/dist/rich-text.cjs

@@ -79,7 +79,7 @@ function fitsOn(side, a, f, vp, offset, padding) {
   return spaceOn(side, a, vp, offset) >= need + padding;
 }
 function computePosition(anchor, floating, viewport, options = {}) {
-  const { placement = "bottom-start", offset = 6, padding = 8, flip = true, shift = true, stickySide } = options;
+  const { placement = "bottom-start", offset = 6, padding = 8, flip = true, shift = true, shiftMainAxis = true, stickySide } = options;
   const { side: preferred, align } = parsePlacement(placement);
   let side = preferred;
   const sticky = stickySide === preferred || stickySide === OPPOSITE[preferred] ? stickySide : void 0;
@@ -112,12 +112,27 @@ function computePosition(anchor, floating, viewport, options = {}) {
     y = align === "start" ? start : align === "end" ? end : center;
     if (shift) y = clamp(y, padding, Math.max(padding, viewport.height - floating.height - padding));
   }
+  const mainAxisNatural = horizontal ? y : x;
+  const anchorInView = horizontal ? anchor.y + anchor.height > 0 && anchor.y < viewport.height : anchor.x + anchor.width > 0 && anchor.x < viewport.width;
+  let mainAxisRange = null;
+  if (shiftMainAxis && anchorInView) {
+    const extent = horizontal ? viewport.height - floating.height : viewport.width - floating.width;
+    mainAxisRange = [padding, Math.max(padding, extent - padding)];
+    if (horizontal) y = clamp(y, mainAxisRange[0], mainAxisRange[1]);
+    else x = clamp(x, mainAxisRange[0], mainAxisRange[1]);
+  }
   return {
     x,
     y,
     placement: align === "center" ? side : `${side}-${align}`,
     side,
-    align
+    align,
+    mainAxisNatural,
+    mainAxisRange,
+    available: {
+      width: Math.max(0, viewport.width - 2 * padding),
+      height: Math.max(0, viewport.height - 2 * padding)
+    }
   };
 }
 
@@ -780,6 +795,7 @@ function supportsAnchoring() {
   }
   return anchoringSupported;
 }
+var ANCHOR_BAND = 64;
 var anchorCount = 0;
 var namesOf = (value) => value.split(",").map((n) => n.trim()).filter((n) => n.startsWith("--"));
 function addAnchorName(el, name) {
@@ -804,9 +820,12 @@ function translationOf(el) {
 }
 var signed = (n) => `${n < 0 ? "-" : "+"} ${Math.round(Math.abs(n) * 100) / 100}px`;
 var prepared = /* @__PURE__ */ new WeakSet();
-function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-start", offset = 6, padding = 8 }) {
-  const opts = (0, import_react3.useRef)({ placement, offset, padding });
-  opts.current = { placement, offset, padding };
+function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-start", offset = 6, padding = 8, shiftMainAxis = true, capHeight = false, onAnchorHidden }) {
+  const opts = (0, import_react3.useRef)({ placement, offset, padding, shiftMainAxis, capHeight });
+  opts.current = { placement, offset, padding, shiftMainAxis, capHeight };
+  const onAnchorHiddenRef = (0, import_react3.useRef)(onAnchorHidden);
+  onAnchorHiddenRef.current = onAnchorHidden;
+  const heightCap = (0, import_react3.useRef)(null);
   const session = (0, import_react3.useRef)(false);
   const side = (0, import_react3.useRef)(null);
   const written = (0, import_react3.useRef)("");
@@ -830,6 +849,15 @@ function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-st
     }
     removeAnchorName(current.anchor, current.name);
   }, [floatingRef]);
+  const uncap = (0, import_react3.useCallback)(() => {
+    const cap = heightCap.current;
+    if (!cap) return;
+    heightCap.current = null;
+    const floating = floatingRef.current;
+    if (!floating) return;
+    floating.style.maxHeight = cap.inlineMaxHeight;
+    if (cap.setOverflow) floating.style.overflowY = cap.inlineOverflowY;
+  }, [floatingRef]);
   const reposition = (0, import_react3.useCallback)(() => {
     const anchorEl = resolveAnchor(anchor);
     const floating = floatingRef.current;
@@ -842,14 +870,36 @@ function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-st
       prepared.add(floating);
       written.current = "";
     }
+    const { placement: p, offset: o, padding: pad, shiftMainAxis: keepInView, capHeight: cap } = opts.current;
+    if (cap) {
+      if (!heightCap.current) {
+        const own = getComputedStyle(floating);
+        const setOverflow = !own.overflowY || own.overflowY === "visible";
+        heightCap.current = {
+          inlineMaxHeight: s.maxHeight,
+          inlineOverflowY: s.overflowY,
+          ownMaxHeight: own.maxHeight && own.maxHeight !== "none" ? own.maxHeight : "",
+          setOverflow,
+          written: ""
+        };
+        if (setOverflow) s.overflowY = "auto";
+      }
+      const room = `${Math.max(0, window.innerHeight - 2 * pad)}px`;
+      const max = heightCap.current.ownMaxHeight ? `min(${room}, ${heightCap.current.ownMaxHeight})` : room;
+      if (max !== heightCap.current.written) {
+        s.maxHeight = max;
+        heightCap.current.written = max;
+      }
+    } else if (heightCap.current) {
+      uncap();
+    }
     const a = anchorEl.getBoundingClientRect();
     const size = { width: floating.offsetWidth, height: floating.offsetHeight };
-    const { placement: p, offset: o, padding: pad } = opts.current;
     const pos = computePosition(
       { x: a.x, y: a.y, width: a.width, height: a.height },
       size,
       { width: window.innerWidth, height: window.innerHeight },
-      { placement: p, offset: o, padding: pad, stickySide: side.current ?? void 0 }
+      { placement: p, offset: o, padding: pad, shiftMainAxis: keepInView, stickySide: side.current ?? void 0 }
     );
     const measured = size.width > 0 || size.height > 0;
     if (measured && session.current) side.current = pos.side;
@@ -863,7 +913,10 @@ function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-st
       s.top = top2;
       written.current = key2;
     };
-    if (anchoringFailed.current || !supportsAnchoring()) {
+    const limit = pos.mainAxisRange;
+    const nearLimit = limit !== null && (pos.mainAxisNatural < limit[0] + ANCHOR_BAND || pos.mainAxisNatural > limit[1] - ANCHOR_BAND);
+    if (anchoringFailed.current || nearLimit || !supportsAnchoring()) {
+      if (anchoring.current) release(false);
       writeFixed(pos);
       return;
     }
@@ -900,7 +953,7 @@ function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-st
         writeFixed(pos);
       }
     }
-  }, [anchor, floatingRef, release]);
+  }, [anchor, floatingRef, release, uncap]);
   useIsomorphicLayoutEffect(() => {
     if (!open) return;
     session.current = true;
@@ -929,8 +982,20 @@ function useAnchoredPosition(anchor, floatingRef, { open, placement = "bottom-st
       side.current = null;
       anchoringFailed.current = false;
       release(true);
+      uncap();
     };
-  }, [open, reposition, anchor, floatingRef, release]);
+  }, [open, reposition, anchor, floatingRef, release, uncap]);
+  const watchAnchor = open && !!onAnchorHidden;
+  (0, import_react3.useEffect)(() => {
+    const anchorEl = resolveAnchor(anchor);
+    if (!watchAnchor || !anchorEl || typeof IntersectionObserver !== "function") return;
+    const observer = new IntersectionObserver((entries) => {
+      const latest = entries[entries.length - 1];
+      if (latest && !latest.isIntersecting) onAnchorHiddenRef.current?.();
+    });
+    observer.observe(anchorEl);
+    return () => observer.disconnect();
+  }, [watchAnchor, anchor]);
   (0, import_react3.useEffect)(() => () => release(false), [release]);
   return reposition;
 }
@@ -952,16 +1017,22 @@ var settle = (el) => {
   el.removeAttribute(PLACING);
 };
 function Popover({
-  popover = "auto",
+  popover: popoverProp,
   anchor,
   placement = "bottom-start",
   offset = 6,
   closeWhenAnchorHidden = false,
   onAnchorHidden,
+  capHeight = false,
+  openOnHover = false,
   className,
   children,
   ...props
 }) {
+  const hover = !!openOnHover && !!anchor;
+  const popover = popoverProp ?? (hover ? "manual" : "auto");
+  const openDelay = typeof openOnHover === "object" ? openOnHover.openDelay ?? 300 : 300;
+  const closeDelay = typeof openOnHover === "object" ? openOnHover.closeDelay ?? 150 : 150;
   const ref = (0, import_react4.useRef)(null);
   const [open, setOpen] = (0, import_react4.useState)(false);
   const openRef = (0, import_react4.useRef)(false);
@@ -971,7 +1042,16 @@ function Popover({
   const reposition = useAnchoredPosition(anchor ?? null, ref, {
     open: open && !!anchor,
     placement,
-    offset
+    offset,
+    capHeight,
+    onAnchorHidden: closeWhenAnchorHidden ? () => {
+      const el = ref.current;
+      if (!el || !isPopoverOpen(el)) return;
+      onAnchorHiddenRef.current?.();
+      const active = el.ownerDocument.activeElement;
+      if (active && el.contains(active)) active.blur();
+      el.hidePopover();
+    } : void 0
   });
   (0, import_react4.useEffect)(() => {
     const el = ref.current;
@@ -1006,25 +1086,87 @@ function Popover({
       el.removeAttribute(PLACING);
     };
   }, [anchor, reposition]);
+  (0, import_react4.useEffect)(() => {
+    const el = ref.current;
+    const anchorEl = resolveAnchor(anchor);
+    if (!hover || !el || !anchorEl) return;
+    let timer;
+    const inside = (node) => !!node && (anchorEl.contains(node) || el.contains(node));
+    const stillWanted = () => {
+      try {
+        return anchorEl.matches(":hover") || el.matches(":hover") || inside(el.ownerDocument.activeElement);
+      } catch {
+        return false;
+      }
+    };
+    const show = (delay) => {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        if (!isPopoverOpen(el)) {
+          try {
+            el.showPopover?.();
+          } catch {
+          }
+        }
+      }, delay);
+    };
+    const hide = (delay) => {
+      window.clearTimeout(timer);
+      timer = window.setTimeout(() => {
+        if (isPopoverOpen(el) && !stillWanted()) {
+          try {
+            el.hidePopover?.();
+          } catch {
+          }
+        }
+      }, delay);
+    };
+    const onEnter = (event) => {
+      if (event.pointerType !== "touch") show(openDelay);
+    };
+    const onLeave = (event) => {
+      if (event.pointerType !== "touch") hide(closeDelay);
+    };
+    const onFocusIn = () => show(0);
+    const onFocusOut = (event) => {
+      if (!inside(event.relatedTarget)) hide(closeDelay);
+    };
+    const onKeyDown = (event) => {
+      if (event.key !== "Escape" || !isPopoverOpen(el)) return;
+      window.clearTimeout(timer);
+      const hadFocus = el.contains(el.ownerDocument.activeElement);
+      try {
+        el.hidePopover?.();
+      } catch {
+      }
+      if (hadFocus) {
+        anchorEl.removeEventListener("focusin", onFocusIn);
+        anchorEl.focus();
+        anchorEl.addEventListener("focusin", onFocusIn);
+      }
+    };
+    for (const node of [anchorEl, el]) {
+      node.addEventListener("pointerenter", onEnter);
+      node.addEventListener("pointerleave", onLeave);
+      node.addEventListener("focusout", onFocusOut);
+      node.addEventListener("keydown", onKeyDown);
+    }
+    anchorEl.addEventListener("focusin", onFocusIn);
+    return () => {
+      window.clearTimeout(timer);
+      for (const node of [anchorEl, el]) {
+        node.removeEventListener("pointerenter", onEnter);
+        node.removeEventListener("pointerleave", onLeave);
+        node.removeEventListener("focusout", onFocusOut);
+        node.removeEventListener("keydown", onKeyDown);
+      }
+      anchorEl.removeEventListener("focusin", onFocusIn);
+    };
+  }, [hover, anchor, openDelay, closeDelay]);
   useIsomorphicLayoutEffect2(() => {
     openRef.current = open;
     if (open && ref.current) settle(ref.current);
   }, [open]);
-  (0, import_react4.useEffect)(() => {
-    const el = ref.current;
-    const anchorEl = resolveAnchor(anchor);
-    if (!closeWhenAnchorHidden || !open || !el || !anchorEl || typeof IntersectionObserver !== "function") return;
-    const observer = new IntersectionObserver((entries) => {
-      const latest = entries[entries.length - 1];
-      if (!latest || latest.isIntersecting || !isPopoverOpen(el)) return;
-      onAnchorHiddenRef.current?.();
-      const active = el.ownerDocument.activeElement;
-      if (active && el.contains(active)) active.blur();
-      el.hidePopover();
-    });
-    observer.observe(anchorEl);
-    return () => observer.disconnect();
-  }, [closeWhenAnchorHidden, open, anchor]);
   return /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("div", { ref, className: cx("uix-popover", className), ...popoverAttr, ...props, children });
 }
 

package/dist/rich-text.d.cts

@@ -1,8 +1,8 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { E as EmojiPickerLabels, a as EmojiLocale } from './emoji-image-6mPZ15Zy.cjs';
-export { l as emojiImageFileName } from './emoji-image-6mPZ15Zy.cjs';
-import './overlay-position-Cjv5E7mn.cjs';
+import { E as EmojiPickerLabels, a as EmojiLocale } from './emoji-image-DjCKpdwE.cjs';
+export { l as emojiImageFileName } from './emoji-image-DjCKpdwE.cjs';
+import './overlay-position-2Afke51l.cjs';
 
 type RichTextFeatures = 'full' | 'comment' | 'template';
 type RichTextHeadingLevel = 1 | 2 | 3;

package/dist/rule-builder-model.d.ts

@@ -20,9 +20,24 @@ interface RuleDefinition {
     when: RuleGroup;
     then: RuleAction[];
 }
+/** The built-in checks of `validateRuleDefinition`; each can be reworded or turned off (HAR-1618). */
+type RuleCheck = 'duplicateId' | 'maxDepth' | 'emptyGroup' | 'missingField' | 'missingOperator' | 'noActions' | 'missingActionType';
 interface RuleValidationIssue {
     path: string;
     message: string;
+    /** Which built-in check raised it. Absent on issues from the consumer's own `validate`. */
+    check?: RuleCheck;
+}
+/** The built-in messages. `{id}` is the duplicated id, `{max}` the depth limit. */
+declare const DEFAULT_RULE_VALIDATION_MESSAGES: Record<RuleCheck, string>;
+interface RuleValidationOptions {
+    /** Replace individual messages (a translation). */
+    messages?: Partial<Record<RuleCheck, string>>;
+    /**
+     * `false` turns a check off: `{ emptyGroup: false }` for a rule that may have no condition
+     * (a catch-all), `{ noActions: false, missingActionType: false }` for conditions without actions.
+     */
+    checks?: Partial<Record<RuleCheck, boolean>>;
 }
 declare function isRuleGroup(node: RuleCondition | RuleGroup): node is RuleGroup;
 declare function ruleDepth(group: RuleGroup): number;
@@ -31,11 +46,28 @@ declare function mapRuleGroup(group: RuleGroup, id: string, update: (node: RuleC
 declare function appendRuleNode(group: RuleGroup, parentId: string, node: RuleCondition | RuleGroup, maxDepth?: number): RuleGroup;
 declare function removeRuleNode(group: RuleGroup, id: string): RuleGroup;
 declare function moveRuleNode(group: RuleGroup, id: string, direction: -1 | 1): RuleGroup;
-declare function validateRuleDefinition(value: RuleDefinition, maxDepth?: number): RuleValidationIssue[];
+/** Set `combinator` on a group and on every group nested in it. */
+declare function setRuleCombinator(group: RuleGroup, combinator: 'and' | 'or'): RuleGroup;
+declare function validateRuleDefinition(value: RuleDefinition, maxDepth?: number, options?: RuleValidationOptions): RuleValidationIssue[];
+/** The words of the `summarizeRule` sentence. `{conditions}` and `{actions}` are filled in. */
+interface RuleSummaryWords {
+    sentence: string;
+    /** For a rule with no actions to name (a conditions-only rule). */
+    sentenceConditionsOnly: string;
+    noConditions: string;
+    noActions: string;
+    and: string;
+    or: string;
+}
+declare const DEFAULT_RULE_SUMMARY_WORDS: RuleSummaryWords;
 declare function summarizeRule(value: RuleDefinition, labels?: {
     fields?: Record<string, string>;
     operators?: Record<string, string>;
     actions?: Record<string, string>;
+    /** Translate the sentence itself. Default: English. */
+    words?: Partial<RuleSummaryWords>;
+    /** Leave the actions out of the sentence. */
+    conditionsOnly?: boolean;
 }): string;
 
-export { type RuleAction, type RuleCondition, type RuleDefinition, type RuleGroup, type RuleValidationIssue, appendRuleNode, findRuleNodeDepth, isRuleGroup, mapRuleGroup, moveRuleNode, removeRuleNode, ruleDepth, summarizeRule, validateRuleDefinition };
+export { DEFAULT_RULE_SUMMARY_WORDS, DEFAULT_RULE_VALIDATION_MESSAGES, type RuleAction, type RuleCheck, type RuleCondition, type RuleDefinition, type RuleGroup, type RuleSummaryWords, type RuleValidationIssue, type RuleValidationOptions, appendRuleNode, findRuleNodeDepth, isRuleGroup, mapRuleGroup, moveRuleNode, removeRuleNode, ruleDepth, setRuleCombinator, summarizeRule, validateRuleDefinition };

package/dist/rule-builder-model.js

@@ -1,3 +1,13 @@
+const fillLabel = (template, values) => template.replace(/\{(\w+)\}/g, (match, key) => Object.prototype.hasOwnProperty.call(values, key) ? String(values[key]) : match);
+const DEFAULT_RULE_VALIDATION_MESSAGES = {
+  duplicateId: "Duplicate id \u201C{id}\u201D.",
+  maxDepth: "Nesting exceeds {max} levels.",
+  emptyGroup: "Add at least one condition.",
+  missingField: "Choose a field.",
+  missingOperator: "Choose an operator.",
+  noActions: "Add at least one action.",
+  missingActionType: "Choose an action."
+};
 function isRuleGroup(node) {
   return "conditions" in node;
 }
@@ -52,43 +62,68 @@ function moveRuleNode(group, id, direction) {
     conditions: group.conditions.map((node) => isRuleGroup(node) ? moveRuleNode(node, id, direction) : node)
   };
 }
-function validateRuleDefinition(value, maxDepth = 3) {
+function setRuleCombinator(group, combinator) {
+  return {
+    ...group,
+    combinator,
+    conditions: group.conditions.map((node) => isRuleGroup(node) ? setRuleCombinator(node, combinator) : node)
+  };
+}
+function validateRuleDefinition(value, maxDepth = 3, options = {}) {
   const issues = [];
+  const messages = { ...DEFAULT_RULE_VALIDATION_MESSAGES, ...options.messages };
+  const report = (check, path, values = {}) => {
+    if (options.checks?.[check] === false) return;
+    issues.push({ path, message: fillLabel(messages[check], values), check });
+  };
   const ids = /* @__PURE__ */ new Set();
   const visit = (group, path, depth) => {
-    if (ids.has(group.id)) issues.push({ path, message: `Duplicate id \u201C${group.id}\u201D.` });
+    if (ids.has(group.id)) report("duplicateId", path, { id: group.id });
     ids.add(group.id);
-    if (depth > maxDepth) issues.push({ path, message: `Nesting exceeds ${maxDepth} levels.` });
-    if (group.conditions.length === 0) issues.push({ path, message: "Add at least one condition." });
+    if (depth > maxDepth) report("maxDepth", path, { max: maxDepth });
+    if (group.conditions.length === 0) report("emptyGroup", path);
     group.conditions.forEach((node, index) => {
       const nodePath = `${path}.conditions[${index}]`;
-      if (ids.has(node.id)) issues.push({ path: nodePath, message: `Duplicate id \u201C${node.id}\u201D.` });
+      if (ids.has(node.id)) report("duplicateId", nodePath, { id: node.id });
       if (isRuleGroup(node)) visit(node, nodePath, depth + 1);
       else {
         ids.add(node.id);
-        if (!node.field) issues.push({ path: nodePath, message: "Choose a field." });
-        if (!node.operator) issues.push({ path: nodePath, message: "Choose an operator." });
+        if (!node.field) report("missingField", nodePath);
+        if (!node.operator) report("missingOperator", nodePath);
       }
     });
   };
   visit(value.when, "when", 1);
-  if (value.then.length === 0) issues.push({ path: "then", message: "Add at least one action." });
+  if (value.then.length === 0) report("noActions", "then");
   value.then.forEach((action, index) => {
-    if (ids.has(action.id)) issues.push({ path: `then[${index}]`, message: `Duplicate id \u201C${action.id}\u201D.` });
+    if (ids.has(action.id)) report("duplicateId", `then[${index}]`, { id: action.id });
     ids.add(action.id);
-    if (!action.type) issues.push({ path: `then[${index}]`, message: "Choose an action." });
+    if (!action.type) report("missingActionType", `then[${index}]`);
   });
   return issues;
 }
+const DEFAULT_RULE_SUMMARY_WORDS = {
+  sentence: "When {conditions}, then {actions}.",
+  sentenceConditionsOnly: "When {conditions}.",
+  noConditions: "no conditions",
+  noActions: "no actions",
+  and: "AND",
+  or: "OR"
+};
 function summarizeRule(value, labels = {}) {
+  const words = { ...DEFAULT_RULE_SUMMARY_WORDS, ...labels.words };
   const formatValue = (input) => input === void 0 ? "" : ` ${JSON.stringify(input)}`;
   const formatGroup = (group) => group.conditions.map(
     (node) => isRuleGroup(node) ? `(${formatGroup(node)})` : `${labels.fields?.[node.field] ?? node.field} ${labels.operators?.[node.operator] ?? node.operator}${formatValue(node.value)}`
-  ).join(` ${group.combinator.toUpperCase()} `);
+  ).join(` ${group.combinator === "or" ? words.or : words.and} `);
+  const conditions = formatGroup(value.when) || words.noConditions;
+  if (labels.conditionsOnly) return fillLabel(words.sentenceConditionsOnly, { conditions });
   const actions = value.then.map((action) => labels.actions?.[action.type] ?? action.type).join(", ");
-  return `When ${formatGroup(value.when) || "no conditions"}, then ${actions || "no actions"}.`;
+  return fillLabel(words.sentence, { conditions, actions: actions || words.noActions });
 }
 export {
+  DEFAULT_RULE_SUMMARY_WORDS,
+  DEFAULT_RULE_VALIDATION_MESSAGES,
   appendRuleNode,
   findRuleNodeDepth,
   isRuleGroup,
@@ -96,6 +131,7 @@ export {
   moveRuleNode,
   removeRuleNode,
   ruleDepth,
+  setRuleCombinator,
   summarizeRule,
   validateRuleDefinition
 };

package/dist/scheduling-calendar-model.d.ts

@@ -0,0 +1,66 @@
+import { CalendarWeekday, ZonedDaySpan } from './calendar-model.js';
+
+/** Which lane group a span is drawn in: windows sit above multi-day items, and neither takes a chip slot. */
+type MonthSpanGroup = 'window' | 'item';
+interface MonthSpanInput {
+    id: string;
+    /** Half-open `[start, end)` instants (ISO 8601, epoch ms or Date). */
+    start: string | number | Date;
+    end: string | number | Date;
+    /** Defaults to `'item'`. */
+    group?: MonthSpanGroup;
+}
+interface PlacedMonthSpan {
+    id: string;
+    group: MonthSpanGroup;
+    /** 0-based week row of the grid `days` the layout was computed for. */
+    weekRow: number;
+    /** 0-based lane inside its group. */
+    lane: number;
+    /** First and last column (0–6, inclusive) the span covers in this row. */
+    startCol: number;
+    endCol: number;
+    /** The span started in an earlier row (or before the grid). */
+    continuesBefore: boolean;
+    /** The span goes on in a later row (or past the grid). */
+    continuesAfter: boolean;
+}
+interface MonthSpanLayout {
+    /** One entry per span per week row it got a lane in. Render exactly these; never re-pack. */
+    placed: PlacedMonthSpan[];
+    /** Per week row, the ids that got no lane, in input order (windows first). An id may name a window and an item. */
+    hiddenByRow: Record<number, string[]>;
+    /** Per week row with a hidden span, the first day (`YYYY-MM-DD`) a hidden span covers. */
+    firstHiddenDayByRow: Record<number, string>;
+}
+interface LayoutMonthSpansOptions {
+    /** The display zone that decides which days a span covers. */
+    timeZone: string;
+    /** When set, `days[0]` must fall on this weekday (a guard against a grid built for another week start). */
+    weekStartsOn?: CalendarWeekday;
+    /** Lanes per group (default 2). A number applies to both groups. */
+    laneCap?: number | Partial<Record<MonthSpanGroup, number>>;
+}
+/**
+ * The calendar days an item covers in `timeZone`, end-exclusive (`end` is the first day not
+ * covered): a 22:00–00:00 item covers only its start day, a 23:00 → 02:00 item two days. A
+ * zero-length item covers the day of its start. Throws a `RangeError` when `end` is before
+ * `start`; it never swaps them.
+ */
+declare function itemDaySpan(start: string | number | Date, end: string | number | Date, timeZone: string): ZonedDaySpan;
+/**
+ * The date keys a `SchedulingCalendar` grid shows, in order: six week rows for `'month'`
+ * (from the week holding the 1st), one for `'week'` (the week holding `anchorDate`). Pass the
+ * result to `layoutMonthSpans` so the layout and the rendered grid agree.
+ */
+declare function schedulingGridDays(anchorDate: string, view: 'month' | 'week', weekStartsOn?: CalendarWeekday): string[];
+/**
+ * Places multi-day spans as one continuous bar per week row. Spans are taken **in the order
+ * given** (the consumer's salience order): in each row and group, the first spans to ask get
+ * the lanes, the rest are listed in `hiddenByRow`. Windows and items pack in separate groups,
+ * each capped by `laneCap`. Day membership is the end-exclusive zoned span in `timeZone`
+ * (never a UTC date). `days` are the grid's date keys, a whole number of weeks.
+ */
+declare function layoutMonthSpans(spans: readonly MonthSpanInput[], days: readonly string[], options: LayoutMonthSpansOptions): MonthSpanLayout;
+
+export { type LayoutMonthSpansOptions, type MonthSpanGroup, type MonthSpanInput, type MonthSpanLayout, type PlacedMonthSpan, itemDaySpan, layoutMonthSpans, schedulingGridDays };

package/dist/scheduling-calendar-model.js

@@ -0,0 +1,82 @@
+import { addCalendarDays, buildMonthGrid, packLanes, startOfMonth, zonedDateKey, zonedDaySpan } from "./calendar-model.js";
+const DEFAULT_LANE_CAP = 2;
+function itemDaySpan(start, end, timeZone) {
+  const from = new Date(start);
+  const to = new Date(end);
+  if (from.getTime() === to.getTime()) {
+    const day = zonedDateKey(from, timeZone);
+    return { start: day, end: addCalendarDays(day, 1) };
+  }
+  return zonedDaySpan(from, to, timeZone);
+}
+function schedulingGridDays(anchorDate, view, weekStartsOn = 1) {
+  if (view === "month") return buildMonthGrid(startOfMonth(anchorDate), weekStartsOn).map((day) => day.date);
+  const weekday = (/* @__PURE__ */ new Date(`${anchorDate}T00:00:00Z`)).getUTCDay();
+  const first = addCalendarDays(anchorDate, -((weekday - weekStartsOn + 7) % 7));
+  return Array.from({ length: 7 }, (_, index) => addCalendarDays(first, index));
+}
+function layoutMonthSpans(spans, days, options) {
+  if (days.length === 0 || days.length % 7 !== 0) throw new RangeError(`layoutMonthSpans: days must be whole weeks, got ${days.length} day(s)`);
+  for (let index = 1; index < days.length; index++) {
+    if (days[index] !== addCalendarDays(days[index - 1], 1)) throw new RangeError(`layoutMonthSpans: days must be consecutive (${days[index - 1]} \u2192 ${days[index]})`);
+  }
+  if (options.weekStartsOn !== void 0 && (/* @__PURE__ */ new Date(`${days[0]}T00:00:00Z`)).getUTCDay() !== options.weekStartsOn) {
+    throw new RangeError(`layoutMonthSpans: days[0] (${days[0]}) does not fall on weekday ${options.weekStartsOn}`);
+  }
+  const capFor = (group) => {
+    const cap = typeof options.laneCap === "number" ? options.laneCap : options.laneCap?.[group] ?? DEFAULT_LANE_CAP;
+    if (!(cap === Infinity || Number.isInteger(cap) && cap >= 0)) throw new RangeError(`layoutMonthSpans: laneCap for ${group} must be a non-negative integer, got ${cap}`);
+    return cap;
+  };
+  const caps = { window: capFor("window"), item: capFor("item") };
+  const rows = days.length / 7;
+  const gridEnd = addCalendarDays(days[days.length - 1], 1);
+  const seen = /* @__PURE__ */ new Set();
+  const covered = spans.map((span) => {
+    const group = span.group ?? "item";
+    if (seen.has(`${group} ${span.id}`)) throw new TypeError(`layoutMonthSpans: duplicate ${group} id ${span.id}`);
+    seen.add(`${group} ${span.id}`);
+    return { id: span.id, group, days: itemDaySpan(span.start, span.end, options.timeZone) };
+  });
+  const placed = [];
+  const hiddenByRow = {};
+  const firstHiddenDayByRow = {};
+  for (let row = 0; row < rows; row++) {
+    const rowStart = days[row * 7];
+    const rowEnd = row + 1 < rows ? days[(row + 1) * 7] : gridEnd;
+    for (const group of ["window", "item"]) {
+      const inRow = covered.filter((span) => span.group === group && span.days.start < rowEnd && span.days.end > rowStart).map((span) => {
+        const from = span.days.start > rowStart ? span.days.start : rowStart;
+        const to = span.days.end < rowEnd ? span.days.end : rowEnd;
+        const startCol = days.indexOf(from, row * 7) - row * 7;
+        const endCol = days.indexOf(addCalendarDays(to, -1), row * 7) - row * 7;
+        return { span, from, startCol, endCol };
+      });
+      const packed = packLanes(inRow.map(({ span, startCol, endCol }) => ({ id: span.id, start: startCol, end: endCol + 1 })), caps[group], { order: "given" });
+      for (const { span, from, startCol, endCol } of inRow) {
+        const lane = packed.lanes[span.id].lane;
+        if (lane === null) {
+          (hiddenByRow[row] ?? (hiddenByRow[row] = [])).push(span.id);
+          if (firstHiddenDayByRow[row] === void 0 || from < firstHiddenDayByRow[row]) firstHiddenDayByRow[row] = from;
+          continue;
+        }
+        placed.push({
+          id: span.id,
+          group,
+          weekRow: row,
+          lane,
+          startCol,
+          endCol,
+          continuesBefore: span.days.start < rowStart,
+          continuesAfter: span.days.end > rowEnd
+        });
+      }
+    }
+  }
+  return { placed, hiddenByRow, firstHiddenDayByRow };
+}
+export {
+  itemDaySpan,
+  layoutMonthSpans,
+  schedulingGridDays
+};