@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/dist/patterns/signature/signature-ceremony.d.ts

@@ -0,0 +1,33 @@
+import type { CeremonyResolution, Signatory, SignatureMode } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * Party-oriented signing progress: who signs, in what order, and — the part
+ * that matters — who can act *right now*.
+ *
+ * The rules live in `resolveCeremony`, which is pure, so a host can drive its
+ * own surface or its reminder emails from the same function rather than
+ * reimplementing the ordering logic and drifting from what the UI shows.
+ *
+ * Read-only by design. Signing happens in the signature provider's own flow,
+ * so this states position rather than offering a button that would have to
+ * duplicate that flow's authority.
+ */
+export declare class SignatureCeremony extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private hostEl;
+    private signatoriesRaw;
+    private signatoriesCache;
+    get heading(): string;
+    set heading(value: string);
+    /** `sequential` (default) routes one party at a time; `parallel` sends to all. */
+    get mode(): SignatureMode;
+    set mode(value: SignatureMode);
+    get signatories(): Signatory[];
+    set signatories(value: Signatory[]);
+    /** The resolved ceremony — same object the render uses. */
+    get resolution(): CeremonyResolution;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

package/dist/patterns/signature/signature-ceremony.js

@@ -0,0 +1,317 @@
+import { formatCeremonySummary, isSignatoryRecord, resolveCeremony, } from "./types.js";
+import { formatUtcDay } from "../audit/types.js";
+import { BaseElement } from "../../core/index.js";
+import { boePanel } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-signature-ceremony";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+const initialsOf = (name) => name
+    .split(/\s+/)
+    .filter(Boolean)
+    .slice(0, 2)
+    .map(part => part[0].toUpperCase())
+    .join("");
+/**
+ * `formatUtcDay` takes a date-only string or a `Date`; handing it a full ISO
+ * timestamp makes it concatenate a second time component and fall back to
+ * echoing the raw input. Signing timestamps carry a time, so parse first.
+ * Returns an empty string for an unparseable value, so callers can fall back.
+ */
+const signedOnDay = (iso) => formatUtcDay(new Date(iso));
+const STATE_LABEL = {
+    signed: "Signed",
+    declined: "Declined",
+    awaiting: "Awaiting signature",
+    waiting: "Not yet their turn",
+};
+const elementStyles = `
+        :host {
+          display: block;
+        }
+
+        [part="card"] {
+          border: ${boePanel.border};
+          border-radius: ${boePanel.radius};
+          background: ${boePanel.background};
+          overflow: hidden;
+        }
+
+        [part="header"] {
+          display: flex;
+          align-items: baseline;
+          gap: 0.6rem;
+          padding: 0.8rem 1rem;
+          border-block-end: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+        }
+
+        [part="heading"] {
+          margin: 0;
+          font: inherit;
+          font-size: 0.95rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="summary"] {
+          margin-inline-start: auto;
+          font-size: 0.78rem;
+          font-weight: 600;
+          padding: 0.14rem 0.5rem;
+          border-radius: 999px;
+          border: 1px solid transparent;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          background: color-mix(in srgb, var(--boe-token-surface-surface-hover, #f4f4f4) 80%, transparent);
+        }
+
+        [part="summary"][data-status="completed"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26a27b) 14%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26a27b) 74%, black 26%);
+          border-color: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26a27b) 32%, transparent);
+        }
+
+        [part="summary"][data-status="declined"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 14%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 76%, black 24%);
+          border-color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 32%, transparent);
+        }
+
+        [part="parties"] {
+          margin: 0;
+          padding: 0;
+          list-style: none;
+        }
+
+        [part="party"] {
+          display: grid;
+          grid-template-columns: auto auto 1fr auto;
+          align-items: center;
+          gap: 0.7rem;
+          padding: 0.65rem 1rem;
+        }
+
+        [part="party"] + [part="party"] {
+          border-block-start: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 45%, transparent);
+        }
+
+        [part="order"] {
+          inline-size: 1.35rem;
+          block-size: 1.35rem;
+          display: grid;
+          place-items: center;
+          border-radius: 999px;
+          font-size: 0.7rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="party"][data-state="signed"] [part="order"] {
+          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) 74%, black 26%);
+        }
+
+        [part="party"][data-state="declined"] [part="order"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 16%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 76%, black 24%);
+        }
+
+        [part="party"][data-state="awaiting"] [part="order"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 16%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 80%, black 20%);
+        }
+
+        [part="avatar"] {
+          inline-size: 1.7rem;
+          block-size: 1.7rem;
+          display: grid;
+          place-items: center;
+          border-radius: 999px;
+          font-size: 0.68rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="identity"] {
+          min-inline-size: 0;
+        }
+
+        [part="name"] {
+          display: block;
+          font-size: 0.88rem;
+          color: var(--boe-token-text-text, #1f1e1b);
+          overflow-wrap: anywhere;
+        }
+
+        [part="role"] {
+          display: block;
+          font-size: 0.76rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="state"] {
+          text-align: end;
+          font-size: 0.76rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          white-space: nowrap;
+        }
+
+        [part="party"][data-state="awaiting"] [part="state"] {
+          font-weight: 700;
+          color: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 80%, black 20%);
+        }
+
+        [part="party"][data-state="declined"] [part="state"] {
+          font-weight: 700;
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 76%, black 24%);
+        }
+
+        [part="reason"] {
+          grid-column: 3 / -1;
+          font-size: 0.76rem;
+          font-style: italic;
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 70%, black 30%);
+        }
+
+        [part="empty"] {
+          padding: 1.2rem 1rem;
+          text-align: center;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+      `;
+/**
+ * Party-oriented signing progress: who signs, in what order, and — the part
+ * that matters — who can act *right now*.
+ *
+ * The rules live in `resolveCeremony`, which is pure, so a host can drive its
+ * own surface or its reminder emails from the same function rather than
+ * reimplementing the ordering logic and drifting from what the UI shows.
+ *
+ * Read-only by design. Signing happens in the signature provider's own flow,
+ * so this states position rather than offering a button that would have to
+ * duplicate that flow's authority.
+ */
+export class SignatureCeremony extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["heading", "mode", "signatories"];
+    }
+    hostEl;
+    signatoriesRaw = null;
+    signatoriesCache = [];
+    get heading() {
+        return this.getAttribute("heading") ?? "Signatures";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    /** `sequential` (default) routes one party at a time; `parallel` sends to all. */
+    get mode() {
+        return this.getAttribute("mode") === "parallel" ? "parallel" : "sequential";
+    }
+    set mode(value) {
+        this.setAttribute("mode", value);
+    }
+    get signatories() {
+        const raw = this.getAttribute("signatories");
+        if (!raw) {
+            return [...this.signatoriesCache];
+        }
+        if (raw !== this.signatoriesRaw) {
+            this.signatoriesRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.signatoriesCache =
+                    Array.isArray(parsed) && parsed.every(isSignatoryRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.signatoriesCache = [];
+            }
+        }
+        return [...this.signatoriesCache];
+    }
+    set signatories(value) {
+        if (value.length) {
+            this.setAttribute("signatories", JSON.stringify(value));
+            return;
+        }
+        // Clear the cache too: the no-attribute branch of the getter serves from
+        // it, and a stale cache would make an emptied roster un-clearable.
+        this.signatoriesCache = [];
+        this.signatoriesRaw = null;
+        this.removeAttribute("signatories");
+    }
+    /** The resolved ceremony — same object the render uses. */
+    get resolution() {
+        return resolveCeremony(this.signatories, this.mode);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `<style>${elementStyles}</style><div part="host"></div>`;
+        this.hostEl = this.shadowRoot.querySelector('[part="host"]');
+    }
+    setupListeners() {
+        // Read-only: signing is the provider's flow, not this component's.
+    }
+    update() {
+        if (!this.hostEl) {
+            return;
+        }
+        const resolution = this.resolution;
+        const rows = resolution.statuses
+            .map(entry => {
+            const { signatory, state, order } = entry;
+            // An unparseable timestamp falls back to the bare state rather than
+            // rendering "Signed " with nothing after it.
+            const signedDay = signatory.signedAt ? signedOnDay(signatory.signedAt) : "";
+            const declinedDay = signatory.declinedAt ? signedOnDay(signatory.declinedAt) : "";
+            // "Not yet their turn" would be a lie once someone has refused: their
+            // turn is not coming. A stopped ceremony says so.
+            const waitingLabel = resolution.status === "declined" ? "Ceremony stopped" : STATE_LABEL.waiting;
+            const detail = state === "signed" && signedDay
+                ? `Signed ${signedDay}`
+                : state === "declined" && declinedDay
+                    ? `Declined ${declinedDay}`
+                    : state === "waiting"
+                        ? waitingLabel
+                        : STATE_LABEL[state];
+            const reason = state === "declined" && signatory.declineReason
+                ? `<span part="reason">${escapeHtml(signatory.declineReason)}</span>`
+                : "";
+            return `
+          <li part="party" data-state="${state}" data-signatory-id="${escapeHtml(signatory.id)}">
+            <span part="order" aria-hidden="true">${String(order)}</span>
+            <span part="avatar" aria-hidden="true">${escapeHtml(initialsOf(signatory.name))}</span>
+            <span part="identity">
+              <span part="name">${escapeHtml(signatory.name)}</span>
+              ${signatory.role ? `<span part="role">${escapeHtml(signatory.role)}</span>` : ""}
+            </span>
+            <span part="state">${escapeHtml(detail)}</span>
+            ${reason}
+          </li>
+        `;
+        })
+            .join("");
+        const summary = formatCeremonySummary(resolution);
+        this.hostEl.innerHTML = `
+      <section part="card" aria-label="${escapeHtml(this.heading)}">
+        <div part="header">
+          <h3 part="heading">${escapeHtml(this.heading)}</h3>
+          <span part="summary" data-status="${resolution.status}">${escapeHtml(summary)}</span>
+        </div>
+        ${resolution.total
+            ? `<ol part="parties">${rows}</ol>`
+            : `<div part="empty">No signatories yet.</div>`}
+      </section>
+    `;
+    }
+}
+SignatureCeremony.register();

