@unofficialbox/box-open-elements 0.5.0 → 0.7.0

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

@@ -0,0 +1,53 @@
+/**
+ * Node roles in a provenance chain. Open vocabulary — `clause`, `template`,
+ * and `contract` are the CLM conventions, but hosts add their own kinds
+ * without a schema change.
+ */
+export type LineageKind = string;
+/** How far a node's text drifted from the parent it derives from. */
+export type LineageDeviation = "none" | "minor" | "major";
+/**
+ * One typed derivation link. Unlike the versions pattern (where a parent is
+ * just an id), lineage links carry the comparison payload: how severely the
+ * child deviates from that parent, and an optional one-line summary.
+ */
+export interface LineageParentLink {
+    id: string;
+    deviation?: LineageDeviation;
+    /** One-line description of the drift, e.g. "liability cap reworded". */
+    note?: string;
+}
+/**
+ * One node in the provenance DAG: a library clause, a template that embeds
+ * it, or an executed contract containing the final text. `parents` carries
+ * the derivation topology; a root (the source clause) has none.
+ */
+export interface LineageNode {
+    id: string;
+    /** Short display name: "Clause 4.2 v5", "Template 2026", "MSA_Acme §4.2". */
+    label: string;
+    kind?: LineageKind;
+    parents?: LineageParentLink[];
+    /** Reference to the underlying record, for hosts to resolve on selection. */
+    entityRef?: {
+        id: string;
+        label?: string;
+    };
+    actor?: {
+        name: string;
+        initials?: string;
+    };
+    /** ISO timestamp; display only — `parents` defines the topology. */
+    timestamp?: string;
+    note?: string;
+}
+/** Detail payload for `edge-selected`; feeds the diff viewer's base/target pair. */
+export interface LineageEdgeDetail {
+    parent: LineageNode;
+    child: LineageNode;
+    deviation: LineageDeviation;
+    note?: string;
+}
+export declare const resolveLineageDeviation: (value: string | null | undefined) => LineageDeviation;
+/** Attribute payloads are author input — validate every record, not just the array. */
+export declare const isLineageNodeRecord: (value: unknown) => value is LineageNode;

package/dist/patterns/lineage/types.js

@@ -0,0 +1,49 @@
+const DEVIATIONS = new Set(["none", "minor", "major"]);
+export const resolveLineageDeviation = (value) => (value && DEVIATIONS.has(value) ? value : "none");
+/** Attribute payloads are author input — validate every record, not just the array. */
+export const isLineageNodeRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const node = value;
+    if (typeof node.id !== "string" || node.id.length === 0 || typeof node.label !== "string") {
+        return false;
+    }
+    for (const field of ["kind", "timestamp", "note"]) {
+        if (node[field] !== undefined && typeof node[field] !== "string") {
+            return false;
+        }
+    }
+    if (node.parents !== undefined) {
+        if (!Array.isArray(node.parents)) {
+            return false;
+        }
+        for (const entry of node.parents) {
+            const link = entry;
+            if (typeof link !== "object" ||
+                link === null ||
+                typeof link.id !== "string" ||
+                link.id.length === 0 ||
+                (link.deviation !== undefined && typeof link.deviation !== "string") ||
+                (link.note !== undefined && typeof link.note !== "string")) {
+                return false;
+            }
+        }
+    }
+    if (node.entityRef !== undefined) {
+        const ref = node.entityRef;
+        if (typeof ref !== "object" || ref === null || typeof ref.id !== "string") {
+            return false;
+        }
+    }
+    if (node.actor !== undefined) {
+        const actor = node.actor;
+        if (typeof actor !== "object" || actor === null || typeof actor.name !== "string") {
+            return false;
+        }
+        if (actor.initials !== undefined && typeof actor.initials !== "string") {
+            return false;
+        }
+    }
+    return true;
+};

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

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export * from "./notification-bell.js";
+export * from "./notification-inbox.js";

package/dist/patterns/notifications/index.js

@@ -0,0 +1,6 @@
+// Notification model + pure grouping/counting engine
+export * from "./types.js";
+// Bell with unread count for the app chrome
+export * from "./notification-bell.js";
+// Triage inbox panel
+export * from "./notification-inbox.js";

package/dist/patterns/notifications/notification-bell.d.ts

