@unofficialbox/box-open-elements 0.10.0 → 0.12.0

package/dist/foundations/layout/grid.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Adobe Spectrum's responsive grid, as a foundation.
+ *
+ * Two surfaces build on this: `box-grid`, which lays out slotted content, and
+ * `box-skeleton`'s grid variant, which fills the same regions with shimmer
+ * bars. They must agree on what a column is worth and how wide a gutter is at
+ * a given viewport, so the model lives here rather than in either of them.
+ */
+/**
+ * Columns in the grid.
+ *
+ * Twelve divides by 2, 3, 4 and 6, so halves, thirds, quarters and
+ * sidebar-plus-content all land on whole columns.
+ */
+export declare const BOE_GRID_COLUMNS = 12;
+/**
+ * Spectrum's breakpoints and their gutters.
+ *
+ * Breakpoints are min-widths, so a viewport between two of them inherits the
+ * smaller one's dimensions. Gutters are fixed values per breakpoint rather
+ * than a proportion of the grid — that is Spectrum's rule, and it is why the
+ * gutter cannot simply be a percentage.
+ */
+export declare const BOE_GRID_BREAKPOINTS: readonly {
+    minWidth: number;
+    gutter: number;
+}[];
+/** The custom property every grid surface reads its gutter from. */
+export declare const BOE_GRID_GUTTER_PROPERTY = "--boe-grid-gutter";
+/**
+ * The gutter scale as CSS, scoped to a selector.
+ *
+ * Emitted rather than hand-written in each component so the two cannot drift,
+ * and so adding a breakpoint is one edit. A consumer overriding the property
+ * replaces the whole scale in one declaration.
+ */
+export declare const boeGridGutterStyles: (selector?: string) => string;
+/**
+ * One region of the grid: a block spanning some columns and rows, optionally
+ * pushed right by an offset. Spectrum calls these layout regions.
+ */
+export interface BoeGridPlacement {
+    /** Columns to span. Clamped to what is left after `offset`. */
+    span?: number;
+    /** Rows to span. Clamped to the grid's `rows`, so a region cannot exceed it. */
+    rowSpan?: number;
+    /** Empty columns before this region. Clamped to leave room for one column. */
+    offset?: number;
+}
+/** A resolved region: every field present, every value in range. */
+export interface ResolvedBoeGridPlacement {
+    span: number;
+    rowSpan: number;
+    offset: number;
+}
+/** Attribute payloads are author input — validate every record. */
+export declare const isBoeGridPlacementRecord: (value: unknown) => value is BoeGridPlacement;
+/**
+ * Fit a region to the grid.
+ *
+ * Every value is clamped rather than rejected. A layout that renders slightly
+ * wrong is recoverable; one that vanishes because a number was out of range is
+ * not, and the caller usually cannot tell which region was dropped. The clamps
+ * are what confine a region to the totals the author declared: a span of 9 in a
+ * three-column grid becomes 3, and a `rowSpan` of 5 in a three-row grid
+ * becomes 3.
+ */
+export declare const resolveBoeGridPlacement: (item: BoeGridPlacement, columns: number, rows: number) => ResolvedBoeGridPlacement;
+/** Parse a positive integer attribute, falling back when it is absent or junk. */
+export declare const resolveGridCount: (raw: string | null, fallback: number) => number;

package/dist/foundations/layout/grid.js

