@joewinke/jatui 0.37.0 → 0.38.0

package/dist/artifact-blocks/blocks/timeline/schema.js

@@ -0,0 +1,405 @@
+/**
+ * Timeline block — params schema, validation, date scale and layout
+ * (mos-d70v4).
+ *
+ * Pure functions only (no DOM): dates parse to UTC-midnight epoch ms (a
+ * date-only ISO string parses identically in every timezone), the domain,
+ * ticks, lane rows and dependency elbows are computed here, and colors
+ * NEVER appear — the renderer maps tones to theme-token classes.
+ *
+ * Untrusted-input rules (CONTRACT.md): text params are length-capped
+ * strings, dates are ISO-validated (impossible calendar dates are refused
+ * at publish), arrays are capped (50 milestones / 80 bars / 120 deps).
+ */
+import { z } from "zod";
+import { toneSchema, isoDateSchema } from "../../params.js";
+import { MAX_MILESTONES, MAX_BARS, MAX_DEPS, MAX_LANES, BAR_TEXT_MAX, ID_MAX, LANE_MAX, } from "./constants.js";
+// ── Schemas ───────────────────────────────────────────────────────────────
+const timelineIdSchema = z
+    .string()
+    .min(1)
+    .max(ID_MAX)
+    .regex(/^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/);
+const milestoneSchema = z.object({
+    id: timelineIdSchema.optional(),
+    label: z.string().min(1).max(BAR_TEXT_MAX),
+    date: isoDateSchema,
+    tone: toneSchema.optional(),
+    lane: z.string().min(1).max(LANE_MAX).optional(),
+});
+const barSchema = z.object({
+    id: timelineIdSchema,
+    label: z.string().min(1).max(BAR_TEXT_MAX),
+    start: isoDateSchema,
+    end: isoDateSchema,
+    lane: z.string().min(1).max(LANE_MAX).optional(),
+    tone: toneSchema.optional(),
+    /** Completion percentage 0-100 (int) — renders a darker fill portion. */
+    progress: z.number().int().min(0).max(100).optional(),
+});
+const dependencySchema = z.object({
+    from: timelineIdSchema,
+    to: timelineIdSchema,
+});
+export const timelineParamsSchema = z
+    .object({
+    title: z.string().max(200).optional(),
+    subtitle: z.string().max(300).optional(),
+    /** Axis granularity: day / week / month ticks. */
+    zoom: z.enum(["day", "week", "month"]).default("month"),
+    /** Dashed "today" line at the current date (when it falls in range). */
+    showToday: z.boolean().default(true),
+    milestones: z.array(milestoneSchema).max(MAX_MILESTONES).default([]),
+    bars: z.array(barSchema).max(MAX_BARS).default([]),
+    dependencies: z.array(dependencySchema).max(MAX_DEPS).default([]),
+    /** Explicit lane order; lanes discovered from bars/milestones append. */
+    lanes: z.array(z.string().min(1).max(LANE_MAX)).max(MAX_LANES).optional(),
+})
+    .superRefine((p, ctx) => {
+    // bar ids unique; end >= start
+    const barIds = new Set();
+    for (const [i, b] of p.bars.entries()) {
+        if (barIds.has(b.id)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Duplicate bar id "${b.id}" (bar ${i})`,
+                path: ["bars", i, "id"],
+            });
+        }
+        barIds.add(b.id);
+        if (Date.parse(b.start) > Date.parse(b.end)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Bar "${b.id}" ends before it starts`,
+                path: ["bars", i, "end"],
+            });
+        }
+    }
+    // milestone ids unique (when given)
+    const msIds = new Set();
+    for (const [i, m] of p.milestones.entries()) {
+        if (!m.id)
+            continue;
+        if (msIds.has(m.id)) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Duplicate milestone id "${m.id}" (milestone ${i})`,
+                path: ["milestones", i, "id"],
+            });
+        }
+        msIds.add(m.id);
+    }
+    // dependencies reference bars, no self-deps, no duplicates
+    p.dependencies.forEach((d, i) => {
+        for (const key of ["from", "to"]) {
+            if (!barIds.has(d[key])) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: `Dependency ${i} ${key} "${d[key]}" has no bar`,
+                    path: ["dependencies", i, key],
+                });
+            }
+        }
+        if (d.from === d.to) {
+            ctx.addIssue({
+                code: "custom",
+                message: `Dependency ${i} is a self-dependency`,
+                path: ["dependencies", i],
+            });
+        }
+        for (let j = 0; j < i; j++) {
+            const o = p.dependencies[j];
+            if (o.from === d.from && o.to === d.to) {
+                ctx.addIssue({
+                    code: "custom",
+                    message: `Dependency ${i} duplicates dependency ${j}`,
+                    path: ["dependencies", i],
+                });
+            }
+        }
+    });
+});
+// ── Date scale (UTC-day anchored, deterministic) ──────────────────────────
+export const DAY_MS = 86_400_000;
+/** ISO date(-time) → epoch ms. Date-only strings are UTC midnight. */
+export function parseDay(v) {
+    const ms = Date.parse(v);
+    return Number.isFinite(ms) ? ms : Number.NaN;
+}
+function startOfUtcDay(ms) {
+    return Math.floor(ms / DAY_MS) * DAY_MS;
+}
+export function addDays(ms, days) {
+    return ms + days * DAY_MS;
+}
+/** UTC Monday 00:00 of the week containing ms. */
+function startOfUtcWeek(ms) {
+    const d = new Date(ms);
+    const day = (d.getUTCDay() + 6) % 7; // Mon=0 … Sun=6
+    return startOfUtcDay(ms) - day * DAY_MS;
+}
+/** UTC 1st of the month 00:00 containing ms. */
+function startOfUtcMonth(ms) {
+    const d = new Date(ms);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
+}
+/** Tick steps (in units) that keep the tick count honest. */
+const STEP_LADDER = [1, 2, 3, 6, 12];
+/** Calendar-aware ticks for the domain at the chosen zoom, snapped to real
+ * day/week/month boundaries (never "Mar 34"). Returns ≤ ~48 ticks; the step
+ * widens when the span is too long for the zoom. */
+export function timeTicks(d0, d1, zoom) {
+    if (!Number.isFinite(d0) || !Number.isFinite(d1) || d1 <= d0)
+        return [];
+    const spanDays = (d1 - d0) / DAY_MS;
+    const out = [];
+    if (zoom === "day") {
+        const stepDays = STEP_LADDER.concat([14]).find((s) => spanDays / s <= 46) ?? 14;
+        let t = startOfUtcDay(d0);
+        while (t <= d1) {
+            if (t >= d0)
+                out.push({
+                    ms: t,
+                    label: new Intl.DateTimeFormat("en-US", {
+                        month: "short",
+                        day: "numeric",
+                    }).format(t),
+                });
+            t = addDays(t, stepDays);
+        }
+        return out;
+    }
+    if (zoom === "week") {
+        const stepWeeks = STEP_LADDER.find((s) => spanDays / (7 * s) <= 46) ?? 12;
+        let t = startOfUtcWeek(d0);
+        while (t <= d1) {
+            if (t >= d0)
+                out.push({
+                    ms: t,
+                    label: new Intl.DateTimeFormat("en-US", {
+                        month: "short",
+                        day: "numeric",
+                    }).format(t),
+                });
+            t = addDays(t, 7 * stepWeeks);
+        }
+        return out;
+    }
+    const stepMonths = STEP_LADDER.find((s) => spanDays / (30.4 * s) <= 46) ?? 12;
+    let t = startOfUtcMonth(d0);
+    while (t <= d1 && out.length < 60) {
+        if (t >= d0) {
+            const d = new Date(t);
+            const jan = d.getUTCMonth() === 0;
+            out.push({
+                ms: t,
+                label: jan
+                    ? new Intl.DateTimeFormat("en-US", {
+                        month: "short",
+                        year: "numeric",
+                    }).format(t)
+                    : new Intl.DateTimeFormat("en-US", { month: "short" }).format(t),
+            });
+        }
+        const d = new Date(t);
+        t = Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + stepMonths, 1);
+    }
+    return out;
+}
+/** Domain pad per zoom (days each side) so marks aren't glued to the edge. */
+function padDays(zoom) {
+    return zoom === "day" ? 1 : zoom === "week" ? 3 : 10;
+}
+/** Date domain over milestones + bars, padded per zoom. */
+function timeDomain(p) {
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    for (const m of p.milestones) {
+        const t = parseDay(m.date);
+        if (Number.isFinite(t)) {
+            min = Math.min(min, t);
+            max = Math.max(max, t);
+        }
+    }
+    for (const b of p.bars) {
+        const s = parseDay(b.start);
+        const e = parseDay(b.end);
+        if (Number.isFinite(s))
+            min = Math.min(min, s);
+        if (Number.isFinite(e))
+            max = Math.max(max, e);
+    }
+    if (!Number.isFinite(min) || !Number.isFinite(max)) {
+        // no data: a one-week window around today keeps the axis honest
+        const today = startOfUtcDay(Date.now());
+        return { d0: addDays(today, -2), d1: addDays(today, 5) };
+    }
+    min = startOfUtcDay(min);
+    max = startOfUtcDay(max);
+    if (min === max)
+        max = addDays(max, 1);
+    const pad = padDays(p.zoom);
+    return { d0: addDays(min, -pad), d1: addDays(max, pad) };
+}
+// ── Lanes ─────────────────────────────────────────────────────────────────
+const MILESTONE_LANE = "__milestones";
+/** Lane order: explicit `lanes` first (only those with items), then lanes
+ * discovered from bars/milestones in first-seen order. Lane-less milestones
+ * land on the dedicated top lane; lane-less bars on a trailing "—"-labeled
+ * lane. Returns lane ids with display labels. */
+function laneOrder(p) {
+    const out = [];
+    const seen = new Set();
+    const push = (id, label) => {
+        if (!seen.has(id)) {
+            seen.add(id);
+            out.push({ id, label });
+        }
+    };
+    const msLaneless = p.milestones.some((m) => !m.lane);
+    if (msLaneless)
+        push(MILESTONE_LANE, "Milestones");
+    for (const l of p.lanes ?? [])
+        push(l, l);
+    for (const m of p.milestones)
+        if (m.lane)
+            push(m.lane, m.lane);
+    for (const b of p.bars)
+        if (b.lane)
+            push(b.lane, b.lane);
+    if (p.bars.some((b) => !b.lane))
+        push("", "Tasks");
+    return out;
+}
+// ── Layout ────────────────────────────────────────────────────────────────
+const TICK_H = 22;
+const ROW_PAD = 9;
+const BAR_H = 16;
+const SUB_ROW_H = BAR_H + 7;
+/** Full layout for the renderer. `nowMs` (client-only) adds the today line
+ * when it falls inside the domain; SSR passes null and the line is skipped
+ * — no hydration mismatch. */
+export function layoutTimeline(p, opts = {
+    plotW: 700,
+    laneW: 120,
+    nowMs: null,
+}) {
+    const { d0, d1 } = timeDomain(p);
+    const span = Math.max(1, d1 - d0);
+    const xFor = (ms) => opts.laneW + ((ms - d0) / span) * Math.max(40, opts.plotW);
+    const rows = [];
+    let y = TICK_H + ROW_PAD;
+    const laneDefs = laneOrder(p);
+    for (const lane of laneDefs) {
+        const bars = p.bars
+            .filter((b) => (b.lane ?? "") === lane.id)
+            .sort((a, b) => Date.parse(a.start) - Date.parse(b.start));
+        const milestones = p.milestones.filter((m) => (m.lane ?? "") === lane.id || (!m.lane && lane.id === MILESTONE_LANE));
+        // greedy sub-rows so overlapping bars in one lane stack
+        const subEnds = [];
+        const placed = bars.map((b) => {
+            const s = parseDay(b.start);
+            const e = parseDay(b.end);
+            let sub = subEnds.findIndex((end) => end <= s);
+            if (sub === -1) {
+                subEnds.push(e);
+                sub = subEnds.length - 1;
+            }
+            else
+                subEnds[sub] = e;
+            return { bar: b, sub, x: xFor(s), w: Math.max(2, xFor(e) - xFor(s)) };
+        });
+        const subCount = Math.max(subEnds.length, milestones.length ? 1 : 0, 1);
+        const height = subCount * SUB_ROW_H + ROW_PAD;
+        const rowY = y;
+        y += height;
+        rows.push({
+            id: lane.id,
+            label: lane.label,
+            y: rowY,
+            height,
+            bars: placed.map((pl) => ({
+                id: pl.bar.id,
+                label: pl.bar.label,
+                tone: pl.bar.tone,
+                progress: pl.bar.progress,
+                start: pl.bar.start,
+                end: pl.bar.end,
+                x: pl.x,
+                w: pl.w,
+                y: rowY + ROW_PAD / 2 + pl.sub * SUB_ROW_H + (SUB_ROW_H - BAR_H) / 2,
+                xStartMs: parseDay(pl.bar.start),
+                xEndMs: parseDay(pl.bar.end),
+            })),
+            milestones: milestones.map((m) => ({
+                id: m.id ?? `ms-${m.label}`,
+                label: m.label,
+                tone: m.tone,
+                date: m.date,
+                x: xFor(parseDay(m.date)),
+                y: rowY + height / 2,
+            })),
+        });
+    }
+    const height = y + ROW_PAD;
+    const today = opts.nowMs != null &&
+        Number.isFinite(opts.nowMs) &&
+        opts.nowMs >= d0 &&
+        opts.nowMs <= d1
+        ? { x: xFor(startOfUtcDay(opts.nowMs)) }
+        : null;
+    return {
+        d0,
+        d1,
+        ticks: timeTicks(d0, d1, p.zoom).map((t) => ({
+            ...t,
+            x: xFor(t.ms),
+        })),
+        rows,
+        today,
+        width: opts.laneW + Math.max(40, opts.plotW) + 12,
+        height,
+        laneW: opts.laneW,
+    };
+}
+/** Dependency elbow path: from the END of bar A to the START of bar B,
+ * routed through the row gap. Points (not a path string) so the renderer
+ * draws + head-triangles it like every other polyline here. */
+export function dependencyPoints(from, to) {
+    const dir = to.xStart >= from.xEnd ? 1 : -1;
+    const gap = 8 * dir;
+    if (Math.abs(to.y - from.y) < 2)
+        return [
+            { x: from.xEnd, y: from.y },
+            { x: to.xStart, y: to.y },
+        ];
+    return [
+        { x: from.xEnd, y: from.y },
+        { x: from.xEnd + gap, y: from.y },
+        { x: from.xEnd + gap, y: to.y },
+        { x: to.xStart, y: to.y },
+    ];
+}
+const dayFmt = new Intl.DateTimeFormat("en-US", { dateStyle: "medium" });
+/** Flat rows for the accessible data fallback (sr-only table). */
+export function timelineRows(p) {
+    const rows = [];
+    for (const m of p.milestones)
+        rows.push({
+            kind: "milestone",
+            label: m.label,
+            detail: `${dayFmt.format(Date.parse(m.date))}${m.lane ? ` · ${m.lane}` : ""}`,
+        });
+    for (const b of p.bars)
+        rows.push({
+            kind: "bar",
+            label: b.label,
+            detail: `${b.start} → ${b.end}${b.lane ? ` · ${b.lane}` : ""}${b.progress != null ? ` · ${b.progress}%` : ""}`,
+        });
+    for (const d of p.dependencies) {
+        const f = p.bars.find((b) => b.id === d.from)?.label ?? d.from;
+        const t = p.bars.find((b) => b.id === d.to)?.label ?? d.to;
+        rows.push({ kind: "bar", label: `${f} → ${t}`, detail: "dependency" });
+    }
+    return rows;
+}

package/dist/artifact-blocks/blocks/timeline/thumb.d.ts

@@ -0,0 +1,2 @@
+import { type ThumbPalette } from "../../thumb-kit.js";
+export declare function drawTimelineThumb(raw: unknown, palette: ThumbPalette): string | null;

package/dist/artifact-blocks/blocks/timeline/thumb.js

@@ -0,0 +1,117 @@
+/**
+ * Timeline block thumbnail composer (mos-qkpva).
+ *
+ * The same layoutTimeline geometry the component draws (./schema.ts, pure and
+ * unit-tested) as a simplified silhouette: tick header, lane-labeled bar rows
+ * (tone fills at the component's opacities), progress overlays and milestone
+ * diamonds. The today line is client-only in the component (nowMs=null on
+ * SSR); the thumb passes null too, so a thumbnail never lies about "today".
+ *
+ * A timeline can be very tall (24 lanes); the thumb keeps rows only while
+ * they fit a ~2:1 box and clips the viewBox to what it drew — a tall timeline
+ * shows its first rows, not a dust-scale whole.
+ */
+import { timelineParamsSchema, layoutTimeline, } from "./schema.js";
+import { LANE_W, BAR_H, MS_R } from "./constants.js";
+import { r1, thumbText, thumbTruncate, toneColor, } from "../../thumb-kit.js";
+const PLOT_W = 480;
+const MAX_ROWS_HEIGHT = 300;
+/** The components' static tone maps, resolved to concrete color+opacity. */
+function barFill(palette, tone) {
+    switch (tone) {
+        case "success":
+        case "warning":
+            return { fill: toneColor(palette, tone), opacity: 0.3 };
+        case "neutral":
+            return { fill: palette.ink, opacity: 0.15 };
+        case undefined:
+            return { fill: palette.primary, opacity: 0.25 };
+        default:
+            return { fill: toneColor(palette, tone), opacity: 0.25 };
+    }
+}
+function barStroke(palette, tone) {
+    switch (tone) {
+        case "warning":
+            return { stroke: palette.warning, opacity: 0.8 };
+        case "neutral":
+            return { stroke: palette.ink, opacity: 0.35 };
+        case undefined:
+            return { stroke: palette.primary, opacity: 0.7 };
+        default:
+            return { stroke: toneColor(palette, tone), opacity: 0.7 };
+    }
+}
+function progressFill(palette, tone) {
+    switch (tone) {
+        case "neutral":
+            return { fill: palette.ink, opacity: 0.4 };
+        case undefined:
+            return { fill: palette.primary, opacity: 0.6 };
+        default:
+            return { fill: toneColor(palette, tone), opacity: 0.6 };
+    }
+}
+export function drawTimelineThumb(raw, palette) {
+    const parsed = timelineParamsSchema.safeParse(raw);
+    if (!parsed.success)
+        return null;
+    const params = parsed.data;
+    if (params.bars.length === 0 && params.milestones.length === 0)
+        return null;
+    const layout = layoutTimeline(params, {
+        plotW: PLOT_W,
+        laneW: LANE_W,
+        nowMs: null,
+    });
+    // Keep rows until they no longer fit the ~2:1 silhouette box; the drawn
+    // height becomes the viewBox height.
+    const rows = [];
+    let drawnH = layout.rows.length ? layout.rows[0].y : 0;
+    for (const row of layout.rows) {
+        rows.push(row);
+        drawnH = row.y + row.height;
+        if (drawnH > MAX_ROWS_HEIGHT && rows.length > 1) {
+            rows.pop();
+            drawnH = (rows.at(-1)?.y ?? 0) + (rows.at(-1)?.height ?? 0);
+            break;
+        }
+    }
+    if (rows.length === 0)
+        return null;
+    const W = Math.max(240, layout.width);
+    const H = Math.max(60, drawnH + 6);
+    const out = [];
+    // tick header (position + faint line only — labels are dust at cell size)
+    for (const t of layout.ticks) {
+        out.push(`<line x1="${r1(t.x)}" x2="${r1(t.x)}" y1="0" y2="${r1(H)}" stroke="${palette.ink}" stroke-opacity="0.08" stroke-width="1"/>`);
+    }
+    for (const row of rows) {
+        // lane label
+        if (row.label)
+            out.push(thumbText(8, row.y + row.height / 2 + 3, thumbTruncate(row.label, 14), {
+                size: 10,
+                fill: palette.ink,
+                opacity: 0.55,
+            }));
+        // row hairline separator (alternate, like the component)
+        out.push(`<line x1="${r1(LANE_W)}" x2="${r1(W)}" y1="${r1(row.y + row.height)}" y2="${r1(row.y + row.height)}" stroke="${palette.ink}" stroke-opacity="0.08" stroke-width="1"/>`);
+        for (const b of row.bars) {
+            const f = barFill(palette, b.tone);
+            const s = barStroke(palette, b.tone);
+            out.push(`<rect x="${r1(b.x)}" y="${r1(b.y)}" width="${r1(Math.max(2, b.w))}" height="${BAR_H}" rx="4" fill="${f.fill}" fill-opacity="${f.opacity}" stroke="${s.stroke}" stroke-opacity="${s.opacity}" stroke-width="1"/>`);
+            if (b.progress != null) {
+                const pf = progressFill(palette, b.tone);
+                out.push(`<rect x="${r1(b.x)}" y="${r1(b.y)}" width="${r1(Math.max(2, (b.w * b.progress) / 100))}" height="${BAR_H}" rx="4" fill="${pf.fill}" fill-opacity="${pf.opacity}"/>`);
+            }
+        }
+        for (const m of row.milestones) {
+            const tone = m.tone ?? "accent";
+            const color = toneColor(palette, tone === "neutral" ? "accent" : tone);
+            const cx = r1(m.x);
+            const cy = r1(m.y);
+            out.push(`<polygon points="${cx},${cy - MS_R} ${cx + MS_R},${cy} ${cx},${cy + MS_R} ${cx - MS_R},${cy}" fill="${color}"/>`);
+        }
+    }
+    return `<svg viewBox="0 0 ${r1(W)} ${r1(H)}">${out.join("")}</svg>`;
+}

package/dist/artifact-blocks/blocks/timeline/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Timeline block — shared types. schema.ts owns the zod schema and infers
+ * TimelineParams from it; this file carries the layout vocabulary so
+ * schema.ts and TimelineBlock.svelte agree without a cycle.
+ */
+import type { z } from "zod";
+import type { ToneTokenT } from "./constants.js";
+import type { timelineParamsSchema } from "./schema.js";
+export type ToneToken = ToneTokenT;
+export type TimelineParams = z.infer<typeof timelineParamsSchema>;
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Tick {
+    ms: number;
+    label: string;
+    /** x pixel position (layout fills this in). */
+    x: number;
+}
+export interface TimelineBar {
+    id: string;
+    label: string;
+    tone?: ToneToken;
+    progress?: number;
+    start: string;
+    end: string;
+    /** Pixel geometry (layout fills these in). */
+    x: number;
+    w: number;
+    y: number;
+    /** Parsed epoch ms of start/end (for dependency routing). */
+    xStartMs: number;
+    xEndMs: number;
+}
+export interface TimelineMilestone {
+    id: string;
+    label: string;
+    tone?: ToneToken;
+    date: string;
+    /** Pixel center of the diamond (layout fills these in). */
+    x: number;
+    y: number;
+}
+export interface LaneRow {
+    id: string;
+    label: string;
+    y: number;
+    height: number;
+    bars: TimelineBar[];
+    milestones: TimelineMilestone[];
+}
+export interface TimelineLayout {
+    /** UTC-day-anchored domain (epoch ms). */
+    d0: number;
+    d1: number;
+    ticks: Tick[];
+    rows: LaneRow[];
+    /** Today line when it falls inside the domain (client-only). */
+    today: {
+        x: number;
+    } | null;
+    width: number;
+    height: number;
+    laneW: number;
+}

package/dist/artifact-blocks/blocks/timeline/types.js

@@ -0,0 +1 @@
+export {};