@@ -0,0 +1,38 @@
+import type { NotificationItem } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * The bell: an unread count over a trigger, for the app chrome.
+ *
+ * The count is the accessible name, not decoration — "Notifications, 3
+ * unread" — because a red dot alone tells a screen-reader user nothing. Past
+ * `max` the badge reads "9+" while the label still states the true count,
+ * since the abbreviation is a layout concession and the number is the fact.
+ */
+export declare class NotificationBell extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private triggerEl;
+    private countEl;
+    private notificationsRaw;
+    private notificationsCache;
+    get label(): string;
+    set label(value: string);
+    /** Largest number rendered before the badge abbreviates, e.g. `9+`. */
+    get max(): number;
+    set max(value: number);
+    get expanded(): boolean;
+    set expanded(value: boolean);
+    /** Optional records; supply these or `unread-count`, not both. */
+    get notifications(): NotificationItem[];
+    set notifications(value: NotificationItem[]);
+    /**
+     * Unread total. Derived from `notifications` when they are supplied;
+     * otherwise read from the attribute, so a host that keeps the list on the
+     * server can still drive the badge with one number.
+     */
+    get unreadCount(): number;
+    set unreadCount(value: number);
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

package/dist/patterns/notifications/notification-bell.js

@@ -0,0 +1,198 @@
+import { countUnreadNotifications, isNotificationItemRecord } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+import { boeRadius } from "../../foundations/geometry/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+const DEFAULT_TAG_NAME = "box-notification-bell";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+const elementStyles = `
+        [hidden] {
+          display: none !important;
+        }
+
+        :host {
+          display: inline-block;
+        }
+
+        [part="trigger"] {
+          position: relative;
+          appearance: none;
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          inline-size: 2.25rem;
+          block-size: 2.25rem;
+          padding: 0;
+          border: 1px solid transparent;
+          border-radius: ${boeRadius.control};
+          background: none;
+          color: var(--boe-token-text-text, #1f1e1b);
+          font: inherit;
+          font-size: 1.05rem;
+          cursor: pointer;
+          transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+        }
+
+        [part="trigger"]:hover {
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="trigger"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
+        }
+
+        [part="trigger"][aria-expanded="true"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 12%, transparent);
+          border-color: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 30%, transparent);
+        }
+
+        [part="count"] {
+          position: absolute;
+          inset-block-start: 0;
+          inset-inline-end: 0;
+          transform: translate(35%, -35%);
+          min-inline-size: 1.1rem;
+          padding: 0 0.25rem;
+          border-radius: 999px;
+          background: var(--boe-token-surface-status-surface-error, #ed3757);
+          color: var(--boe-token-text-text-on-brand, #ffffff);
+          font-size: 0.68rem;
+          font-weight: 700;
+          line-height: 1.1rem;
+          text-align: center;
+        }
+
+        [part="count"][data-dot="true"] {
+          min-inline-size: 0.5rem;
+          block-size: 0.5rem;
+          padding: 0;
+        }
+      `;
+/**
+ * The bell: an unread count over a trigger, for the app chrome.
+ *
+ * The count is the accessible name, not decoration — "Notifications, 3
+ * unread" — because a red dot alone tells a screen-reader user nothing. Past
+ * `max` the badge reads "9+" while the label still states the true count,
+ * since the abbreviation is a layout concession and the number is the fact.
+ */
+export class NotificationBell extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["expanded", "label", "max", "notifications", "unread-count"];
+    }
+    triggerEl;
+    countEl;
+    notificationsRaw = null;
+    notificationsCache = [];
+    get label() {
+        return this.getAttribute("label") ?? "Notifications";
+    }
+    set label(value) {
+        this.setAttribute("label", value);
+    }
+    /** Largest number rendered before the badge abbreviates, e.g. `9+`. */
+    get max() {
+        const raw = Number.parseInt(this.getAttribute("max") ?? "", 10);
+        return Number.isFinite(raw) && raw > 0 ? raw : 99;
+    }
+    set max(value) {
+        this.setAttribute("max", String(value));
+    }
+    get expanded() {
+        return this.hasAttribute("expanded");
+    }
+    set expanded(value) {
+        this.toggleAttribute("expanded", value);
+    }
+    /** Optional records; supply these or `unread-count`, not both. */
+    get notifications() {
+        const raw = this.getAttribute("notifications");
+        if (!raw) {
+            return [];
+        }
+        if (raw !== this.notificationsRaw) {
+            this.notificationsRaw = raw;
+            try {
+                const parsed = JSON.parse(raw);
+                this.notificationsCache =
+                    Array.isArray(parsed) && parsed.every(isNotificationItemRecord)
+                        ? parsed
+                        : [];
+            }
+            catch {
+                this.notificationsCache = [];
+            }
+        }
+        return [...this.notificationsCache];
+    }
+    set notifications(value) {
+        if (value.length) {
+            this.setAttribute("notifications", JSON.stringify(value));
+            return;
+        }
+        this.removeAttribute("notifications");
+    }
+    /**
+     * Unread total. Derived from `notifications` when they are supplied;
+     * otherwise read from the attribute, so a host that keeps the list on the
+     * server can still drive the badge with one number.
+     */
+    get unreadCount() {
+        if (this.hasAttribute("notifications")) {
+            return countUnreadNotifications(this.notifications);
+        }
+        const raw = Number.parseInt(this.getAttribute("unread-count") ?? "", 10);
+        return Number.isFinite(raw) && raw > 0 ? raw : 0;
+    }
+    set unreadCount(value) {
+        this.setAttribute("unread-count", String(Math.max(0, Math.trunc(value))));
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${elementStyles}</style>
+      <button type="button" part="trigger" aria-expanded="false" aria-haspopup="dialog">
+        <span part="icon" aria-hidden="true">🔔</span>
+        <span part="count" aria-hidden="true" hidden></span>
+      </button>
+    `;
+        this.triggerEl = this.shadowRoot.querySelector('[part="trigger"]');
+        this.countEl = this.shadowRoot.querySelector('[part="count"]');
+    }
+    setupListeners() {
+        this.triggerEl.addEventListener("click", () => {
+            const expanded = !this.expanded;
+            this.expanded = expanded;
+            this.dispatchEvent(new CustomEvent("toggle", {
+                bubbles: true,
+                composed: true,
+                detail: { expanded, unreadCount: this.unreadCount },
+            }));
+        });
+    }
+    update() {
+        if (!this.triggerEl) {
+            return;
+        }
+        const unread = this.unreadCount;
+        const max = this.max;
+        this.countEl.hidden = unread === 0;
+        this.countEl.textContent = unread > max ? `${String(max)}+` : String(unread);
+        // A zero-width badge would be invisible; a dot is the honest minimum.
+        this.countEl.setAttribute("data-dot", String(this.countEl.textContent === ""));
+        // The abbreviated badge is a layout concession — the label keeps the
+        // real number so assistive tech is never told "9+" when it is 240.
+        const suffix = unread === 0 ? "no unread" : `${String(unread)} unread`;
+        this.triggerEl.setAttribute("aria-label", `${escapeHtml(this.label)}, ${suffix}`);
+        this.triggerEl.setAttribute("aria-expanded", String(this.expanded));
+    }
+}
+NotificationBell.register();