@@ -0,0 +1,84 @@
+/**
+ * Adobe Spectrum's responsive grid, as a foundation.
+ *
+ * Two surfaces build on this: `box-grid`, which lays out slotted content, and
+ * `box-skeleton`'s grid variant, which fills the same regions with shimmer
+ * bars. They must agree on what a column is worth and how wide a gutter is at
+ * a given viewport, so the model lives here rather than in either of them.
+ */
+/**
+ * Columns in the grid.
+ *
+ * Twelve divides by 2, 3, 4 and 6, so halves, thirds, quarters and
+ * sidebar-plus-content all land on whole columns.
+ */
+export const BOE_GRID_COLUMNS = 12;
+/**
+ * Spectrum's breakpoints and their gutters.
+ *
+ * Breakpoints are min-widths, so a viewport between two of them inherits the
+ * smaller one's dimensions. Gutters are fixed values per breakpoint rather
+ * than a proportion of the grid — that is Spectrum's rule, and it is why the
+ * gutter cannot simply be a percentage.
+ */
+export const BOE_GRID_BREAKPOINTS = [
+    { minWidth: 0, gutter: 16 },
+    { minWidth: 768, gutter: 24 },
+    { minWidth: 1280, gutter: 32 },
+    { minWidth: 1768, gutter: 40 },
+    { minWidth: 2160, gutter: 48 },
+];
+/** The custom property every grid surface reads its gutter from. */
+export const BOE_GRID_GUTTER_PROPERTY = "--boe-grid-gutter";
+/**
+ * The gutter scale as CSS, scoped to a selector.
+ *
+ * Emitted rather than hand-written in each component so the two cannot drift,
+ * and so adding a breakpoint is one edit. A consumer overriding the property
+ * replaces the whole scale in one declaration.
+ */
+export const boeGridGutterStyles = (selector = ":host") => BOE_GRID_BREAKPOINTS.map(({ minWidth, gutter }) => {
+    const declaration = `${selector} {\n    ${BOE_GRID_GUTTER_PROPERTY}: ${gutter}px;\n  }`;
+    return minWidth === 0
+        ? `  ${declaration}`
+        : `  @media (min-width: ${minWidth}px) {\n  ${declaration}\n  }`;
+}).join("\n\n");
+/** Attribute payloads are author input — validate every record. */
+export const isBoeGridPlacementRecord = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const item = value;
+    // Absent is fine — each field has a default. Present-but-not-a-number is not:
+    // it means the host built the payload wrong, and silently substituting a
+    // default would hide that.
+    return ["span", "rowSpan", "offset"].every(key => {
+        const raw = item[key];
+        return raw === undefined || (typeof raw === "number" && Number.isFinite(raw));
+    });
+};
+const clamp = (value, min, max) => Math.min(Math.max(Math.trunc(value), min), max);
+/**
+ * Fit a region to the grid.
+ *
+ * Every value is clamped rather than rejected. A layout that renders slightly
+ * wrong is recoverable; one that vanishes because a number was out of range is
+ * not, and the caller usually cannot tell which region was dropped. The clamps
+ * are what confine a region to the totals the author declared: a span of 9 in a
+ * three-column grid becomes 3, and a `rowSpan` of 5 in a three-row grid
+ * becomes 3.
+ */
+export const resolveBoeGridPlacement = (item, columns, rows) => {
+    // Leave at least one column for the region itself.
+    const offset = clamp(item.offset ?? 0, 0, Math.max(columns - 1, 0));
+    return {
+        offset,
+        span: clamp(item.span ?? 1, 1, Math.max(columns - offset, 1)),
+        rowSpan: clamp(item.rowSpan ?? 1, 1, Math.max(rows, 1)),
+    };
+};
+/** Parse a positive integer attribute, falling back when it is absent or junk. */
+export const resolveGridCount = (raw, fallback) => {
+    const parsed = Number.parseInt(raw ?? "", 10);
+    return Number.isFinite(parsed) ? Math.max(parsed, 1) : fallback;
+};

package/dist/foundations/layout/index.d.ts

@@ -0,0 +1 @@
+export * from "./grid.js";

package/dist/foundations/layout/index.js

