@devfellowship/components 3.2.3 → 3.3.0

package/dist/index.js

@@ -8305,6 +8305,417 @@ function PublishDrawer({
   ) });
 }
 
+// src/components/organisms/roadmap/contract.ts
+import { z } from "zod";
+var ROADMAP_COLUMNS = ["left", "center", "right"];
+var ROADMAP_TONES = [
+  "primary",
+  "secondary",
+  "accent",
+  "muted",
+  "success",
+  "info",
+  "danger",
+  "neutral"
+];
+var ROADMAP_NODE_KINDS = [
+  "topic",
+  "subtopic",
+  "label",
+  "title",
+  "paragraph",
+  "button",
+  "legend"
+];
+var ROADMAP_NODE_STATES = ["todo", "done", "learning", "skipped", "locked"];
+var ROADMAP_EDGE_STYLES = ["solid", "dashed", "dotted"];
+var ROADMAP_EDGE_ROUTES = ["auto", "straight", "elbow", "curve"];
+var ROADMAP_ARROWS = ["none", "end", "both"];
+var ROADMAP_LEGEND_PLACEMENTS = ["top", "bottom", "inline"];
+var DEFAULT_NODE_SPAN = 1;
+var DEFAULT_EDGE_STYLE = "dashed";
+var DEFAULT_EDGE_ROUTE = "auto";
+var DEFAULT_EDGE_ARROW = "none";
+var DEFAULT_GROUP_TONE = "neutral";
+var DEFAULT_LEGEND_PLACEMENT = "top";
+var DEFAULT_NODE_STATE = "todo";
+var NODE_KIND_DEFAULT_TONE = {
+  topic: "primary",
+  subtopic: "secondary",
+  button: "primary",
+  label: "neutral",
+  title: "neutral",
+  paragraph: "neutral",
+  legend: "neutral"
+};
+var resolveNodeSpan = (node) => node.span ?? DEFAULT_NODE_SPAN;
+var resolveNodeTone = (node) => node.tone ?? NODE_KIND_DEFAULT_TONE[node.kind];
+var resolveEdgeStyle = (edge) => edge.style ?? DEFAULT_EDGE_STYLE;
+var resolveEdgeRoute = (edge) => edge.route ?? DEFAULT_EDGE_ROUTE;
+var resolveEdgeArrow = (edge) => edge.arrow ?? DEFAULT_EDGE_ARROW;
+var resolveGroupTone = (group) => group.tone ?? DEFAULT_GROUP_TONE;
+var resolveGroupColumns = (group) => group.columns && group.columns.length > 0 ? group.columns : [...ROADMAP_COLUMNS];
+var resolveLegendPlacement = (legend) => legend.placement ?? DEFAULT_LEGEND_PLACEMENT;
+var resolveNodeState = (node, overlay) => overlay?.nodes[node.id] ?? node.state ?? DEFAULT_NODE_STATE;
+var ROADMAP_NODE_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+var ROADMAP_EDGE_LABEL_MAX = 40;
+var ROADMAP_LABEL_MAX = 200;
+var columnSchema = z.enum(ROADMAP_COLUMNS);
+var toneSchema = z.enum(ROADMAP_TONES);
+var idSchema = z.string().regex(ROADMAP_NODE_ID_PATTERN, "must match /^[A-Za-z0-9_-]{1,64}$/");
+var metaSchema = z.record(z.unknown());
+var roadmapIconSchema = z.object({
+  name: z.string().min(1).max(64),
+  side: z.enum(["left", "right"]),
+  tone: toneSchema.optional()
+}).strict();
+var roadmapActionSchema = z.object({
+  label: z.string().min(1).max(80),
+  href: z.string().min(1).optional(),
+  actionId: z.string().min(1).optional(),
+  tone: toneSchema.optional()
+}).strict().superRefine((action, ctx) => {
+  const given = [action.href, action.actionId].filter((v) => v !== void 0).length;
+  if (given !== 1) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["href"],
+      message: "an action needs exactly one of `href` or `actionId`"
+    });
+  }
+});
+var roadmapLinkSchema = z.object({ label: z.string().min(1).max(120), href: z.string().min(1) }).strict();
+var roadmapNodeStateSchema = z.enum(ROADMAP_NODE_STATES);
+var roadmapNodeSchema = z.object({
+  id: idSchema,
+  column: columnSchema,
+  order: z.number().int().min(0),
+  span: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional(),
+  kind: z.enum(ROADMAP_NODE_KINDS),
+  label: z.string().min(1).max(ROADMAP_LABEL_MAX),
+  description: z.string().max(2e3).optional(),
+  tone: toneSchema.optional(),
+  icon: roadmapIconSchema.optional(),
+  badge: z.string().min(1).optional(),
+  state: roadmapNodeStateSchema.optional(),
+  action: roadmapActionSchema.optional(),
+  href: z.string().min(1).optional(),
+  links: z.array(roadmapLinkSchema).optional(),
+  meta: metaSchema.optional()
+}).strict();
+var roadmapEdgeSchema = z.object({
+  id: idSchema,
+  source: z.string().min(1),
+  target: z.string().min(1),
+  style: z.enum(ROADMAP_EDGE_STYLES).optional(),
+  label: z.string().min(1).max(ROADMAP_EDGE_LABEL_MAX).optional(),
+  route: z.enum(ROADMAP_EDGE_ROUTES).optional(),
+  arrow: z.enum(ROADMAP_ARROWS).optional(),
+  tone: toneSchema.optional()
+}).strict();
+var roadmapGroupSchema = z.object({
+  id: idSchema,
+  title: z.string().min(1).max(ROADMAP_LABEL_MAX).optional(),
+  tone: toneSchema.optional(),
+  from: z.number().int().min(0),
+  to: z.number().int().min(0),
+  columns: z.array(columnSchema).min(1).max(3).optional(),
+  description: z.string().max(2e3).optional()
+}).strict();
+var roadmapLegendEntrySchema = z.object({
+  id: idSchema,
+  label: z.string().min(1).max(ROADMAP_LABEL_MAX),
+  tone: toneSchema,
+  icon: z.string().min(1).max(64).optional()
+}).strict();
+var roadmapLegendSchema = z.object({
+  entries: z.array(roadmapLegendEntrySchema).min(1),
+  placement: z.enum(ROADMAP_LEGEND_PLACEMENTS).optional()
+}).strict();
+function columnsCovered(node) {
+  const span = node.span ?? DEFAULT_NODE_SPAN;
+  if (span === 3) return [...ROADMAP_COLUMNS];
+  const start = ROADMAP_COLUMNS.indexOf(node.column);
+  return ROADMAP_COLUMNS.slice(start, start + span);
+}
+var roadmapDocumentBaseSchema = z.object({
+  version: z.literal("roadmap/v1"),
+  title: z.string().min(1).max(ROADMAP_LABEL_MAX).optional(),
+  direction: z.literal("down"),
+  columns: z.literal(3),
+  nodes: z.array(roadmapNodeSchema),
+  edges: z.array(roadmapEdgeSchema),
+  groups: z.array(roadmapGroupSchema),
+  legend: roadmapLegendSchema.optional(),
+  meta: metaSchema.optional()
+}).strict();
+var roadmapDocumentSchema = roadmapDocumentBaseSchema.superRefine((doc, ctx) => {
+  const nodeIndexById = /* @__PURE__ */ new Map();
+  doc.nodes.forEach((node, i) => {
+    if (nodeIndexById.has(node.id)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["nodes", i, "id"],
+        message: `duplicate node id "${node.id}" (first seen at nodes[${nodeIndexById.get(node.id)}])`
+      });
+      return;
+    }
+    nodeIndexById.set(node.id, i);
+  });
+  const cellOwner = /* @__PURE__ */ new Map();
+  doc.nodes.forEach((node, i) => {
+    const span = node.span ?? DEFAULT_NODE_SPAN;
+    if (span === 2 && node.column === "right") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["nodes", i, "span"],
+        message: 'a `span: 2` node at column "right" runs past the last track'
+      });
+      return;
+    }
+    for (const column of columnsCovered(node)) {
+      const key = `${column}:${node.order}`;
+      const owner = cellOwner.get(key);
+      if (owner !== void 0) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["nodes", i, "order"],
+          message: `cell (${column}, ${node.order}) is already taken by nodes[${owner}] ("${doc.nodes[owner].id}")`
+        });
+        continue;
+      }
+      cellOwner.set(key, i);
+    }
+  });
+  const edgeIds = /* @__PURE__ */ new Set();
+  doc.edges.forEach((edge, i) => {
+    if (edgeIds.has(edge.id)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["edges", i, "id"],
+        message: `duplicate edge id "${edge.id}"`
+      });
+    }
+    edgeIds.add(edge.id);
+    if (!nodeIndexById.has(edge.source)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["edges", i, "source"],
+        message: `edge source "${edge.source}" is not a node in this document`
+      });
+    }
+    if (!nodeIndexById.has(edge.target)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["edges", i, "target"],
+        message: `edge target "${edge.target}" is not a node in this document`
+      });
+    }
+    if (edge.source === edge.target) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["edges", i, "target"],
+        message: `edge "${edge.id}" is a self-loop`
+      });
+    }
+  });
+  const groupIds = /* @__PURE__ */ new Set();
+  doc.groups.forEach((group, i) => {
+    if (groupIds.has(group.id)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["groups", i, "id"],
+        message: `duplicate group id "${group.id}"`
+      });
+    }
+    groupIds.add(group.id);
+    if (group.from > group.to) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["groups", i, "to"],
+        message: `group "${group.id}" has from (${group.from}) greater than to (${group.to})`
+      });
+    }
+  });
+  for (let i = 0; i < doc.groups.length; i += 1) {
+    const a = doc.groups[i];
+    if (a.from > a.to) continue;
+    const aColumns = new Set(resolveGroupColumns(a));
+    for (let j = i + 1; j < doc.groups.length; j += 1) {
+      const b = doc.groups[j];
+      if (b.from > b.to) continue;
+      const rowsOverlap = a.from <= b.to && b.from <= a.to;
+      if (!rowsOverlap) continue;
+      const shared = resolveGroupColumns(b).filter((c) => aColumns.has(c));
+      if (shared.length === 0) continue;
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["groups", j, "from"],
+        message: `group "${b.id}" overlaps rows ${a.from}..${a.to} of group "${a.id}" on column(s) ${shared.join(", ")}`
+      });
+    }
+  }
+  const legendIds = /* @__PURE__ */ new Set();
+  doc.legend?.entries.forEach((entry, i) => {
+    if (legendIds.has(entry.id)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["legend", "entries", i, "id"],
+        message: `duplicate legend entry id "${entry.id}"`
+      });
+    }
+    legendIds.add(entry.id);
+  });
+  doc.nodes.forEach((node, i) => {
+    if (node.badge === void 0) return;
+    if (!legendIds.has(node.badge)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["nodes", i, "badge"],
+        message: `badge "${node.badge}" is not a legend entry of this document`
+      });
+    }
+  });
+});
+var roadmapStateOverlaySchema = z.object({
+  version: z.literal("roadmap-state/v1"),
+  nodes: z.record(roadmapNodeStateSchema)
+}).strict();
+var roadmapStateSchema = roadmapStateOverlaySchema;
+function parseRoadmapDocument(input) {
+  return roadmapDocumentSchema.parse(input);
+}
+function safeParseRoadmapDocument(input) {
+  return roadmapDocumentSchema.safeParse(input);
+}
+function parseRoadmapStateOverlay(input) {
+  return roadmapStateOverlaySchema.parse(input);
+}
+function safeParseRoadmapStateOverlay(input) {
+  return roadmapStateOverlaySchema.safeParse(input);
+}
+
+// src/components/organisms/roadmap/layout.ts
+function columnIndex(column) {
+  return ROADMAP_COLUMNS.indexOf(column);
+}
+function gridColumnFor(node) {
+  const span = resolveNodeSpan(node);
+  if (span === 3) return { start: 1, span: 3 };
+  return { start: columnIndex(node.column) + 1, span };
+}
+function rowsOf(doc) {
+  const rows = /* @__PURE__ */ new Set();
+  for (const node of doc.nodes) rows.add(node.order);
+  return [...rows].sort((a, b) => a - b);
+}
+function maxRowOf(doc) {
+  return doc.nodes.reduce((max, node) => Math.max(max, node.order), -1);
+}
+function nodesByRow(doc) {
+  const byRow = /* @__PURE__ */ new Map();
+  for (const node of doc.nodes) {
+    const bucket = byRow.get(node.order);
+    if (bucket) bucket.push(node);
+    else byRow.set(node.order, [node]);
+  }
+  for (const bucket of byRow.values()) {
+    bucket.sort((a, b) => {
+      const byColumn = columnIndex(a.column) - columnIndex(b.column);
+      return byColumn !== 0 ? byColumn : a.id.localeCompare(b.id);
+    });
+  }
+  return byRow;
+}
+function columnsUsed(doc) {
+  const used = /* @__PURE__ */ new Set();
+  for (const node of doc.nodes) for (const column of columnsCovered(node)) used.add(column);
+  return ROADMAP_COLUMNS.filter((column) => used.has(column));
+}
+function groupRanges(doc) {
+  return doc.groups.map((group) => {
+    const columns = resolveGroupColumns(group);
+    const indices = columns.map(columnIndex).sort((a, b) => a - b);
+    const start = indices[0];
+    const end = indices[indices.length - 1];
+    return {
+      id: group.id,
+      from: group.from,
+      to: group.to,
+      columns: ROADMAP_COLUMNS.filter((c) => columns.includes(c)),
+      row: { start: group.from + 1, span: group.to - group.from + 1 },
+      column: { start: start + 1, span: end - start + 1 },
+      fragmented: end - start + 1 !== indices.length
+    };
+  });
+}
+function groupColumnRuns(group) {
+  const indices = resolveGroupColumns(group).map(columnIndex).sort((a, b) => a - b);
+  const runs = [];
+  for (const index of indices) {
+    const last = runs[runs.length - 1];
+    if (last && last.start + last.span === index + 1) last.span += 1;
+    else runs.push({ start: index + 1, span: 1 });
+  }
+  return runs;
+}
+function validateNoOverlap(doc) {
+  const overlaps = [];
+  const nodeCell = /* @__PURE__ */ new Map();
+  for (const node of doc.nodes) {
+    for (const column of columnsCovered(node)) {
+      const key = `${column}:${node.order}`;
+      const owner = nodeCell.get(key);
+      if (owner !== void 0) {
+        overlaps.push({ kind: "node", column, row: node.order, ids: [owner, node.id] });
+        continue;
+      }
+      nodeCell.set(key, node.id);
+    }
+  }
+  const groupCell = /* @__PURE__ */ new Map();
+  for (const group of doc.groups) {
+    if (group.from > group.to) continue;
+    for (const column of resolveGroupColumns(group)) {
+      for (let row = group.from; row <= group.to; row += 1) {
+        const key = `${column}:${row}`;
+        const owner = groupCell.get(key);
+        if (owner !== void 0) {
+          if (owner !== group.id) {
+            overlaps.push({ kind: "group", column, row, ids: [owner, group.id] });
+          }
+          continue;
+        }
+        groupCell.set(key, group.id);
+      }
+    }
+  }
+  return overlaps;
+}
+function placeNodes(doc) {
+  const byRow = nodesByRow(doc);
+  const rows = rowsOf(doc);
+  const placements = [];
+  for (const row of rows) {
+    for (const node of byRow.get(row) ?? []) {
+      placements.push({
+        node,
+        row: { start: node.order + 1, span: 1 },
+        column: gridColumnFor(node)
+      });
+    }
+  }
+  return { placements, rows, rowCount: maxRowOf(doc) + 1 };
+}
+function firstFreeRow(taken, columns, from) {
+  let row = from;
+  for (let guard = 0; guard < 1e5; guard += 1) {
+    if (columns.every((column) => !taken.has(`${column}:${row}`))) return row;
+    row += 1;
+  }
+  return row;
+}
+
 // src/hooks/use-iframe-auth.ts
 import { useContext as useContext9 } from "react";
 function useIframeAuth() {
@@ -8445,7 +8856,14 @@ export {
   ContextMenuSubContent,
   ContextMenuSubTrigger,
   ContextMenuTrigger,
+  DEFAULT_EDGE_ARROW,
+  DEFAULT_EDGE_ROUTE,
+  DEFAULT_EDGE_STYLE,
+  DEFAULT_GROUP_TONE,
+  DEFAULT_LEGEND_PLACEMENT,
   DEFAULT_NAME_COL_WIDTH,
+  DEFAULT_NODE_SPAN,
+  DEFAULT_NODE_STATE,
   DflRemote,
   Dialog,
   DialogClose,
@@ -8523,6 +8941,7 @@ export {
   MenubarSubContent,
   MenubarSubTrigger,
   MenubarTrigger,
+  NODE_KIND_DEFAULT_TONE,
   NavigationMenu,
   NavigationMenuContent,
   NavigationMenuIndicator,
@@ -8546,6 +8965,17 @@ export {
   Progress,
   ProtectedRoute,
   PublishDrawer,
+  ROADMAP_ARROWS,
+  ROADMAP_COLUMNS,
+  ROADMAP_EDGE_LABEL_MAX,
+  ROADMAP_EDGE_ROUTES,
+  ROADMAP_EDGE_STYLES,
+  ROADMAP_LABEL_MAX,
+  ROADMAP_LEGEND_PLACEMENTS,
+  ROADMAP_NODE_ID_PATTERN,
+  ROADMAP_NODE_KINDS,
+  ROADMAP_NODE_STATES,
+  ROADMAP_TONES,
   RadioGroup4 as RadioGroup,
   RadioGroupItem,
   RadioGroupRow,
@@ -8639,19 +9069,55 @@ export {
   buttonVariants,
   clampPct,
   cn,
+  columnIndex,
+  columnsCovered,
+  columnsUsed,
   filterPublishableAccounts,
+  firstFreeRow,
   getInitials,
+  gridColumnFor,
+  groupColumnRuns,
+  groupRanges,
   iconButtonVariants,
   isAllowedOrigin,
   kbdVariants,
   labelVariants,
+  maxRowOf,
   memberHueIndex,
   memberHueVar,
   navigationMenuTriggerStyle,
+  nodesByRow,
+  parseRoadmapDocument,
+  parseRoadmapStateOverlay,
   parseTags,
+  placeNodes,
+  resolveEdgeArrow,
+  resolveEdgeRoute,
+  resolveEdgeStyle,
+  resolveGroupColumns,
+  resolveGroupTone,
+  resolveLegendPlacement,
   resolveNameColWidth,
+  resolveNodeSpan,
+  resolveNodeState,
+  resolveNodeTone,
   resolveWeekCount,
   resolveWeekLabels,
+  roadmapActionSchema,
+  roadmapDocumentSchema,
+  roadmapEdgeSchema,
+  roadmapGroupSchema,
+  roadmapIconSchema,
+  roadmapLegendEntrySchema,
+  roadmapLegendSchema,
+  roadmapLinkSchema,
+  roadmapNodeSchema,
+  roadmapNodeStateSchema,
+  roadmapStateOverlaySchema,
+  roadmapStateSchema,
+  rowsOf,
+  safeParseRoadmapDocument,
+  safeParseRoadmapStateOverlay,
   stageProgress,
   toast,
   toggleVariants,
@@ -8665,5 +9131,6 @@ export {
   useSession,
   useSidebar,
   useToast,
+  validateNoOverlap,
   validatePublishForm
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devfellowship/components",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "description": "DFL Design System — UI components, hooks, utils and providers",
   "type": "module",
   "sideEffects": [