trekoon 0.2.8 → 0.3.0

package/src/board/assets/state/url.js

@@ -0,0 +1,184 @@
+/**
+ * URL hash synchronization for board state.
+ *
+ * Serializes epic, task, search, and view into the URL hash so that
+ * browser back/forward and refresh preserve board navigation.
+ * Theme stays in localStorage; token stays in sessionStorage.
+ */
+
+const DEFAULT_VIEW = "kanban";
+
+function toHistoryState(state) {
+  return {
+    screen: state.screen || "epics",
+    selectedEpicId: state.selectedEpicId || null,
+    view: state.view || DEFAULT_VIEW,
+  };
+}
+
+function shouldPushHistoryEntry(previousState, nextState) {
+  if (!previousState) {
+    return false;
+  }
+
+  return previousState.selectedEpicId !== nextState.selectedEpicId
+    || previousState.screen !== nextState.screen
+    || previousState.view !== nextState.view;
+}
+
+/**
+ * Serialize board-relevant state fields into a URL hash string.
+ * Omits default values to keep the URL clean.
+ *
+ * @param {object} state
+ * @param {string|null} state.selectedEpicId
+ * @param {string|null} state.selectedTaskId
+ * @param {string} state.screen
+ * @param {string} state.search
+ * @param {string} state.view
+ * @returns {string} Hash string without leading '#'
+ */
+export function stateToHash(state) {
+  const params = new URLSearchParams();
+
+  if (state.selectedEpicId) {
+    params.set("epic", state.selectedEpicId);
+  }
+  if (state.selectedTaskId) {
+    params.set("task", state.selectedTaskId);
+  }
+  if (state.screen === "epics" && state.selectedEpicId) {
+    params.set("screen", "epics");
+  }
+  if (state.search && state.search.trim().length > 0) {
+    params.set("search", state.search);
+  }
+  if (state.view && state.view !== DEFAULT_VIEW) {
+    params.set("view", state.view);
+  }
+
+  const hash = params.toString();
+  return hash;
+}
+
+/**
+ * Parse a URL hash string back into state fields.
+ *
+ * @param {string} hash - Hash string (with or without leading '#')
+ * @returns {{ selectedEpicId: string|null, selectedTaskId: string|null, search: string, view: string, screen: string }}
+ */
+export function hashToState(hash) {
+  const cleaned = hash.startsWith("#") ? hash.slice(1) : hash;
+  const params = new URLSearchParams(cleaned);
+
+  const epicId = params.get("epic") || null;
+  const taskId = params.get("task") || null;
+  const screenParam = params.get("screen");
+  const search = params.get("search") || "";
+  const view = params.get("view") || DEFAULT_VIEW;
+  const screen = screenParam === "epics" || screenParam === "tasks"
+    ? screenParam
+    : epicId || taskId
+      ? "tasks"
+      : "epics";
+
+  return {
+    selectedEpicId: epicId,
+    selectedTaskId: taskId,
+    search,
+    view,
+    screen,
+  };
+}
+
+/**
+ * Set up bidirectional URL hash synchronization with a store.
+ *
+ * - On store changes, pushes history for major navigation changes and replaces
+ *   the current entry for noisy state like transient selection/search.
+ * - On hashchange (browser back/forward), reads the hash and updates store state.
+ *
+ * @param {object} store - Observable store from createStore
+ * @param {object} [options]
+ * @param {() => void} [options.onRestore] - Callback after URL-driven state restore
+ * @returns {() => void} Cleanup function that removes event listeners and unsubscribes
+ */
+export function syncUrlHash(store, options = {}) {
+  const { beforeRestore, onRestore } = options;
+  let isApplyingLocation = false;
+  let lastSerializedState = "";
+  let lastHistoryState = toHistoryState(store.store);
+
+  function serializeCurrentState() {
+    return stateToHash(store.store);
+  }
+
+  function buildUrl(hash) {
+    const { pathname, search } = window.location;
+    return `${pathname}${search}${hash.length > 0 ? `#${hash}` : ""}`;
+  }
+
+  function applyLocation(hash, mode) {
+    const nextUrl = buildUrl(hash);
+    const currentUrl = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+    lastSerializedState = hash;
+    if (nextUrl === currentUrl) {
+      return;
+    }
+
+    if (mode === "push") {
+      window.history.pushState({ boardHash: hash }, "", nextUrl);
+      return;
+    }
+
+    window.history.replaceState({ boardHash: hash }, "", nextUrl);
+  }
+
+  function restoreFromLocation() {
+    beforeRestore?.();
+    isApplyingLocation = true;
+    const urlState = hashToState(window.location.hash);
+    const restoredState = store.syncState(urlState);
+    store.persist();
+    const restoredHash = stateToHash(restoredState);
+    applyLocation(restoredHash, "replace");
+    lastSerializedState = restoredHash;
+    lastHistoryState = toHistoryState(store.store);
+    isApplyingLocation = false;
+    onRestore?.();
+  }
+
+  // Restore state from current URL hash on init
+  if (window.location.hash.length > 1) {
+    restoreFromLocation();
+  } else {
+    applyLocation(serializeCurrentState(), "replace");
+  }
+
+  // Store → URL: update hash when state changes
+  const unsubscribe = store.subscribe(() => {
+    if (isApplyingLocation) {
+      return;
+    }
+
+    const hash = serializeCurrentState();
+    if (hash !== lastSerializedState) {
+      const nextHistoryState = toHistoryState(store.store);
+      const mode = shouldPushHistoryEntry(lastHistoryState, nextHistoryState) ? "push" : "replace";
+      applyLocation(hash, mode);
+      lastHistoryState = nextHistoryState;
+    }
+  });
+
+  // URL → Store: respond to browser back/forward
+  function onPopState() {
+    restoreFromLocation();
+  }
+
+  window.addEventListener("popstate", onPopState);
+
+  return () => {
+    unsubscribe();
+    window.removeEventListener("popstate", onPopState);
+  };
+}