@@ -0,0 +1,3 @@
+// Adobe Spectrum's responsive grid: columns, breakpoint gutters, and the
+// clamping that confines a region to the totals its host declared.
+export * from "./grid.js";

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export type { ResolvedTheme, ThemeChangeDetail, ThemeController, ThemeController
 export { DESIGN_PROFILE_CHANGE_EVENT, DESIGN_PROFILE_VARIABLES, DEFAULT_DESIGN_PROFILE_STORAGE_KEY, applyDesignProfile, boxDefaultDesignProfile, compactNeutralDesignProfile, createDesignProfileController, createDesignProfileStyleText, getDesignProfile, listDesignProfiles, registerBuiltInDesignProfiles, registerDesignProfile, resolveDesignProfileProperties, } from "./foundations/profiles/index.js";
 export type { ApplyDesignProfileOptions, DesignProfileChangeDetail, DesignProfileController, DesignProfileControllerOptions, DesignProfileDefinition, DesignProfileDensity, DesignProfileElevation, DesignProfileMotion, DesignProfileRadius, DesignProfileSpacing, DesignProfileTypography, } from "./foundations/profiles/index.js";
 export { boxIconography, boxIconographyAliases } from "./foundations/icons/index.js";
+export * from "./foundations/layout/index.js";
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 export type { OverlayAlign, OverlayPlacement, OverlaySide, PositionOptions, PositionResult, } from "./foundations/overlay/index.js";
 export * from "./components/actions/button.js";
@@ -42,10 +43,11 @@ export * from "./components/feedback/progress-ring.js";
 export * from "./components/feedback/progress-steps.js";
 export * from "./components/feedback/skeleton.js";
 export * from "./components/feedback/spinner.js";
-export * from "./components/feedback/stage-path.js";
+export * from "./components/feedback/path.js";
 export * from "./components/feedback/toast.js";
 export * from "./components/files/drop-zone.js";
 export * from "./components/identity/avatar.js";
+export * from "./components/identity/contact-datalist-item.js";
 export * from "./components/identity/persona.js";
 export * from "./components/navigation/accordion.js";
 export * from "./components/navigation/breadcrumb.js";
@@ -80,6 +82,7 @@ export * from "./components/forms/text-area.js";
 export * from "./components/forms/text-field.js";
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.js";
+export * from "./components/layout/grid.js";
 export * from "./components/layout/nav-sidebar.js";
 export * from "./components/layout/section.js";
 export * from "./components/layout/sidebar-toggle-button.js";
@@ -107,6 +110,7 @@ export * from "./patterns/versions/index.js";
 export * from "./patterns/lineage/index.js";
 export * from "./patterns/agent-chat/index.js";
 export * from "./patterns/audit/index.js";
+export * from "./patterns/comments/index.js";
 export * from "./patterns/notifications/index.js";
 export * from "./patterns/search/index.js";
 export * from "./patterns/item/index.js";

package/dist/index.js

@@ -5,6 +5,8 @@ export { DESIGN_SYSTEM_CHANGE_EVENT, SEMANTIC_TOKEN_ALIASES, applyDesignTokens,
 export { DARK_MODE_MEDIA_QUERY, DEFAULT_THEME_STORAGE_KEY, THEME_CHANGE_EVENT, createThemeController, createThemeInitializationScript, } from "./foundations/theming/index.js";
 export { DESIGN_PROFILE_CHANGE_EVENT, DESIGN_PROFILE_VARIABLES, DEFAULT_DESIGN_PROFILE_STORAGE_KEY, applyDesignProfile, boxDefaultDesignProfile, compactNeutralDesignProfile, createDesignProfileController, createDesignProfileStyleText, getDesignProfile, listDesignProfiles, registerBuiltInDesignProfiles, registerDesignProfile, resolveDesignProfileProperties, } from "./foundations/profiles/index.js";
 export { boxIconography, boxIconographyAliases } from "./foundations/icons/index.js";
+// Foundations: Adobe Spectrum's responsive grid (shared by box-grid and box-skeleton)
+export * from "./foundations/layout/index.js";
 // Foundations: viewport-aware overlay positioning (for building custom overlays)
 export { anchorFloating, parsePlacement, resolvePosition, trackAnchor, } from "./foundations/overlay/index.js";
 // Components: actions
@@ -42,12 +44,13 @@ export * from "./components/feedback/progress-ring.js";
 export * from "./components/feedback/progress-steps.js";
 export * from "./components/feedback/skeleton.js";
 export * from "./components/feedback/spinner.js";
-export * from "./components/feedback/stage-path.js";
+export * from "./components/feedback/path.js";
 export * from "./components/feedback/toast.js";
 // Components: files
 export * from "./components/files/drop-zone.js";
 // Components: identity
 export * from "./components/identity/avatar.js";
+export * from "./components/identity/contact-datalist-item.js";
 export * from "./components/identity/persona.js";
 // Components: navigation
 export * from "./components/navigation/accordion.js";
@@ -86,6 +89,7 @@ export * from "./components/forms/text-field.js";
 // Components: layout
 export * from "./components/layout/app-shell.js";
 export * from "./components/layout/divider.js";
+export * from "./components/layout/grid.js";
 export * from "./components/layout/nav-sidebar.js";
 export * from "./components/layout/section.js";
 export * from "./components/layout/sidebar-toggle-button.js";
@@ -115,6 +119,7 @@ export * from "./patterns/versions/index.js";
 export * from "./patterns/lineage/index.js";
 export * from "./patterns/agent-chat/index.js";
 export * from "./patterns/audit/index.js";
+export * from "./patterns/comments/index.js";
 export * from "./patterns/notifications/index.js";
 // Patterns: compositions and workflow areas
 export * from "./patterns/search/index.js";

package/dist/patterns/audit/audit-log.js

@@ -221,7 +221,6 @@ const elementStyles = `
           gap: 0.25rem;
           padding: 0.5rem 0.65rem;
           border-top: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 55%, transparent);
-          border-left: 3px solid var(--audit-tone, transparent);
         }
 
         [part="event-topline"] {

package/dist/patterns/comments/comment-thread.d.ts

@@ -0,0 +1,79 @@
+import { BaseElement } from "../../core/index.js";
+import type { CommentAction, CommentEntry } from "./types.js";
+/**
+ * A comment thread: authored entries, selection, actions, and a composer.
+ *
+ * Comments are a standalone concept. They hang off a file, a folder, a task or
+ * a contract clause just as readily as off a region of a document, so the
+ * thread does not know what it is attached to — a host that needs an anchor
+ * composes one on top. `box-annotation-thread` is exactly that: this component
+ * plus the document anchor, which is the only thing that makes an annotation an
+ * annotation.
+ *
+ * The extension points below (`threadStyles`, `headerExtras`, `defaultHeading`,
+ * `emptyText`, `entryBadge`, and the composer copy) exist so a subclass can
+ * specialise the chrome without reimplementing entry rendering, selection
+ * patching, or the composer.
+ */
+export declare class CommentThread extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    protected titleEl: HTMLElement;
+    protected messageEl: HTMLElement;
+    protected entriesEl: HTMLElement;
+    protected emptyEl: HTMLElement;
+    protected actionsEl: HTMLElement;
+    protected composerEl: HTMLElement;
+    protected composerLabelEl: HTMLElement;
+    protected composerSubmitEl: HTMLElement;
+    protected composerInputEl: HTMLTextAreaElement;
+    private entriesSignature;
+    private actionsSignature;
+    /** Styles for the thread. Subclasses append rather than replace. */
+    protected threadStyles(): string;
+    /** Extra markup inside the header, after the message. Empty by default. */
+    protected headerExtras(): string;
+    /** Heading when the host sets none. */
+    protected defaultHeading(): string;
+    /** Text shown when there are no entries. */
+    protected emptyText(): string;
+    /** Label on the composer, and on its submit button. */
+    protected defaultComposerLabel(): string;
+    /** Placeholder in the composer input. */
+    protected defaultPlaceholder(): string;
+    /**
+     * The pill beside the author. Reads the generic `badge`; a subclass with its
+     * own vocabulary overrides this rather than forcing hosts to rename fields.
+     */
+    protected entryBadge(entry: CommentEntry): string | undefined;
+    get actions(): CommentAction[];
+    set actions(value: CommentAction[]);
+    get composable(): boolean;
+    set composable(value: boolean);
+    get entries(): CommentEntry[];
+    set entries(value: CommentEntry[]);
+    get message(): string;
+    set message(value: string);
+    get selectedEntryId(): string;
+    set selectedEntryId(value: string);
+    get heading(): string;
+    set heading(value: string);
+    /** Composer label and submit-button text. */
+    get composerLabel(): string;
+    set composerLabel(value: string);
+    get placeholder(): string;
+    set placeholder(value: string);
+    protected parseJsonAttribute<T>(name: string, fallback: T): T;
+    private emitAction;
+    private emitEntrySelected;
+    private submitComposer;
+    private entriesKey;
+    private actionsKey;
+    private rebuildEntries;
+    private patchEntrySelection;
+    private rebuildActions;
+    private patchActionLabels;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}