package/dist/patterns/notifications/notification-inbox.d.ts

@@ -0,0 +1,46 @@
+import type { NotificationFilter, NotificationItem } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * The triage inbox: approvals waiting, SLA breaches, mentions — grouped by
+ * type, filterable to unread, with per-row and bulk intents.
+ *
+ * Toasts are the wrong surface for this: they are transient and unordered,
+ * while triage needs a list you can come back to. Sections lead with the most
+ * unread so what needs attention rises to the top.
+ *
+ * Mutations are intents, not state changes. The element never marks anything
+ * read on its own — the host owns the write and feeds back a new list, so the
+ * inbox can never disagree with the server about what has been seen.
+ */
+export declare class NotificationInbox extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private panelEl;
+    private titleEl;
+    private unreadPillEl;
+    private markAllEl;
+    private filtersEl;
+    private groupsEl;
+    private emptyEl;
+    private signature;
+    private notificationsRaw;
+    private notificationsCache;
+    get heading(): string;
+    set heading(value: string);
+    get filter(): NotificationFilter;
+    set filter(value: NotificationFilter);
+    /** Notification records; JSON payloads are validated per record. */
+    get notifications(): NotificationItem[];
+    set notifications(value: NotificationItem[]);
+    /** Optional `{ type: heading }` map; unmapped types are humanized. */
+    get typeLabels(): Record<string, string>;
+    set typeLabels(value: Record<string, string>);
+    get unreadCount(): number;
+    /** The records currently on screen, after the filter. */
+    get visibleNotifications(): NotificationItem[];
+    private emitIntent;
+    private itemHtml;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}