@unofficialbox/box-open-elements 0.1.0

package/dist/patterns/share/collaborator-avatars.js

@@ -0,0 +1,214 @@
+import { BaseElement } from "../../core/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+const DEFAULT_TAG_NAME = "box-collaborator-avatars";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+const initialsFromName = (name) => name
+    .trim()
+    .split(/\s+/)
+    .slice(0, 2)
+    .map(segment => segment[0] ?? "")
+    .join("")
+    .toUpperCase();
+const isCollaborator = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.name === "string" &&
+        (candidate.id === undefined || typeof candidate.id === "string") &&
+        (candidate.initials === undefined || typeof candidate.initials === "string") &&
+        (candidate.src === undefined || typeof candidate.src === "string"));
+};
+/**
+ * A stacked "avatar pile" for the collaborators on an item, with a `+N` overflow
+ * chip once the count exceeds `max`. A composition: data arrives via the
+ * `collaborators` property (no transport). Each visible avatar is a button that
+ * emits `select`; the overflow chip emits `overflow`. The group is labelled for
+ * assistive tech and the hidden count is announced.
+ */
+const elementStyles = `
+        :host {
+          display: inline-block;
+          color: inherit;
+          font: inherit;
+        }
+
+        [part="group"] {
+          display: inline-flex;
+          align-items: center;
+        }
+
+        [part="avatar"],
+        [part="overflow"] {
+          appearance: none;
+          display: inline-grid;
+          place-items: center;
+          inline-size: 2.1rem;
+          block-size: 2.1rem;
+          margin-inline-start: -0.55rem;
+          padding: 0;
+          overflow: hidden;
+          border: 2px solid var(--boe-token-surface-surface, #ffffff);
+          border-radius: 999px;
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 12%, var(--boe-token-surface-surface, #ffffff) 88%);
+          color: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 72%, var(--boe-token-text-text, #222222));
+          font: inherit;
+          font-size: 0.78rem;
+          font-weight: 700;
+          cursor: pointer;
+          transition: transform ${boeMotionDuration.fast} ${boeMotionEasing.standard};
+        }
+
+        [part="group"] > :first-child {
+          margin-inline-start: 0;
+        }
+
+        [part="avatar"]:hover,
+        [part="avatar"]:focus-visible,
+        [part="overflow"]:hover,
+        [part="overflow"]:focus-visible {
+          transform: translateY(-2px);
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 22%, transparent);
+        }
+
+        [part="overflow"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-secondary, #fbfbfb) 82%, var(--boe-token-surface-surface, #ffffff) 18%);
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="avatar-image"] {
+          inline-size: 100%;
+          block-size: 100%;
+          object-fit: cover;
+        }
+
+        [part="empty"] {
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-size: 0.86rem;
+        }
+      `;
+export class BoxCollaboratorAvatarsElement extends BaseElement {
+    static get observedAttributes() {
+        return ["collaborators", "label", "max"];
+    }
+    get collaborators() {
+        const raw = this.getAttribute("collaborators");
+        if (!raw) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed.filter(isCollaborator) : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    set collaborators(value) {
+        this.setAttribute("collaborators", JSON.stringify(value));
+    }
+    get label() {
+        return this.getAttribute("label")?.trim() || "Collaborators";
+    }
+    set label(value) {
+        this.setAttribute("label", value);
+    }
+    get max() {
+        const raw = Number(this.getAttribute("max") ?? "5");
+        if (!Number.isFinite(raw) || raw < 1) {
+            return 5;
+        }
+        return Math.floor(raw);
+    }
+    set max(value) {
+        this.setAttribute("max", String(value));
+    }
+    connectedCallback() {
+        super.connectedCallback();
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        super.attributeChangedCallback(name, oldValue, newValue);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${elementStyles}</style>
+      <div part="content-host"></div>
+    `;
+    }
+    update() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        const collaborators = this.collaborators;
+        const max = this.max;
+        const visible = collaborators.slice(0, max);
+        const overflow = Math.max(0, collaborators.length - visible.length);
+        const avatarsMarkup = visible
+            .map((collaborator, index) => {
+            const initials = collaborator.initials || initialsFromName(collaborator.name) || "?";
+            const inner = collaborator.src
+                ? `<img part="avatar-image" src="${escapeHtml(collaborator.src)}" alt="" />`
+                : escapeHtml(initials);
+            return `
+          <button
+            type="button"
+            part="avatar"
+            data-index="${index}"
+            style="z-index:${visible.length - index};"
+            aria-label="${escapeHtml(collaborator.name)}"
+            title="${escapeHtml(collaborator.name)}"
+          >${inner}</button>
+        `;
+        })
+            .join("");
+        const overflowMarkup = overflow
+            ? `<button type="button" part="overflow" aria-label="${overflow} more" title="${overflow} more">+${overflow}</button>`
+            : "";
+        const host = this.shadowRoot.querySelector('[part="content-host"]');
+        if (!host) {
+            return;
+        }
+        host.innerHTML = `
+      ${collaborators.length
+            ? `<div part="group" role="group" aria-label="${escapeHtml(this.label)}">${avatarsMarkup}${overflowMarkup}</div>`
+            : `<div part="group" role="group" aria-label="${escapeHtml(this.label)}"><span part="empty">No collaborators</span></div>`}
+    `;
+        for (const avatar of Array.from(this.shadowRoot.querySelectorAll('[part="avatar"]'))) {
+            avatar.addEventListener("click", () => {
+                const index = Number(avatar.dataset.index ?? "-1");
+                const collaborator = visible[index];
+                if (collaborator) {
+                    this.dispatchEvent(new CustomEvent("select", {
+                        bubbles: true,
+                        composed: true,
+                        detail: { id: collaborator.id, name: collaborator.name },
+                    }));
+                }
+            });
+        }
+        this.shadowRoot.querySelector('[part="overflow"]')?.addEventListener("click", () => {
+            this.dispatchEvent(new CustomEvent("overflow", {
+                bubbles: true,
+                composed: true,
+                detail: { count: overflow },
+            }));
+        });
+    }
+}
+export const defineBoxCollaboratorAvatarsElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxCollaboratorAvatarsElement);
+    return BoxCollaboratorAvatarsElement;
+};

package/dist/patterns/share/contracts.d.ts

@@ -0,0 +1,65 @@
+export interface ShareFetchLike {
+    (input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+export interface ShareRequestContext {
+    locale?: string;
+    requestId?: string;
+    signal?: AbortSignal;
+}
+export interface SharedLinkState {
+    url?: string;
+    access?: "open" | "company" | "collaborators";
+    passwordEnabled?: boolean;
+    canDownload?: boolean;
+    canPreview?: boolean;
+    expiresAt?: string | null;
+}
+export interface CollaboratorSummary {
+    id: string;
+    name: string;
+    type: "user" | "group" | "invite";
+    role: string;
+    status?: string;
+}
+export interface ShareState {
+    itemId: string;
+    itemType: "file" | "folder";
+    sharedLink: SharedLinkState | null;
+    collaborators: CollaboratorSummary[];
+}
+export interface ShareDataSource {
+    getShareState(input: {
+        itemId: string;
+        itemType: "file" | "folder";
+        context?: ShareRequestContext;
+    }): Promise<ShareState>;
+    updateSharedLink(input: {
+        itemId: string;
+        itemType: "file" | "folder";
+        sharedLink: SharedLinkState | null;
+        context?: ShareRequestContext;
+    }): Promise<ShareState>;
+    listCollaborators(input: {
+        itemId: string;
+        itemType: "file" | "folder";
+        context?: ShareRequestContext;
+    }): Promise<CollaboratorSummary[]>;
+}
+export interface ShareHttpDataSourceOptions {
+    baseUrl?: string;
+    fetch?: ShareFetchLike;
+    headers?: Record<string, string>;
+    buildGetShareStateUrl?: (input: {
+        itemId: string;
+        itemType: "file" | "folder";
+    }) => string;
+    buildUpdateSharedLinkUrl?: (input: {
+        itemId: string;
+        itemType: "file" | "folder";
+    }) => string;
+    buildListCollaboratorsUrl?: (input: {
+        itemId: string;
+        itemType: "file" | "folder";
+    }) => string;
+}
+export declare const createHttpShareDataSource: (options?: ShareHttpDataSourceOptions) => ShareDataSource;

package/dist/patterns/share/contracts.js

@@ -0,0 +1,75 @@
+const resolveFetch = (providedFetch) => {
+    if (providedFetch) {
+        return providedFetch;
+    }
+    if (typeof globalThis.fetch !== "function") {
+        throw new Error("A fetch implementation is required to use the share HTTP data source.");
+    }
+    return globalThis.fetch.bind(globalThis);
+};
+const getErrorMessage = async (response) => {
+    try {
+        const payload = (await response.json());
+        if (payload.message) {
+            return payload.code ? `${payload.code}: ${payload.message}` : payload.message;
+        }
+    }
+    catch {
+        // ignore parse issues and fall back to status text
+    }
+    return `Share request failed with status ${response.status}`;
+};
+export const createHttpShareDataSource = (options = {}) => {
+    const fetchImpl = resolveFetch(options.fetch);
+    const baseUrl = (options.baseUrl ?? "/api/share").replace(/\/$/, "");
+    const withContextHeaders = (context) => ({
+        accept: "application/json",
+        ...(context?.locale ? { "accept-language": context.locale } : {}),
+        ...(context?.requestId ? { "x-request-id": context.requestId } : {}),
+        ...options.headers,
+    });
+    const readJson = async (response) => {
+        if (!response.ok) {
+            throw new Error(await getErrorMessage(response));
+        }
+        return (await response.json());
+    };
+    return {
+        async getShareState(input) {
+            const url = options.buildGetShareStateUrl?.(input) ??
+                `${baseUrl}/items/${encodeURIComponent(input.itemType)}/${encodeURIComponent(input.itemId)}`;
+            const response = await fetchImpl(url, {
+                method: "GET",
+                headers: withContextHeaders(input.context),
+                signal: input.context?.signal,
+            });
+            return readJson(response);
+        },
+        async updateSharedLink(input) {
+            const url = options.buildUpdateSharedLinkUrl?.(input) ??
+                `${baseUrl}/items/${encodeURIComponent(input.itemType)}/${encodeURIComponent(input.itemId)}/shared-link`;
+            const response = await fetchImpl(url, {
+                method: "PUT",
+                headers: {
+                    ...withContextHeaders(input.context),
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                    sharedLink: input.sharedLink,
+                }),
+                signal: input.context?.signal,
+            });
+            return readJson(response);
+        },
+        async listCollaborators(input) {
+            const url = options.buildListCollaboratorsUrl?.(input) ??
+                `${baseUrl}/items/${encodeURIComponent(input.itemType)}/${encodeURIComponent(input.itemId)}/collaborators`;
+            const response = await fetchImpl(url, {
+                method: "GET",
+                headers: withContextHeaders(input.context),
+                signal: input.context?.signal,
+            });
+            return readJson(response);
+        },
+    };
+};

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

@@ -0,0 +1,14 @@
+export * from "./contracts.js";
+export * from "./schemas.js";
+export * from "./access-stats.js";
+export * from "./collaborator-avatars.js";
+export * from "./invite-collaborators-contracts.js";
+export * from "./invite-collaborators-controller.js";
+export * from "./invite-collaborators-modal.js";
+export * from "./permission-matrix.js";
+export * from "./presence-contracts.js";
+export * from "./presence-controller.js";
+export * from "./presence.js";
+export * from "./share-panel.js";
+export * from "./unified-share-controller.js";
+export * from "./unified-share-modal.js";

package/dist/patterns/share/index.js

@@ -0,0 +1,14 @@
+export * from "./contracts.js";
+export * from "./schemas.js";
+export * from "./access-stats.js";
+export * from "./collaborator-avatars.js";
+export * from "./invite-collaborators-contracts.js";
+export * from "./invite-collaborators-controller.js";
+export * from "./invite-collaborators-modal.js";
+export * from "./permission-matrix.js";
+export * from "./presence-contracts.js";
+export * from "./presence-controller.js";
+export * from "./presence.js";
+export * from "./share-panel.js";
+export * from "./unified-share-controller.js";
+export * from "./unified-share-modal.js";

package/dist/patterns/share/invite-collaborators-contracts.d.ts

@@ -0,0 +1,38 @@
+/** A role that can be granted to an invited collaborator. */
+export interface InviteRole {
+    value: string;
+    label: string;
+}
+/** The payload submitted when inviting collaborators to an item. */
+export interface InviteCollaboratorsInput {
+    itemId: string;
+    recipients: string[];
+    role: string;
+    message?: string;
+}
+/** The transport's response to an invite submission. */
+export interface InviteResult {
+    invited: string[];
+    failed?: {
+        recipient: string;
+        reason: string;
+    }[];
+}
+/**
+ * The transport a host provides to actually deliver invitations. Narrow by
+ * design: the workflow owns the form state and validation; the transport owns
+ * delivery (an API call, a queue, a mock).
+ */
+export interface InviteCollaboratorsTransport {
+    sendInvites(input: InviteCollaboratorsInput): Promise<InviteResult>;
+}
+export type InviteStatus = "idle" | "submitting" | "success" | "error";
+/** The controller's observable state for the invite flow. */
+export interface InviteCollaboratorsState {
+    recipients: string[];
+    role: string;
+    message: string;
+    status: InviteStatus;
+    error: string | null;
+    result: InviteResult | null;
+}

package/dist/patterns/share/invite-collaborators-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/patterns/share/invite-collaborators-controller.d.ts

@@ -0,0 +1,40 @@
+import { Controller } from "../../core/index.js";
+import type { InviteCollaboratorsState, InviteCollaboratorsTransport, InviteResult } from "./invite-collaborators-contracts.js";
+export interface InviteCollaboratorsControllerConfig {
+    itemId: string;
+    transport: InviteCollaboratorsTransport;
+    role?: string;
+}
+type InviteCollaboratorsEvents = {
+    stateChanged: {
+        state: InviteCollaboratorsState;
+    };
+    submitted: {
+        result: InviteResult;
+    };
+    error: {
+        error: string;
+    };
+};
+/**
+ * Headless controller for the invite-collaborators flow. It owns the form state
+ * — the recipient list (validated, de-duplicated emails), the granted role, and
+ * an optional message — plus the async submission lifecycle, delegating actual
+ * delivery to the injected transport. Consumers subscribe to `stateChanged` and
+ * render; `submit()` resolves to whether the invite succeeded.
+ */
+export declare class InviteCollaboratorsController extends Controller<InviteCollaboratorsState, InviteCollaboratorsEvents> {
+    private readonly config;
+    constructor(config: InviteCollaboratorsControllerConfig);
+    get recipients(): string[];
+    private update;
+    /** Add a validated, lower-cased email. Returns false for invalid or duplicate input. */
+    addRecipient(email: string): boolean;
+    removeRecipient(email: string): void;
+    setRole(role: string): void;
+    setMessage(message: string): void;
+    reset(): void;
+    /** Submit the current recipients via the transport. No-op without recipients or while submitting. */
+    submit(): Promise<boolean>;
+}
+export {};

package/dist/patterns/share/invite-collaborators-controller.js

@@ -0,0 +1,86 @@
+import { Controller } from "../../core/index.js";
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/**
+ * Headless controller for the invite-collaborators flow. It owns the form state
+ * — the recipient list (validated, de-duplicated emails), the granted role, and
+ * an optional message — plus the async submission lifecycle, delegating actual
+ * delivery to the injected transport. Consumers subscribe to `stateChanged` and
+ * render; `submit()` resolves to whether the invite succeeded.
+ */
+export class InviteCollaboratorsController extends Controller {
+    config;
+    constructor(config) {
+        super({
+            recipients: [],
+            role: config.role ?? "editor",
+            message: "",
+            status: "idle",
+            error: null,
+            result: null,
+        });
+        this.config = config;
+    }
+    get recipients() {
+        return this.state.recipients;
+    }
+    update(patch) {
+        this.setState({ ...this.state, ...patch });
+        this.emit("stateChanged", { state: this.state });
+    }
+    /** Add a validated, lower-cased email. Returns false for invalid or duplicate input. */
+    addRecipient(email) {
+        const value = email.trim().toLowerCase();
+        if (!EMAIL_PATTERN.test(value) || this.state.recipients.includes(value)) {
+            return false;
+        }
+        this.update({ recipients: [...this.state.recipients, value], error: null });
+        return true;
+    }
+    removeRecipient(email) {
+        if (!this.state.recipients.includes(email)) {
+            return;
+        }
+        this.update({ recipients: this.state.recipients.filter(item => item !== email) });
+    }
+    setRole(role) {
+        if (role && role !== this.state.role) {
+            this.update({ role });
+        }
+    }
+    setMessage(message) {
+        this.update({ message });
+    }
+    reset() {
+        this.update({
+            recipients: [],
+            message: "",
+            status: "idle",
+            error: null,
+            result: null,
+        });
+    }
+    /** Submit the current recipients via the transport. No-op without recipients or while submitting. */
+    async submit() {
+        if (!this.state.recipients.length || this.state.status === "submitting") {
+            return false;
+        }
+        this.update({ status: "submitting", error: null });
+        try {
+            const result = await this.config.transport.sendInvites({
+                itemId: this.config.itemId,
+                recipients: [...this.state.recipients],
+                role: this.state.role,
+                message: this.state.message || undefined,
+            });
+            this.update({ status: "success", result });
+            this.emit("submitted", { result });
+            return true;
+        }
+        catch (caught) {
+            const error = caught instanceof Error ? caught.message : "Failed to send invitations";
+            this.update({ status: "error", error });
+            this.emit("error", { error });
+            return false;
+        }
+    }
+}

package/dist/patterns/share/invite-collaborators-modal.d.ts

@@ -0,0 +1,46 @@
+import type { InviteCollaboratorsTransport, InviteRole } from "./invite-collaborators-contracts.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * The invite-collaborators workflow surface: a modal that collects recipient
+ * emails (as removable pills), a role, and an optional message, then submits via
+ * an `InviteCollaboratorsController` it owns (created from the injected
+ * `transport` + `item-id`). Emits `submitted` on success and `cancel` on
+ * dismissal, closing itself in both cases. Structure is built once per open so
+ * the live inputs keep focus while only the pills/status update.
+ */
+export declare class BoxInviteCollaboratorsModalElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private controller;
+    private controllerUnsubscribe;
+    private transportValue;
+    private rolesValue;
+    private rolesSignature;
+    private readonly focusRestore;
+    private wasOpen;
+    get open(): boolean;
+    set open(value: boolean);
+    get itemId(): string;
+    set itemId(value: string);
+    get heading(): string;
+    set heading(value: string);
+    get submitLabel(): string;
+    set submitLabel(value: string);
+    get transport(): InviteCollaboratorsTransport | null;
+    set transport(value: InviteCollaboratorsTransport | null);
+    get roles(): InviteRole[];
+    set roles(value: InviteRole[]);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    private ensureController;
+    private teardownController;
+    private refresh;
+    protected renderTemplate(): void;
+    protected update(): void;
+    private buildStructure;
+    private attachListeners;
+    private submit;
+    private close;
+    private updateDynamic;
+}
+export declare const defineBoxInviteCollaboratorsModalElement: (tagName?: string) => typeof BoxInviteCollaboratorsModalElement;