package/dist/patterns/signature/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Signature ceremony model and the pure engine that resolves it.
+ *
+ * DOM-free and deterministic, so the rules that decide *who may sign now* are
+ * testable on their own and a host can drive its own signing surface — or its
+ * server-side reminders — from the same function.
+ */
+/**
+ * `sequential` routes the document one party at a time, in order.
+ * `parallel` sends it to everyone at once.
+ */
+export type SignatureMode = "sequential" | "parallel";
+/**
+ * `awaiting` means this party can act **now**. `waiting` means their turn has
+ * not come — or the ceremony has stopped and will never reach them. The
+ * distinction is the whole point of the component: only `awaiting` should ever
+ * carry a sign-now affordance.
+ */
+export type SignatoryState = "signed" | "declined" | "awaiting" | "waiting";
+export type CeremonyStatus = "completed" | "in-progress" | "declined";
+export interface Signatory {
+    id: string;
+    name: string;
+    /** Capacity they sign in — "Counterparty", "General Counsel". */
+    role?: string;
+    email?: string;
+    /** ISO timestamp. Present means signed. */
+    signedAt?: string;
+    /** ISO timestamp. Present means refused, which stops the ceremony. */
+    declinedAt?: string;
+    declineReason?: string;
+}
+export interface SignatoryStatus {
+    signatory: Signatory;
+    state: SignatoryState;
+    /** 1-based: the signing position in sequential mode, display order otherwise. */
+    order: number;
+}
+export interface CeremonyResolution {
+    statuses: SignatoryStatus[];
+    status: CeremonyStatus;
+    signedCount: number;
+    total: number;
+    /** Parties who may act right now. Empty once the ceremony is done or stopped. */
+    awaiting: Signatory[];
+}
+/**
+ * Resolve every party's state from the signing order and what has happened.
+ *
+ * Three rules, in priority order:
+ *
+ * 1. **A decline stops the ceremony.** Nobody who has not already signed
+ *    becomes `awaiting` — not even in parallel mode, where they otherwise
+ *    could all act. This is the rule worth being strict about: a declined
+ *    document is dead until the host revives it, and showing someone a
+ *    sign-now affordance for it wastes their time and produces a signature
+ *    against a document the counterparty has already refused.
+ * 2. **Sequential grants exactly one turn.** The first unsigned party is
+ *    `awaiting`; everyone behind them is `waiting`. A later party can never
+ *    appear actionable before an earlier one has signed.
+ * 3. **Parallel grants every turn at once** — all unsigned parties are
+ *    `awaiting`.
+ */
+export declare const resolveCeremony: (signatories: readonly Signatory[], mode?: SignatureMode) => CeremonyResolution;
+/** Human phrasing for the ceremony as a whole. */
+export declare const formatCeremonySummary: (resolution: CeremonyResolution) => string;
+/** Attribute payloads are author input — validate every record. */
+export declare const isSignatoryRecord: (value: unknown) => value is Signatory;

