@unofficialbox/box-open-elements 0.10.0 → 0.12.0

package/dist/patterns/versions/graph-arrows.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Which ends of a graph edge carry an arrowhead.
+ *
+ * Shared by `box-version-graph` and `box-lineage-graph`, which draw the same
+ * edge geometry from the same layout and should not disagree about what an
+ * arrow means. Lives here rather than in either component because the lineage
+ * graph already depends on this directory for `computeVersionGraphLayout`, and
+ * the reverse dependency would be a cycle.
+ */
+export type GraphArrows = "none" | "start" | "end" | "both";
+/**
+ * Narrow an author-supplied value, falling back to `end`.
+ *
+ * `end` is the default because these are directed graphs: the layout builds
+ * every edge as parent → child, so a single head on the child is the reading
+ * that matches the data. A typo should not silently turn the direction off.
+ */
+export declare const resolveGraphArrows: (value: string | null | undefined) => GraphArrows;
+/** Whether the head at the child end is drawn. */
+export declare const hasEndArrow: (arrows: GraphArrows) => boolean;
+/** Whether the head at the parent end is drawn. */
+export declare const hasStartArrow: (arrows: GraphArrows) => boolean;

package/dist/patterns/versions/graph-arrows.js

@@ -0,0 +1,13 @@
+const GRAPH_ARROWS = new Set(["none", "start", "end", "both"]);
+/**
+ * Narrow an author-supplied value, falling back to `end`.
+ *
+ * `end` is the default because these are directed graphs: the layout builds
+ * every edge as parent → child, so a single head on the child is the reading
+ * that matches the data. A typo should not silently turn the direction off.
+ */
+export const resolveGraphArrows = (value) => GRAPH_ARROWS.has(value) ? value : "end";
+/** Whether the head at the child end is drawn. */
+export const hasEndArrow = (arrows) => arrows === "end" || arrows === "both";
+/** Whether the head at the parent end is drawn. */
+export const hasStartArrow = (arrows) => arrows === "start" || arrows === "both";

package/dist/patterns/versions/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./types.js";
 export * from "./graph-layout.js";
+export * from "./graph-arrows.js";
 export * from "./version-list.js";
 export * from "./version-graph.js";

package/dist/patterns/versions/index.js

@@ -2,6 +2,7 @@
 export * from "./types.js";
 // Pure git-network layout engine (shared with future lineage graphs)
 export * from "./graph-layout.js";
+export * from "./graph-arrows.js";
 // Accessible core contract
 export * from "./version-list.js";
 // Git-style visualization layer

package/dist/patterns/versions/version-graph.d.ts

@@ -1,3 +1,4 @@
+import type { GraphArrows } from "./graph-arrows.js";
 import type { VersionNode } from "./types.js";
 import { BaseElement } from "../../core/index.js";
 /**
@@ -12,6 +13,12 @@ import { BaseElement } from "../../core/index.js";
 export declare class VersionGraph extends BaseElement {
     static readonly tagName: string;
     static get observedAttributes(): string[];
+    /**
+     * Which ends of each edge carry an arrowhead. Defaults to `end`, the head on
+     * the child, because the layout builds edges parent → child.
+     */
+    get arrows(): GraphArrows;
+    set arrows(value: GraphArrows);
     private versionsValue;
     private compareIds;
     private rovingId;

package/dist/patterns/versions/version-graph.js

@@ -1,4 +1,5 @@
 import { computeVersionGraphLayout, orderVersionsForDisplay } from "./graph-layout.js";
+import { hasEndArrow, hasStartArrow, resolveGraphArrows } from "./graph-arrows.js";
 import { escapeHtml, STATUS_LABELS } from "./shared.js";
 import { isVersionNodeRecord, resolveVersionKind, resolveVersionStatus } from "./types.js";
 import { formatItemDate } from "../content-explorer/adapters/item-summary.js";
