calendar-ui-layout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiku0730
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# calendar-ui-layout
+
+**Headless time-grid layout engine.** Give it a day's worth of timed events; get
+back where each one goes — column packing, overlap resolution, and expansion —
+as plain numbers. No UI, no framework, no DOM, zero runtime dependencies.
+
+This is the hard part every "headless" calendar makes you write yourself. The
+competition ([`@verbpatch/*`](https://www.verbpatch.com/calendar),
+react-headless-agenda) hands you time slots and then, in their own docs, tells
+you to *"calculate the width and horizontal position of events that occur at the
+same time"* on your own. This package **is** that calculation.
+
+## Install
+
+```sh
+npm install calendar-ui-layout
+```
+
+## Usage
+
+```ts
+import { layoutDay } from "calendar-ui-layout";
+
+const positioned = layoutDay(
+  [
+    { id: "a", start: 9 * 60, end: 10 * 60 + 30 }, // minutes from midnight
+    { id: "b", start: 9 * 60, end: 9 * 60 + 30 },
+    { id: "c", start: 9 * 60 + 30, end: 10 * 60 },
+  ],
+  { dayStart: 8 * 60, dayEnd: 18 * 60 },
+);
+
+for (const p of positioned) {
+  // p.data                      → your original event, untouched
+  // p.top / p.height            → vertical geometry, fractions 0..1 of the window
+  // p.left / p.width            → horizontal geometry, fractions 0..1
+  // p.columnIndex / columnCount → integer column math, if you'd rather do px yourself
+  // p.span                      → how many columns wide after expansion
+}
+```
+
+Render however you like — the numbers are the whole point:
+
+```tsx
+<div style={{ position: "relative" }}>
+  {positioned.map((p) => (
+    <div
+      key={p.data.id}
+      style={{
+        position: "absolute",
+        top: `${p.top * 100}%`,
+        height: `${p.height * 100}%`,
+        left: `${p.left * 100}%`,
+        width: `${p.width * 100}%`,
+      }}
+    >
+      {String(p.data.id)}
+    </div>
+  ))}
+</div>
+```
+
+## Why numeric, not `Date`?
+
+`start`/`end` are numbers in one consistent unit (minutes from midnight is the
+natural choice). Turning a `Date` — with its timezone and DST rules — into a
+minute offset is a separate, thorny concern; keeping it out of the layout core
+makes this engine **pure and deterministic**: same input, same output, fully
+unit-testable, no clock involved. Timezone/DST/recurrence handling lives in
+higher layers (and leans on battle-tested libraries), not here.
+
+## API
+
+### `layoutDay(events, options?) → PositionedInterval[]`
+
+- `events`: `{ id, start, end, ...yourFields }[]` — `end` is exclusive.
+- `options`:
+  - `dayStart` (default `0`), `dayEnd` (default `1440`) — the visible window; events are clamped to it and fully-outside events are dropped.
+  - `minDuration` (default `0`) — floor height so zero-length events stay clickable.
+  - `expand` (default `true`) — widen events into free right-hand columns (the "wide when alone" look). Set `false` to keep every event one column wide.
+
+Guarantees (enforced by the test suite):
+
+- Events overlapping in time never overlap in space.
+- Touching events (`end === start`) do **not** count as overlapping.
+- `left + width ≤ 1` and `top + height ≤ 1` always.
+- Deterministic and order-independent: shuffling the input yields the same layout.
+
+## Develop
+
+```sh
+npm test          # 18 tests: clustering, packing, expansion, edge cases, invariants
+npm run typecheck # strict, noUncheckedIndexedAccess
+npm run demo      # ASCII render of a sample day — see the overlap resolution
+```
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+// src/layout.ts
+function overlaps(aStart, aEnd, bStart, bEnd) {
+  return aStart < bEnd && bStart < aEnd;
+}
+function layoutDay(events, options = {}) {
+  const dayStart = options.dayStart ?? 0;
+  const dayEnd = options.dayEnd ?? 1440;
+  const expand = options.expand ?? true;
+  const minDuration = options.minDuration ?? 0;
+  const range = dayEnd - dayStart;
+  if (range <= 0) return [];
+  const norm = [];
+  for (const e of events) {
+    let start = Math.max(e.start, dayStart);
+    let end = Math.min(e.end, dayEnd);
+    if (minDuration > 0 && end - start < minDuration) {
+      end = Math.min(start + minDuration, dayEnd);
+      start = Math.max(dayStart, end - minDuration);
+    }
+    if (end <= start) continue;
+    norm.push({ data: e, start, end });
+  }
+  if (norm.length === 0) return [];
+  norm.sort(
+    (a, b) => a.start - b.start || b.end - a.end || String(a.data.id).localeCompare(String(b.data.id))
+  );
+  const result = [];
+  let i = 0;
+  while (i < norm.length) {
+    let clusterEnd = norm[i].end;
+    let j = i + 1;
+    while (j < norm.length && norm[j].start < clusterEnd) {
+      clusterEnd = Math.max(clusterEnd, norm[j].end);
+      j++;
+    }
+    layoutCluster(norm.slice(i, j), { dayStart, range, expand }, result);
+    i = j;
+  }
+  return result;
+}
+function layoutCluster(cluster, ctx, out) {
+  const columns = [];
+  const columnOf = /* @__PURE__ */ new Map();
+  for (const ev of cluster) {
+    let placed = false;
+    for (let c = 0; c < columns.length; c++) {
+      const col = columns[c];
+      const last = col[col.length - 1];
+      if (last.end <= ev.start) {
+        col.push(ev);
+        columnOf.set(ev, c);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) {
+      columnOf.set(ev, columns.length);
+      columns.push([ev]);
+    }
+  }
+  const columnCount = columns.length;
+  for (const ev of cluster) {
+    const columnIndex = columnOf.get(ev);
+    const span = ctx.expand ? spanFor(ev, columnIndex, columnCount, columns) : 1;
+    out.push({
+      data: ev.data,
+      columnIndex,
+      columnCount,
+      span,
+      top: (ev.start - ctx.dayStart) / ctx.range,
+      height: (ev.end - ev.start) / ctx.range,
+      left: columnIndex / columnCount,
+      width: span / columnCount
+    });
+  }
+}
+function spanFor(ev, columnIndex, columnCount, columns) {
+  let span = 1;
+  for (let c = columnIndex + 1; c < columnCount; c++) {
+    const col = columns[c];
+    const blocked = col.some((o) => overlaps(ev.start, ev.end, o.start, o.end));
+    if (blocked) break;
+    span++;
+  }
+  return span;
+}
+
+exports.layoutDay = layoutDay;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/layout.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["import type { Interval, LayoutOptions, PositionedInterval } from \"./types.js\";\n\n/** Internal, normalized (clamped) representation of an interval. */\ninterface Normalized<T extends Interval> {\n  data: T;\n  start: number;\n  end: number;\n}\n\n/** Two half-open intervals overlap iff each starts before the other ends. */\nfunction overlaps(aStart: number, aEnd: number, bStart: number, bEnd: number): boolean {\n  return aStart < bEnd && bStart < aEnd;\n}\n\n/**\n * Lay out timed events for a single day/column axis, resolving overlaps into\n * side-by-side columns.\n *\n * Algorithm (the same shape Google Calendar uses):\n *  1. **Normalize** — clamp every event to the day window, drop anything that\n *     falls outside it, optionally enforce a minimum duration.\n *  2. **Sort** — by start ascending, then by end descending (longer events\n *     first), then by id for a stable, deterministic order.\n *  3. **Cluster** — sweep the sorted list into maximal runs of transitively\n *     overlapping events. Columns are counted per cluster, so a busy morning\n *     never shrinks a quiet afternoon.\n *  4. **Pack** — within a cluster, greedily drop each event into the first\n *     column whose previous event has already ended; open a new column only\n *     when none is free.\n *  5. **Expand** — optionally widen each event rightward across columns that are\n *     free for its entire duration.\n *\n * The engine is pure and deterministic: same input → same output, no clock, no\n * DOM, no framework.\n */\nexport function layoutDay<T extends Interval>(\n  events: readonly T[],\n  options: LayoutOptions = {},\n): PositionedInterval<T>[] {\n  const dayStart = options.dayStart ?? 0;\n  const dayEnd = options.dayEnd ?? 1440;\n  const expand = options.expand ?? true;\n  const minDuration = options.minDuration ?? 0;\n\n  const range = dayEnd - dayStart;\n  if (range <= 0) return [];\n\n  // 1. Normalize: clamp to window, apply minDuration, drop out-of-window.\n  const norm: Normalized<T>[] = [];\n  for (const e of events) {\n    let start = Math.max(e.start, dayStart);\n    let end = Math.min(e.end, dayEnd);\n    if (minDuration > 0 && end - start < minDuration) {\n      end = Math.min(start + minDuration, dayEnd);\n      // If clamping to the window pushed us against the wall, pull start back\n      // so a min-duration event near dayEnd still renders its full min height.\n      start = Math.max(dayStart, end - minDuration);\n    }\n    if (end <= start) continue;\n    norm.push({ data: e, start, end });\n  }\n  if (norm.length === 0) return [];\n\n  // 2. Sort: start asc, end desc, id asc.\n  norm.sort(\n    (a, b) =>\n      a.start - b.start ||\n      b.end - a.end ||\n      String(a.data.id).localeCompare(String(b.data.id)),\n  );\n\n  const result: PositionedInterval<T>[] = [];\n\n  // 3. Cluster + 4. Pack + 5. Expand, one maximal overlap-run at a time.\n  let i = 0;\n  while (i < norm.length) {\n    let clusterEnd = norm[i]!.end;\n    let j = i + 1;\n    while (j < norm.length && norm[j]!.start < clusterEnd) {\n      clusterEnd = Math.max(clusterEnd, norm[j]!.end);\n      j++;\n    }\n    layoutCluster(norm.slice(i, j), { dayStart, range, expand }, result);\n    i = j;\n  }\n\n  return result;\n}\n\ninterface ClusterContext {\n  dayStart: number;\n  range: number;\n  expand: boolean;\n}\n\nfunction layoutCluster<T extends Interval>(\n  cluster: readonly Normalized<T>[],\n  ctx: ClusterContext,\n  out: PositionedInterval<T>[],\n): void {\n  // 4. Greedy column packing. `columns[c]` holds the events placed in column c,\n  // in time order; the last one determines whether the column is free.\n  const columns: Normalized<T>[][] = [];\n  const columnOf = new Map<Normalized<T>, number>();\n\n  for (const ev of cluster) {\n    let placed = false;\n    for (let c = 0; c < columns.length; c++) {\n      const col = columns[c]!;\n      const last = col[col.length - 1]!;\n      if (last.end <= ev.start) {\n        col.push(ev);\n        columnOf.set(ev, c);\n        placed = true;\n        break;\n      }\n    }\n    if (!placed) {\n      columnOf.set(ev, columns.length);\n      columns.push([ev]);\n    }\n  }\n\n  const columnCount = columns.length;\n\n  // 5. Expansion + geometry.\n  for (const ev of cluster) {\n    const columnIndex = columnOf.get(ev)!;\n    const span = ctx.expand\n      ? spanFor(ev, columnIndex, columnCount, columns)\n      : 1;\n\n    out.push({\n      data: ev.data,\n      columnIndex,\n      columnCount,\n      span,\n      top: (ev.start - ctx.dayStart) / ctx.range,\n      height: (ev.end - ev.start) / ctx.range,\n      left: columnIndex / columnCount,\n      width: span / columnCount,\n    });\n  }\n}\n\n/**\n * How many columns `ev` can occupy: start at its own column and extend right\n * while every event in the next column clears its time span.\n */\nfunction spanFor<T extends Interval>(\n  ev: Normalized<T>,\n  columnIndex: number,\n  columnCount: number,\n  columns: readonly Normalized<T>[][],\n): number {\n  let span = 1;\n  for (let c = columnIndex + 1; c < columnCount; c++) {\n    const col = columns[c]!;\n    const blocked = col.some((o) => overlaps(ev.start, ev.end, o.start, o.end));\n    if (blocked) break;\n    span++;\n  }\n  return span;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+/**
+ * A time interval to be laid out. `start`/`end` are numbers in a single
+ * consistent unit — typically **minutes from midnight** — where `end` is
+ * exclusive. Keeping the core purely numeric makes it deterministic and
+ * timezone/DST-agnostic: converting a `Date` (with its zone/DST rules) into a
+ * minute offset is the caller's concern, not the layout engine's.
+ *
+ * Extra fields are preserved untouched on the way through, so callers can carry
+ * their own event payload (title, color, resourceId, …).
+ */
+interface Interval {
+    id: string | number;
+    /** Inclusive start, in minutes (or any consistent unit). */
+    start: number;
+    /** Exclusive end, in the same unit as `start`. */
+    end: number;
+    [key: string]: unknown;
+}
+interface LayoutOptions {
+    /** Start of the visible day window, same unit as intervals. Default 0. */
+    dayStart?: number;
+    /** End of the visible day window (exclusive), same unit. Default 1440 (24h). */
+    dayEnd?: number;
+    /**
+     * Minimum duration used for layout so zero/near-zero-length events still get
+     * a clickable height. Applied after clamping to the window. Default 0 (off).
+     */
+    minDuration?: number;
+    /**
+     * When true (default), an event widens to fill columns to its right that are
+     * free for its whole duration — the "wide when alone" look of Google Calendar.
+     * When false, every event keeps a single-column width (`span` is always 1).
+     */
+    expand?: boolean;
+}
+/**
+ * The result of laying out one interval.
+ *
+ * Two coordinate systems are provided so any renderer can consume it:
+ *  - **Structural** (`columnIndex`, `columnCount`, `span`): integer column math,
+ *    for callers that want to compute their own pixel geometry.
+ *  - **Fractional** (`top`, `height`, `left`, `width`): all in the range 0..1
+ *    relative to the day window, ready to drop into `style` as percentages.
+ *
+ * `left + width` never exceeds 1, and `top + height` never exceeds 1.
+ */
+interface PositionedInterval<T extends Interval = Interval> {
+    /** The original interval, unmodified. */
+    data: T;
+    /** Zero-based column this event occupies within its overlap cluster. */
+    columnIndex: number;
+    /** Total number of columns in this event's overlap cluster (>= 1). */
+    columnCount: number;
+    /** How many columns wide the event is after expansion (>= 1). */
+    span: number;
+    /** Fraction (0..1) from the top of the day window to the event's start. */
+    top: number;
+    /** Fraction (0..1) of the day window covered by the event's duration. */
+    height: number;
+    /** Fraction (0..1) from the left edge to the event's column. */
+    left: number;
+    /** Fraction (0..1) of the width the event occupies. */
+    width: number;
+}
+
+/**
+ * Lay out timed events for a single day/column axis, resolving overlaps into
+ * side-by-side columns.
+ *
+ * Algorithm (the same shape Google Calendar uses):
+ *  1. **Normalize** — clamp every event to the day window, drop anything that
+ *     falls outside it, optionally enforce a minimum duration.
+ *  2. **Sort** — by start ascending, then by end descending (longer events
+ *     first), then by id for a stable, deterministic order.
+ *  3. **Cluster** — sweep the sorted list into maximal runs of transitively
+ *     overlapping events. Columns are counted per cluster, so a busy morning
+ *     never shrinks a quiet afternoon.
+ *  4. **Pack** — within a cluster, greedily drop each event into the first
+ *     column whose previous event has already ended; open a new column only
+ *     when none is free.
+ *  5. **Expand** — optionally widen each event rightward across columns that are
+ *     free for its entire duration.
+ *
+ * The engine is pure and deterministic: same input → same output, no clock, no
+ * DOM, no framework.
+ */
+declare function layoutDay<T extends Interval>(events: readonly T[], options?: LayoutOptions): PositionedInterval<T>[];
+
+export { type Interval, type LayoutOptions, type PositionedInterval, layoutDay };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+/**
+ * A time interval to be laid out. `start`/`end` are numbers in a single
+ * consistent unit — typically **minutes from midnight** — where `end` is
+ * exclusive. Keeping the core purely numeric makes it deterministic and
+ * timezone/DST-agnostic: converting a `Date` (with its zone/DST rules) into a
+ * minute offset is the caller's concern, not the layout engine's.
+ *
+ * Extra fields are preserved untouched on the way through, so callers can carry
+ * their own event payload (title, color, resourceId, …).
+ */
+interface Interval {
+    id: string | number;
+    /** Inclusive start, in minutes (or any consistent unit). */
+    start: number;
+    /** Exclusive end, in the same unit as `start`. */
+    end: number;
+    [key: string]: unknown;
+}
+interface LayoutOptions {
+    /** Start of the visible day window, same unit as intervals. Default 0. */
+    dayStart?: number;
+    /** End of the visible day window (exclusive), same unit. Default 1440 (24h). */
+    dayEnd?: number;
+    /**
+     * Minimum duration used for layout so zero/near-zero-length events still get
+     * a clickable height. Applied after clamping to the window. Default 0 (off).
+     */
+    minDuration?: number;
+    /**
+     * When true (default), an event widens to fill columns to its right that are
+     * free for its whole duration — the "wide when alone" look of Google Calendar.
+     * When false, every event keeps a single-column width (`span` is always 1).
+     */
+    expand?: boolean;
+}
+/**
+ * The result of laying out one interval.
+ *
+ * Two coordinate systems are provided so any renderer can consume it:
+ *  - **Structural** (`columnIndex`, `columnCount`, `span`): integer column math,
+ *    for callers that want to compute their own pixel geometry.
+ *  - **Fractional** (`top`, `height`, `left`, `width`): all in the range 0..1
+ *    relative to the day window, ready to drop into `style` as percentages.
+ *
+ * `left + width` never exceeds 1, and `top + height` never exceeds 1.
+ */
+interface PositionedInterval<T extends Interval = Interval> {
+    /** The original interval, unmodified. */
+    data: T;
+    /** Zero-based column this event occupies within its overlap cluster. */
+    columnIndex: number;
+    /** Total number of columns in this event's overlap cluster (>= 1). */
+    columnCount: number;
+    /** How many columns wide the event is after expansion (>= 1). */
+    span: number;
+    /** Fraction (0..1) from the top of the day window to the event's start. */
+    top: number;
+    /** Fraction (0..1) of the day window covered by the event's duration. */
+    height: number;
+    /** Fraction (0..1) from the left edge to the event's column. */
+    left: number;
+    /** Fraction (0..1) of the width the event occupies. */
+    width: number;
+}
+
+/**
+ * Lay out timed events for a single day/column axis, resolving overlaps into
+ * side-by-side columns.
+ *
+ * Algorithm (the same shape Google Calendar uses):
+ *  1. **Normalize** — clamp every event to the day window, drop anything that
+ *     falls outside it, optionally enforce a minimum duration.
+ *  2. **Sort** — by start ascending, then by end descending (longer events
+ *     first), then by id for a stable, deterministic order.
+ *  3. **Cluster** — sweep the sorted list into maximal runs of transitively
+ *     overlapping events. Columns are counted per cluster, so a busy morning
+ *     never shrinks a quiet afternoon.
+ *  4. **Pack** — within a cluster, greedily drop each event into the first
+ *     column whose previous event has already ended; open a new column only
+ *     when none is free.
+ *  5. **Expand** — optionally widen each event rightward across columns that are
+ *     free for its entire duration.
+ *
+ * The engine is pure and deterministic: same input → same output, no clock, no
+ * DOM, no framework.
+ */
+declare function layoutDay<T extends Interval>(events: readonly T[], options?: LayoutOptions): PositionedInterval<T>[];
+
+export { type Interval, type LayoutOptions, type PositionedInterval, layoutDay };

package/dist/index.js

@@ -0,0 +1,90 @@
+// src/layout.ts
+function overlaps(aStart, aEnd, bStart, bEnd) {
+  return aStart < bEnd && bStart < aEnd;
+}
+function layoutDay(events, options = {}) {
+  const dayStart = options.dayStart ?? 0;
+  const dayEnd = options.dayEnd ?? 1440;
+  const expand = options.expand ?? true;
+  const minDuration = options.minDuration ?? 0;
+  const range = dayEnd - dayStart;
+  if (range <= 0) return [];
+  const norm = [];
+  for (const e of events) {
+    let start = Math.max(e.start, dayStart);
+    let end = Math.min(e.end, dayEnd);
+    if (minDuration > 0 && end - start < minDuration) {
+      end = Math.min(start + minDuration, dayEnd);
+      start = Math.max(dayStart, end - minDuration);
+    }
+    if (end <= start) continue;
+    norm.push({ data: e, start, end });
+  }
+  if (norm.length === 0) return [];
+  norm.sort(
+    (a, b) => a.start - b.start || b.end - a.end || String(a.data.id).localeCompare(String(b.data.id))
+  );
+  const result = [];
+  let i = 0;
+  while (i < norm.length) {
+    let clusterEnd = norm[i].end;
+    let j = i + 1;
+    while (j < norm.length && norm[j].start < clusterEnd) {
+      clusterEnd = Math.max(clusterEnd, norm[j].end);
+      j++;
+    }
+    layoutCluster(norm.slice(i, j), { dayStart, range, expand }, result);
+    i = j;
+  }
+  return result;
+}
+function layoutCluster(cluster, ctx, out) {
+  const columns = [];
+  const columnOf = /* @__PURE__ */ new Map();
+  for (const ev of cluster) {
+    let placed = false;
+    for (let c = 0; c < columns.length; c++) {
+      const col = columns[c];
+      const last = col[col.length - 1];
+      if (last.end <= ev.start) {
+        col.push(ev);
+        columnOf.set(ev, c);
+        placed = true;
+        break;
+      }
+    }
+    if (!placed) {
+      columnOf.set(ev, columns.length);
+      columns.push([ev]);
+    }
+  }
+  const columnCount = columns.length;
+  for (const ev of cluster) {
+    const columnIndex = columnOf.get(ev);
+    const span = ctx.expand ? spanFor(ev, columnIndex, columnCount, columns) : 1;
+    out.push({
+      data: ev.data,
+      columnIndex,
+      columnCount,
+      span,
+      top: (ev.start - ctx.dayStart) / ctx.range,
+      height: (ev.end - ev.start) / ctx.range,
+      left: columnIndex / columnCount,
+      width: span / columnCount
+    });
+  }
+}
+function spanFor(ev, columnIndex, columnCount, columns) {
+  let span = 1;
+  for (let c = columnIndex + 1; c < columnCount; c++) {
+    const col = columns[c];
+    const blocked = col.some((o) => overlaps(ev.start, ev.end, o.start, o.end));
+    if (blocked) break;
+    span++;
+  }
+  return span;
+}
+
+export { layoutDay };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/layout.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Interval, LayoutOptions, PositionedInterval } from \"./types.js\";\n\n/** Internal, normalized (clamped) representation of an interval. */\ninterface Normalized<T extends Interval> {\n  data: T;\n  start: number;\n  end: number;\n}\n\n/** Two half-open intervals overlap iff each starts before the other ends. */\nfunction overlaps(aStart: number, aEnd: number, bStart: number, bEnd: number): boolean {\n  return aStart < bEnd && bStart < aEnd;\n}\n\n/**\n * Lay out timed events for a single day/column axis, resolving overlaps into\n * side-by-side columns.\n *\n * Algorithm (the same shape Google Calendar uses):\n *  1. **Normalize** — clamp every event to the day window, drop anything that\n *     falls outside it, optionally enforce a minimum duration.\n *  2. **Sort** — by start ascending, then by end descending (longer events\n *     first), then by id for a stable, deterministic order.\n *  3. **Cluster** — sweep the sorted list into maximal runs of transitively\n *     overlapping events. Columns are counted per cluster, so a busy morning\n *     never shrinks a quiet afternoon.\n *  4. **Pack** — within a cluster, greedily drop each event into the first\n *     column whose previous event has already ended; open a new column only\n *     when none is free.\n *  5. **Expand** — optionally widen each event rightward across columns that are\n *     free for its entire duration.\n *\n * The engine is pure and deterministic: same input → same output, no clock, no\n * DOM, no framework.\n */\nexport function layoutDay<T extends Interval>(\n  events: readonly T[],\n  options: LayoutOptions = {},\n): PositionedInterval<T>[] {\n  const dayStart = options.dayStart ?? 0;\n  const dayEnd = options.dayEnd ?? 1440;\n  const expand = options.expand ?? true;\n  const minDuration = options.minDuration ?? 0;\n\n  const range = dayEnd - dayStart;\n  if (range <= 0) return [];\n\n  // 1. Normalize: clamp to window, apply minDuration, drop out-of-window.\n  const norm: Normalized<T>[] = [];\n  for (const e of events) {\n    let start = Math.max(e.start, dayStart);\n    let end = Math.min(e.end, dayEnd);\n    if (minDuration > 0 && end - start < minDuration) {\n      end = Math.min(start + minDuration, dayEnd);\n      // If clamping to the window pushed us against the wall, pull start back\n      // so a min-duration event near dayEnd still renders its full min height.\n      start = Math.max(dayStart, end - minDuration);\n    }\n    if (end <= start) continue;\n    norm.push({ data: e, start, end });\n  }\n  if (norm.length === 0) return [];\n\n  // 2. Sort: start asc, end desc, id asc.\n  norm.sort(\n    (a, b) =>\n      a.start - b.start ||\n      b.end - a.end ||\n      String(a.data.id).localeCompare(String(b.data.id)),\n  );\n\n  const result: PositionedInterval<T>[] = [];\n\n  // 3. Cluster + 4. Pack + 5. Expand, one maximal overlap-run at a time.\n  let i = 0;\n  while (i < norm.length) {\n    let clusterEnd = norm[i]!.end;\n    let j = i + 1;\n    while (j < norm.length && norm[j]!.start < clusterEnd) {\n      clusterEnd = Math.max(clusterEnd, norm[j]!.end);\n      j++;\n    }\n    layoutCluster(norm.slice(i, j), { dayStart, range, expand }, result);\n    i = j;\n  }\n\n  return result;\n}\n\ninterface ClusterContext {\n  dayStart: number;\n  range: number;\n  expand: boolean;\n}\n\nfunction layoutCluster<T extends Interval>(\n  cluster: readonly Normalized<T>[],\n  ctx: ClusterContext,\n  out: PositionedInterval<T>[],\n): void {\n  // 4. Greedy column packing. `columns[c]` holds the events placed in column c,\n  // in time order; the last one determines whether the column is free.\n  const columns: Normalized<T>[][] = [];\n  const columnOf = new Map<Normalized<T>, number>();\n\n  for (const ev of cluster) {\n    let placed = false;\n    for (let c = 0; c < columns.length; c++) {\n      const col = columns[c]!;\n      const last = col[col.length - 1]!;\n      if (last.end <= ev.start) {\n        col.push(ev);\n        columnOf.set(ev, c);\n        placed = true;\n        break;\n      }\n    }\n    if (!placed) {\n      columnOf.set(ev, columns.length);\n      columns.push([ev]);\n    }\n  }\n\n  const columnCount = columns.length;\n\n  // 5. Expansion + geometry.\n  for (const ev of cluster) {\n    const columnIndex = columnOf.get(ev)!;\n    const span = ctx.expand\n      ? spanFor(ev, columnIndex, columnCount, columns)\n      : 1;\n\n    out.push({\n      data: ev.data,\n      columnIndex,\n      columnCount,\n      span,\n      top: (ev.start - ctx.dayStart) / ctx.range,\n      height: (ev.end - ev.start) / ctx.range,\n      left: columnIndex / columnCount,\n      width: span / columnCount,\n    });\n  }\n}\n\n/**\n * How many columns `ev` can occupy: start at its own column and extend right\n * while every event in the next column clears its time span.\n */\nfunction spanFor<T extends Interval>(\n  ev: Normalized<T>,\n  columnIndex: number,\n  columnCount: number,\n  columns: readonly Normalized<T>[][],\n): number {\n  let span = 1;\n  for (let c = columnIndex + 1; c < columnCount; c++) {\n    const col = columns[c]!;\n    const blocked = col.some((o) => overlaps(ev.start, ev.end, o.start, o.end));\n    if (blocked) break;\n    span++;\n  }\n  return span;\n}\n"]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "calendar-ui-layout",
+  "version": "0.1.0",
+  "description": "Headless time-grid layout engine: overlap-column resolution for calendar/scheduler week & day views. UI-agnostic, zero runtime dependencies.",
+  "keywords": [
+    "calendar",
+    "scheduler",
+    "headless",
+    "layout",
+    "overlap",
+    "time-grid",
+    "react",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "jiku0730",
+  "homepage": "https://github.com/jiku0730/calendar-ui-layout#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jiku0730/calendar-ui-layout.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jiku0730/calendar-ui-layout/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "demo": "tsx examples/ascii-preview.ts",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "tsx": "^4.23.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  }
+}