package/src/board/assets/state/utils.js

@@ -0,0 +1,222 @@
+/** @type {readonly string[]} */
+export const STATUS_ORDER = ["todo", "blocked", "in_progress", "done"];
+
+/** @type {readonly string[]} */
+export const VIEW_MODES = ["kanban", "list"];
+
+const VALID_STATUSES = new Set(STATUS_ORDER);
+
+/**
+ * Normalize a raw status string into one of the canonical status values.
+ * @param {string} rawStatus
+ * @returns {"todo"|"blocked"|"in_progress"|"done"}
+ */
+export function normalizeStatus(rawStatus) {
+  if (rawStatus === "in-progress") return "in_progress";
+  if (VALID_STATUSES.has(rawStatus)) return rawStatus;
+  return "todo";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {any[]}
+ */
+function normalizeArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+/**
+ * @param {{ id?: string }} record
+ * @returns {string}
+ */
+function getId(record) {
+  return typeof record?.id === "string" && record.id.length > 0 ? record.id : crypto.randomUUID();
+}
+
+/**
+ * @param {any[]} tasks
+ * @returns {Record<string, number>}
+ */
+function deriveCounts(tasks) {
+  return STATUS_ORDER.reduce((counts, status) => {
+    counts[status] = tasks.filter((task) => task.status === status).length;
+    return counts;
+  }, {});
+}
+
+/**
+ * Normalize a raw board snapshot into the canonical shape with search text,
+ * dependency cross-references, and epic counts.
+ * @param {object} rawSnapshot
+ * @returns {object}
+ */
+export function normalizeSnapshot(rawSnapshot) {
+  const rawEpics = normalizeArray(rawSnapshot?.epics);
+  const rawTasks = normalizeArray(rawSnapshot?.tasks);
+  const rawSubtasks = normalizeArray(rawSnapshot?.subtasks);
+  const rawDependencies = normalizeArray(rawSnapshot?.dependencies);
+  const taskIndex = new Map();
+  const subtaskIndex = new Map();
+
+  const tasks = rawTasks.map((task) => {
+    const normalizedTask = {
+      id: getId(task),
+      kind: "task",
+      epicId: task.epicId ?? task.epic?.id ?? null,
+      title: String(task.title ?? "Untitled task"),
+      description: String(task.description ?? "").replace(/\\n/g, "\n"),
+      status: normalizeStatus(task.status),
+      createdAt: Number(task.createdAt ?? Date.now()),
+      updatedAt: Number(task.updatedAt ?? task.createdAt ?? Date.now()),
+      blockedBy: [],
+      blocks: [],
+      dependencyIds: [],
+      dependentIds: [],
+      subtasks: [],
+      searchText: "",
+    };
+
+    taskIndex.set(normalizedTask.id, normalizedTask);
+    return normalizedTask;
+  });
+
+  const subtasks = rawSubtasks.map((subtask) => {
+    const normalizedSubtask = {
+      id: getId(subtask),
+      kind: "subtask",
+      taskId: subtask.taskId ?? subtask.task?.id ?? null,
+      title: String(subtask.title ?? "Untitled subtask"),
+      description: String(subtask.description ?? "").replace(/\\n/g, "\n"),
+      status: normalizeStatus(subtask.status),
+      createdAt: Number(subtask.createdAt ?? Date.now()),
+      updatedAt: Number(subtask.updatedAt ?? subtask.createdAt ?? Date.now()),
+      blockedBy: [],
+      blocks: [],
+      dependencyIds: [],
+      dependentIds: [],
+      searchText: "",
+    };
+
+    subtaskIndex.set(normalizedSubtask.id, normalizedSubtask);
+    return normalizedSubtask;
+  });
+
+  for (const subtask of subtasks) {
+    const parentTask = taskIndex.get(subtask.taskId);
+    if (parentTask) {
+      parentTask.subtasks.push(subtask);
+    }
+  }
+
+  const dependencies = rawDependencies.map((dependency) => ({
+    id: getId(dependency),
+    sourceId: String(dependency.sourceId ?? ""),
+    sourceKind: dependency.sourceKind === "subtask" ? "subtask" : "task",
+    dependsOnId: String(dependency.dependsOnId ?? ""),
+    dependsOnKind: dependency.dependsOnKind === "subtask" ? "subtask" : "task",
+  }));
+
+  const lookupNode = (kind, id) => {
+    if (kind === "subtask") {
+      return subtaskIndex.get(id) ?? null;
+    }
+    return taskIndex.get(id) ?? null;
+  };
+
+  for (const dependency of dependencies) {
+    const source = lookupNode(dependency.sourceKind, dependency.sourceId);
+    const target = lookupNode(dependency.dependsOnKind, dependency.dependsOnId);
+    if (source) {
+      source.blockedBy.push(dependency.dependsOnId);
+      source.dependencyIds.push(dependency.id);
+    }
+    if (target) {
+      target.blocks.push(dependency.sourceId);
+      target.dependentIds.push(dependency.id);
+    }
+  }
+
+  const epics = rawEpics.map((epic) => {
+    const epicId = getId(epic);
+    const epicTasks = tasks.filter((task) => task.epicId === epicId);
+    const normalizedEpic = {
+      id: epicId,
+      title: String(epic.title ?? "Untitled epic"),
+      description: String(epic.description ?? "").replace(/\\n/g, "\n"),
+      status: String(epic.status ?? "todo"),
+      createdAt: Number(epic.createdAt ?? Date.now()),
+      updatedAt: Number(epic.updatedAt ?? epic.createdAt ?? Date.now()),
+      taskIds: epicTasks.map((task) => task.id),
+      counts: deriveCounts(epicTasks),
+      searchText: "",
+    };
+
+    normalizedEpic.searchText = [normalizedEpic.title, normalizedEpic.description, ...epicTasks.map((task) => task.title)].join(" ").toLowerCase();
+    return normalizedEpic;
+  });
+
+  for (const subtask of subtasks) {
+    subtask.searchText = [subtask.title, subtask.description, subtask.status].join(" ").toLowerCase();
+  }
+
+  for (const task of tasks) {
+    task.searchText = [
+      task.title,
+      task.description,
+      task.status,
+      ...task.subtasks.map((subtask) => `${subtask.title} ${subtask.description} ${subtask.status}`),
+    ].join(" ").toLowerCase();
+  }
+
+  const taskSearchTextByEpicId = new Map();
+  for (const task of tasks) {
+    if (!task.epicId) {
+      continue;
+    }
+
+    const entries = taskSearchTextByEpicId.get(task.epicId) ?? [];
+    entries.push(task.searchText);
+    taskSearchTextByEpicId.set(task.epicId, entries);
+  }
+
+  return {
+    generatedAt: rawSnapshot?.generatedAt ?? null,
+    epics: epics.map((epic) => ({
+      ...epic,
+      searchText: [
+        epic.title,
+        epic.description,
+        ...(taskSearchTextByEpicId.get(epic.id) ?? []),
+      ].join(" ").toLowerCase(),
+    })),
+    tasks,
+    subtasks,
+    dependencies,
+  };
+}
+
+const dateFormatter = new Intl.DateTimeFormat(undefined, { dateStyle: "medium", timeStyle: "short" });
+
+/**
+ * Format a timestamp into a human-readable date string.
+ * Uses a cached Intl.DateTimeFormat instance for performance.
+ * @param {number|null|undefined} timestamp
+ * @returns {string}
+ */
+export function formatDate(timestamp) {
+  if (!timestamp) return "Unknown";
+  return dateFormatter.format(timestamp);
+}
+
+/**
+ * Escape HTML special characters to prevent XSS.
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}