@@ -8,6 +9,14 @@ const DEFAULT_TAG_NAME = "box-version-graph";
 const LANE_WIDTH = 26;
 const ROW_HEIGHT = 46;
 const EDGE_PAD = 8;
+/**
+ * How far short of a node's centre an edge stops.
+ *
+ * The arrowhead marks the path's end vertex, so an edge running to the centre
+ * would bury its head under the node disc. The largest node here is ~1.05rem
+ * across, so backing off 9px leaves the head just clear of the biggest one.
+ */
+const NODE_EDGE_OFFSET = 9;
 const elementStyles = `
         [hidden] {
           display: none !important;
@@ -48,6 +57,13 @@ const elementStyles = `
           pointer-events: none;
         }
 
+        /* The arrowhead. Same colour as the stroke it terminates, stated
+           rather than inherited: context-stroke is not supported everywhere. */
+        [part="edge-arrow"] {
+          fill: color-mix(in srgb, var(--boe-token-text-text-secondary, #6f6f6f) 55%, transparent);
+          stroke: none;
+        }
+
         [part="edge"] {
           fill: none;
           stroke: color-mix(in srgb, var(--boe-token-text-text-secondary, #6f6f6f) 55%, transparent);
@@ -187,7 +203,17 @@ const elementStyles = `
 export class VersionGraph extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["heading", "versions"];
+        return ["arrows", "heading", "versions"];
+    }
+    /**
+     * Which ends of each edge carry an arrowhead. Defaults to `end`, the head on
+     * the child, because the layout builds edges parent → child.
+     */
+    get arrows() {
+        return resolveGraphArrows(this.getAttribute("arrows"));
+    }
+    set arrows(value) {
+        this.setAttribute("arrows", value);
     }
     versionsValue = [];
     compareIds = [];
@@ -359,16 +385,38 @@ export class VersionGraph extends BaseElement {
         const graphHeight = layout.rowCount * ROW_HEIGHT;
         const centerX = (lane) => EDGE_PAD + lane * LANE_WIDTH + LANE_WIDTH / 2;
         const centerY = (row) => row * ROW_HEIGHT + ROW_HEIGHT / 2;
+        const arrows = this.arrows;
+        const startMarker = hasStartArrow(arrows) ? ` marker-start="url(#boe-graph-arrow)"` : "";
+        const endMarker = hasEndArrow(arrows) ? ` marker-end="url(#boe-graph-arrow)"` : "";
         const edgePaths = layout.edges
             .map(edge => {
             const x1 = centerX(edge.fromLane);
             const y1 = centerY(edge.fromRow);
             const x2 = centerX(edge.toLane);
             const y2 = centerY(edge.toRow);
-            const d = edge.fromLane === edge.toLane
-                ? `M ${x1} ${y1} L ${x2} ${y2}`
-                : `M ${x1} ${y1} C ${x1} ${y1 - ROW_HEIGHT / 2}, ${x2} ${y2 + ROW_HEIGHT / 2}, ${x2} ${y2}`;
-            return `<path part="edge" data-from="${escapeHtml(edge.fromId)}" data-to="${escapeHtml(edge.toId)}" d="${d}"></path>`;
+            // One curve rule for every edge, rather than a straight line for
+            // same-lane edges and a cubic for lane changes: two rules made the
+            // graph read as two different diagrams. A cubic whose ends share an x
+            // degenerates to a straight vertical on its own, so same-lane edges
+            // still render straight without being a special case.
+            //
+            // Control points are pulled *along* the direction of travel — half the
+            // vertical distance each — so the bend always leaves the parent
+            // downward and enters the child from above. The previous version
+            // offset them by a fixed half-row in the wrong direction (up from the
+            // start, down from the end on a downward edge), so an edge spanning
+            // one row bowed backwards into an S while a longer one looked almost
+            // straight.
+            // Stop at each node's edge rather than its centre. A marker sits on
+            // the path's end vertex, so a vertex inside the node disc buries it —
+            // and an edge that starts and ends at the rim reads as connecting two
+            // nodes rather than as passing through them, which is what React Flow
+            // gets from anchoring edges to handles.
+            const yStart = y1 + Math.sign(y2 - y1) * NODE_EDGE_OFFSET;
+            const yEnd = y2 + Math.sign(y1 - y2) * NODE_EDGE_OFFSET;
+            const dy = (yEnd - yStart) / 2;
+            const d = `M ${x1} ${yStart} C ${x1} ${yStart + dy}, ${x2} ${yEnd - dy}, ${x2} ${yEnd}`;
+            return `<path part="edge" data-from="${escapeHtml(edge.fromId)}" data-to="${escapeHtml(edge.toId)}" d="${d}"${startMarker}${endMarker}></path>`;
         })
             .join("");
         const rovingId = this.rovingId && byId.has(this.rovingId)
@@ -416,7 +464,7 @@ export class VersionGraph extends BaseElement {
         ${layout.placements.length > 0
             ? `
               <div part="graph">
-                <svg part="edges" width="${String(graphWidth)}" height="${String(graphHeight)}" viewBox="0 0 ${String(graphWidth)} ${String(graphHeight)}" aria-hidden="true">${edgePaths}</svg>
+                <svg part="edges" width="${String(graphWidth)}" height="${String(graphHeight)}" viewBox="0 0 ${String(graphWidth)} ${String(graphHeight)}" aria-hidden="true"><defs><marker id="boe-graph-arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="4" markerHeight="4" orient="auto-start-reverse"><path part="edge-arrow" d="M 0 0 L 8 4 L 0 8 z"></path></marker></defs>${edgePaths}</svg>
                 <ol part="rows" role="list">${rows}</ol>
               </div>
             `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unofficialbox/box-open-elements",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Box Open Elements: an open, framework-agnostic design system and web component library for Box-style experiences",
   "license": "MIT",
   "homepage": "https://unofficialbox.github.io/box-open-elements",

package/dist/components/feedback/stage-path.d.ts

@@ -1,44 +0,0 @@
-import { BaseElement } from "../../core/index.js";
-/** One point in a record's lifecycle. */
-export interface StagePathStage {
-    id: string;
-    label: string;
-    /** Optional detail shown under the label on the current stage. */
-    description?: string;
-}
-export type StageState = "complete" | "current" | "upcoming";
-/** Attribute payloads are author input — validate every record. */
-export declare const isStagePathStageRecord: (value: unknown) => value is StagePathStage;
-/** State of each stage relative to the current one. */
-export declare const resolveStageStates: (stages: readonly StagePathStage[], currentId: string) => StageState[];
-/**
- * Horizontal chevron lifecycle tracker for record headers — Draft → In
- * Review → Approved → Executed.
- *
- * Distinct from `box-progress-steps`, which is a vertical setup rail for a
- * task the reader is working through: this states where a *record* sits in
- * its lifecycle, is read-only, and belongs in a header rather than a form.
- *
- * Rendered as an ordered list with the current stage marked `aria-current`,
- * so the sequence and the position are both available without relying on the
- * chevron geometry — which is decoration, and collapses on narrow viewports.
- */
-export declare class StagePath extends BaseElement {
-    static readonly tagName: string;
-    static get observedAttributes(): string[];
-    private pathEl;
-    private stagesRaw;
-    private stagesCache;
-    get label(): string;
-    set label(value: string);
-    /** Id of the stage the record is at. An unknown id leaves every stage upcoming. */
-    get current(): string;
-    set current(value: string);
-    get stages(): StagePathStage[];
-    set stages(value: StagePathStage[]);
-    /** State of each stage, in order. */
-    get states(): StageState[];
-    protected renderTemplate(): void;
-    protected setupListeners(): void;
-    protected update(): void;
-}

package/dist/components/feedback/stage-path.js

@@ -1,235 +0,0 @@
-import { BaseElement } from "../../core/index.js";
-import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
-const DEFAULT_TAG_NAME = "box-stage-path";
-const escapeHtml = (value) => value
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&#39;");
-/** Attribute payloads are author input — validate every record. */
-export const isStagePathStageRecord = (value) => {
-    if (typeof value !== "object" || value === null) {
-        return false;
-    }
-    const stage = value;
-    return (typeof stage.id === "string" &&
-        stage.id.length > 0 &&
-        typeof stage.label === "string" &&
-        stage.label.length > 0);
-};
-/** State of each stage relative to the current one. */
-export const resolveStageStates = (stages, currentId) => {
-    const index = stages.findIndex(stage => stage.id === currentId);
-    // An unknown current id means nothing is complete — better than silently
-    // marking the whole path done because the host sent a stale value.
-    return stages.map((_, position) => index === -1
-        ? "upcoming"
-        : position < index
-            ? "complete"
-            : position === index
-                ? "current"
-                : "upcoming");
-};
-const elementStyles = `
-        :host {
-          display: block;
-        }
-
-        [part="path"] {
-          display: flex;
-          flex-wrap: wrap;
-          margin: 0;
-          padding: 0;
-          list-style: none;
-        }
-
-        [part="stage"] {
-          position: relative;
-          flex: 1 1 0;
-          min-inline-size: 6rem;
-          padding: 0.45rem 0.7rem 0.45rem 1.35rem;
-          background: var(--boe-token-surface-surface-hover, #f4f4f4);
-          color: var(--boe-token-text-text-secondary, #6f6f6f);
-          font-size: 0.82rem;
-          transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
-        }
-
-        [part="stage"]:first-child {
-          padding-inline-start: 0.8rem;
-          border-start-start-radius: 999px;
-          border-end-start-radius: 999px;
-        }
-
-        [part="stage"]:last-child {
-          border-start-end-radius: 999px;
-          border-end-end-radius: 999px;
-        }
-
-        /* The chevron: a notch cut from the following stage plus an arrow on
-           this one, so the path reads as a directed sequence rather than a row
-           of pills. Drawn with clip-path so no extra elements are needed. */
-        [part="stage"]:not(:last-child) {
-          clip-path: polygon(0 0, calc(100% - 0.7rem) 0, 100% 50%, calc(100% - 0.7rem) 100%, 0 100%, 0.7rem 50%);
-          margin-inline-end: -0.55rem;
-        }
-
-        [part="stage"]:first-child:not(:last-child) {
-          clip-path: polygon(0 0, calc(100% - 0.7rem) 0, 100% 50%, calc(100% - 0.7rem) 100%, 0 100%);
-        }
-
-        [part="stage"]:last-child:not(:first-child) {
-          clip-path: polygon(0 0, 100% 0, 100% 100%, 0 100%, 0.7rem 50%);
-        }
-
-        [part="stage"][data-state="complete"] {
-          background: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26a27b) 18%, transparent);
-          color: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26a27b) 72%, black 28%);
-        }
-
-        [part="stage"][data-state="current"] {
-          background: var(--boe-token-surface-surface-brand, #0061d5);
-          color: var(--boe-token-text-text-on-brand, #ffffff);
-          font-weight: 700;
-        }
-
-        [part="stage-label"] {
-          display: block;
-        }
-
-        [part="stage-description"] {
-          display: block;
-          margin-block-start: 0.1rem;
-          font-size: 0.72rem;
-          font-weight: 400;
-          opacity: 0.85;
-        }
-
-        [part="stage-marker"] {
-          margin-inline-end: 0.3rem;
-          font-weight: 700;
-        }
-
-        @media (prefers-reduced-motion: reduce) {
-          [part="stage"] {
-            transition: none;
-          }
-        }
-
-        @media (max-width: 34rem) {
-          /* Chevrons collapse below the width where they stop being legible;
-             the states still read from tone and the completed marker. */
-          [part="stage"],
-          [part="stage"]:first-child:not(:last-child),
-          [part="stage"]:last-child:not(:first-child) {
-            clip-path: none;
-            margin-inline-end: 0;
-            padding-inline-start: 0.8rem;
-            border-radius: 0;
-          }
-        }
-      `;
-/**
- * Horizontal chevron lifecycle tracker for record headers — Draft → In
- * Review → Approved → Executed.
- *
- * Distinct from `box-progress-steps`, which is a vertical setup rail for a
- * task the reader is working through: this states where a *record* sits in
- * its lifecycle, is read-only, and belongs in a header rather than a form.
- *
- * Rendered as an ordered list with the current stage marked `aria-current`,
- * so the sequence and the position are both available without relying on the
- * chevron geometry — which is decoration, and collapses on narrow viewports.
- */
-export class StagePath extends BaseElement {
-    static tagName = DEFAULT_TAG_NAME;
-    static get observedAttributes() {
-        return ["current", "label", "stages"];
-    }
-    pathEl;
-    stagesRaw = null;
-    stagesCache = [];
-    get label() {
-        return this.getAttribute("label") ?? "Lifecycle";
-    }
-    set label(value) {
-        this.setAttribute("label", value);
-    }
-    /** Id of the stage the record is at. An unknown id leaves every stage upcoming. */
-    get current() {
-        return this.getAttribute("current") ?? "";
-    }
-    set current(value) {
-        this.setAttribute("current", value);
-    }
-    get stages() {
-        const raw = this.getAttribute("stages");
-        if (!raw) {
-            return [];
-        }
-        if (raw !== this.stagesRaw) {
-            this.stagesRaw = raw;
-            try {
-                const parsed = JSON.parse(raw);
-                this.stagesCache =
-                    Array.isArray(parsed) && parsed.every(isStagePathStageRecord)
-                        ? parsed
-                        : [];
-            }
-            catch {
-                this.stagesCache = [];
-            }
-        }
-        return [...this.stagesCache];
-    }
-    set stages(value) {
-        if (value.length) {
-            this.setAttribute("stages", JSON.stringify(value));
-            return;
-        }
-        this.removeAttribute("stages");
-    }
-    /** State of each stage, in order. */
-    get states() {
-        return resolveStageStates(this.stages, this.current);
-    }
-    renderTemplate() {
-        if (!this.shadowRoot) {
-            return;
-        }
-        this.shadowRoot.innerHTML = `<style>${elementStyles}</style><ol part="path"></ol>`;
-        this.pathEl = this.shadowRoot.querySelector('[part="path"]');
-    }
-    setupListeners() {
-        // Read-only: a record's lifecycle position is not something a header edits.
-    }
-    update() {
-        if (!this.pathEl) {
-            return;
-        }
-        const stages = this.stages;
-        const states = resolveStageStates(stages, this.current);
-        this.pathEl.setAttribute("aria-label", this.label);
-        this.pathEl.innerHTML = stages
-            .map((stage, index) => {
-            const state = states[index];
-            // The completed marker is a second, non-colour signal for "done".
-            const marker = state === "complete" ? `<span part="stage-marker" aria-hidden="true">✓</span>` : "";
-            return `
-          <li
-            part="stage"
-            data-stage-id="${escapeHtml(stage.id)}"
-            data-state="${state}"
-            ${state === "current" ? 'aria-current="step"' : ""}
-          >
-            <span part="stage-label">${marker}${escapeHtml(stage.label)}</span>
-            ${state === "current" && stage.description
-                ? `<span part="stage-description">${escapeHtml(stage.description)}</span>`
-                : ""}
-          </li>
-        `;
-        })
-            .join("");
-    }
-}
-StagePath.register();

package/dist/entries/stage-path.d.ts

@@ -1 +0,0 @@
-export * from "../components/feedback/stage-path.js";

package/dist/entries/stage-path.js

@@ -1 +0,0 @@
-export * from "../components/feedback/stage-path.js";