package/dist/patterns/signature/types.js

@@ -0,0 +1,89 @@
+/**
+ * Signature ceremony model and the pure engine that resolves it.
+ *
+ * DOM-free and deterministic, so the rules that decide *who may sign now* are
+ * testable on their own and a host can drive its own signing surface — or its
+ * server-side reminders — from the same function.
+ */
+/**
+ * Resolve every party's state from the signing order and what has happened.
+ *
+ * Three rules, in priority order:
+ *
+ * 1. **A decline stops the ceremony.** Nobody who has not already signed
+ *    becomes `awaiting` — not even in parallel mode, where they otherwise
+ *    could all act. This is the rule worth being strict about: a declined
+ *    document is dead until the host revives it, and showing someone a
+ *    sign-now affordance for it wastes their time and produces a signature
+ *    against a document the counterparty has already refused.
+ * 2. **Sequential grants exactly one turn.** The first unsigned party is
+ *    `awaiting`; everyone behind them is `waiting`. A later party can never
+ *    appear actionable before an earlier one has signed.
+ * 3. **Parallel grants every turn at once** — all unsigned parties are
+ *    `awaiting`.
+ */
+export const resolveCeremony = (signatories, mode = "sequential") => {
+    const declined = signatories.some(signatory => signatory.declinedAt);
+    const signedCount = signatories.filter(signatory => signatory.signedAt && !signatory.declinedAt).length;
+    let turnTaken = false;
+    const statuses = signatories.map((signatory, index) => {
+        const order = index + 1;
+        if (signatory.declinedAt) {
+            return { signatory, state: "declined", order };
+        }
+        if (signatory.signedAt) {
+            return { signatory, state: "signed", order };
+        }
+        // Rule 1: a stopped ceremony grants no turns at all.
+        if (declined) {
+            return { signatory, state: "waiting", order };
+        }
+        if (mode === "parallel") {
+            return { signatory, state: "awaiting", order };
+        }
+        // Rule 2: sequential hands out a single turn, to the first unsigned party.
+        if (turnTaken) {
+            return { signatory, state: "waiting", order };
+        }
+        turnTaken = true;
+        return { signatory, state: "awaiting", order };
+    });
+    const status = declined
+        ? "declined"
+        : signatories.length > 0 && signedCount === signatories.length
+            ? "completed"
+            : "in-progress";
+    return {
+        statuses,
+        status,
+        signedCount,
+        total: signatories.length,
+        awaiting: statuses
+            .filter(entry => entry.state === "awaiting")
+            .map(entry => entry.signatory),
+    };
+};
+/** Human phrasing for the ceremony as a whole. */
+export const formatCeremonySummary = (resolution) => {
+    if (resolution.total === 0) {
+        return "No signatories";
+    }
+    if (resolution.status === "declined") {
+        return "Declined";
+    }
+    if (resolution.status === "completed") {
+        return "Fully executed";
+    }
+    return `${String(resolution.signedCount)} of ${String(resolution.total)} signed`;
+};
+/** Attribute payloads are author input — validate every record. */
+export const isSignatoryRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const signatory = value;
+    return (typeof signatory.id === "string" &&
+        signatory.id.length > 0 &&
+        typeof signatory.name === "string" &&
+        signatory.name.length > 0);
+};

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

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./timeline.js";

package/dist/patterns/timeline/index.js

@@ -0,0 +1,4 @@
+// Event model and validation
+export * from "./types.js";
+// Composed activity-feed surface
+export * from "./timeline.js";

package/dist/patterns/timeline/timeline.d.ts

@@ -0,0 +1,27 @@
+import type { TimelineEvent } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+export declare class Timeline extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private titleEl;
+    private eventsEl;
+    private emptyEl;
+    private loadMoreRegionEl;
+    private composerEl;
+    private composerInputEl;
+    private eventsSignature;
+    get heading(): string;
+    set heading(value: string);
+    /** Append-only event list; JSON records validated before rendering. */
+    get events(): TimelineEvent[];
+    set events(value: TimelineEvent[]);
+    get composable(): boolean;
+    set composable(value: boolean);
+    get hasMore(): boolean;
+    set hasMore(value: boolean);
+    private emitEntrySubmitted;
+    private rebuildEvents;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}