@unofficialbox/box-open-elements 0.3.0 → 0.5.0

package/dist/foundations/profiles/built-ins.js

@@ -0,0 +1,131 @@
+import { registerDesignProfile } from "./registry.js";
+export const boxDefaultDesignProfile = {
+    name: "box-default",
+    description: "Box web-app geometry, density, elevation, typography, and motion.",
+    spacing: {
+        unit: "4px",
+        space1: "4px",
+        space2: "8px",
+        space3: "12px",
+        space4: "16px",
+        space5: "20px",
+        space6: "24px",
+        space8: "32px",
+        space10: "40px",
+        space12: "48px",
+    },
+    radius: {
+        size: "4px",
+        medium: "12px",
+        large: "16px",
+        xlarge: "20px",
+        control: "20px",
+        field: "24px",
+        nav: "28px",
+        pill: "999px",
+    },
+    density: {
+        panelPadding: "12px",
+        panelGap: "12px",
+        overlayPadding: "12px",
+        overlayItemPadding: "8px 48px 8px 8px",
+        overlayItemMinHeight: "30px",
+        modalPadding: "30px",
+        modalWidth: "460px",
+        drawerWidth: "340px",
+        controlHeight: "32px",
+        controlHeightLarge: "40px",
+        controlPaddingInline: "16px",
+        inputPadding: "7px",
+        selectHeight: "34px",
+        disabledOpacity: "0.4",
+    },
+    typography: {
+        fontFamilyBase: "InterVariable, Inter, Lato, 'Helvetica Neue', Helvetica, Arial, sans-serif",
+        controlFontSize: "13px",
+        controlLetterSpacing: "0.035em",
+        modalTitleSize: "16px",
+    },
+    elevation: {
+        panel: "0 1px 2px rgb(15 23 42 / 4%)",
+        overlay: "0 4px 12px 0 rgb(0 0 0 / 10%)",
+        modal: "0 1px 1px 1px rgb(0 0 0 / 5%)",
+        inputInset: "inset 0 2px 4px rgb(0 0 0 / 10%)",
+        primaryFocus: "inset 0 0 0 1px rgb(255 255 255 / 80%), 0 1px 2px rgb(0 0 0 / 10%)",
+    },
+    motion: {
+        fast: "120ms",
+        interactive: "140ms",
+        medium: "160ms",
+        slow: "240ms",
+        spin: "0.8s",
+        shimmer: "1.4s",
+        easingStandard: "ease",
+        easingEnter: "ease-out",
+        easingExit: "ease-in",
+        easingLinear: "linear",
+    },
+};
+export const compactNeutralDesignProfile = {
+    name: "compact-neutral",
+    description: "A denser, restrained application profile for information-heavy tools.",
+    spacing: {
+        space1: "3px",
+        space2: "6px",
+        space3: "10px",
+        space4: "14px",
+        space5: "18px",
+        space6: "20px",
+        space8: "28px",
+        space10: "36px",
+        space12: "44px",
+    },
+    radius: {
+        size: "3px",
+        medium: "6px",
+        large: "8px",
+        xlarge: "10px",
+        control: "6px",
+        field: "8px",
+        nav: "6px",
+        pill: "999px",
+    },
+    density: {
+        panelPadding: "10px",
+        panelGap: "8px",
+        overlayPadding: "6px",
+        overlayItemPadding: "6px 32px 6px 8px",
+        overlayItemMinHeight: "28px",
+        modalPadding: "20px",
+        controlHeight: "28px",
+        controlHeightLarge: "34px",
+        controlPaddingInline: "12px",
+        inputPadding: "5px 7px",
+        selectHeight: "30px",
+    },
+    typography: {
+        fontFamilyBase: "InterVariable, Inter, sans-serif",
+        controlFontSize: "12px",
+        controlLetterSpacing: "0",
+        modalTitleSize: "15px",
+    },
+    elevation: {
+        panel: "0 1px 2px rgb(0 0 0 / 5%)",
+        overlay: "0 8px 24px rgb(0 0 0 / 18%)",
+        modal: "0 12px 32px rgb(0 0 0 / 22%)",
+        inputInset: "none",
+    },
+    motion: {
+        fast: "80ms",
+        interactive: "100ms",
+        medium: "140ms",
+        slow: "180ms",
+        easingStandard: "cubic-bezier(0.2, 0, 0, 1)",
+        easingEnter: "cubic-bezier(0.16, 1, 0.3, 1)",
+        easingExit: "cubic-bezier(0.7, 0, 0.84, 0)",
+    },
+};
+export const registerBuiltInDesignProfiles = () => {
+    registerDesignProfile(boxDefaultDesignProfile);
+    registerDesignProfile(compactNeutralDesignProfile);
+};

package/dist/foundations/profiles/controller.d.ts

@@ -0,0 +1,4 @@
+import type { DesignProfileController, DesignProfileControllerOptions } from "./types.js";
+export declare const DESIGN_PROFILE_CHANGE_EVENT = "boe:design-profile-change";
+export declare const DEFAULT_DESIGN_PROFILE_STORAGE_KEY = "boe-design-profile";
+export declare const createDesignProfileController: (options?: DesignProfileControllerOptions) => DesignProfileController;

package/dist/foundations/profiles/controller.js

@@ -0,0 +1,107 @@
+import { registerBuiltInDesignProfiles } from "./built-ins.js";
+import { applyDesignProfile, getDesignProfile, } from "./registry.js";
+export const DESIGN_PROFILE_CHANGE_EVENT = "boe:design-profile-change";
+export const DEFAULT_DESIGN_PROFILE_STORAGE_KEY = "boe-design-profile";
+const resolveDefaultRoot = () => typeof document === "undefined" ? null : document.documentElement;
+const resolveDefaultStorage = () => {
+    try {
+        return typeof localStorage === "undefined" ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+};
+export const createDesignProfileController = (options = {}) => {
+    const profileAttribute = options.profileAttribute === undefined
+        ? "data-design-profile"
+        : options.profileAttribute;
+    const storageKey = options.storageKey === undefined
+        ? DEFAULT_DESIGN_PROFILE_STORAGE_KEY
+        : options.storageKey;
+    const shouldResolveDefaultStorage = options.storage === undefined;
+    let root = options.root ?? null;
+    let storage = options.storage ?? null;
+    let profileName = options.profile ?? "box-default";
+    let appliedVariables = new Set();
+    let started = false;
+    const apply = () => {
+        if (!root) {
+            throw new Error("DesignProfileController requires a root HTMLElement");
+        }
+        if (!getDesignProfile(profileName)) {
+            throw new Error(`Unknown design profile: ${profileName}`);
+        }
+        const nextVariables = new Set(applyDesignProfile(root, profileName));
+        for (const variable of appliedVariables) {
+            if (!nextVariables.has(variable)) {
+                root.style.removeProperty(variable);
+            }
+        }
+        appliedVariables = nextVariables;
+        if (profileAttribute) {
+            root.setAttribute(profileAttribute, profileName);
+        }
+        if (typeof CustomEvent !== "undefined") {
+            root.dispatchEvent(new CustomEvent(DESIGN_PROFILE_CHANGE_EVENT, {
+                bubbles: true,
+                composed: true,
+                detail: { profileName },
+            }));
+        }
+    };
+    return {
+        start() {
+            if (started) {
+                return;
+            }
+            root ??= resolveDefaultRoot();
+            if (options.registerBuiltIns ?? true) {
+                registerBuiltInDesignProfiles();
+            }
+            if (shouldResolveDefaultStorage) {
+                storage = resolveDefaultStorage();
+            }
+            if (storage && storageKey) {
+                try {
+                    const storedProfile = storage.getItem(storageKey);
+                    if (storedProfile && getDesignProfile(storedProfile)) {
+                        profileName = storedProfile;
+                    }
+                }
+                catch {
+                    // Storage may be unavailable in privacy-restricted or embedded contexts.
+                }
+            }
+            started = true;
+            apply();
+        },
+        stop() {
+            if (!started || !root) {
+                return;
+            }
+            for (const variable of appliedVariables) {
+                root.style.removeProperty(variable);
+            }
+            appliedVariables.clear();
+            if (profileAttribute) {
+                root.removeAttribute(profileAttribute);
+            }
+            started = false;
+        },
+        setProfile(name) {
+            profileName = name;
+            if (started) {
+                apply();
+            }
+            if (storage && storageKey) {
+                try {
+                    storage.setItem(storageKey, name);
+                }
+                catch {
+                    // Storage may be unavailable in privacy-restricted or embedded contexts.
+                }
+            }
+        },
+        getProfile: () => profileName,
+    };
+};

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

@@ -0,0 +1,4 @@
+export { boxDefaultDesignProfile, compactNeutralDesignProfile, registerBuiltInDesignProfiles, } from "./built-ins.js";
+export { DEFAULT_DESIGN_PROFILE_STORAGE_KEY, DESIGN_PROFILE_CHANGE_EVENT, createDesignProfileController, } from "./controller.js";
+export { DESIGN_PROFILE_VARIABLES, applyDesignProfile, createDesignProfileStyleText, getDesignProfile, listDesignProfiles, registerDesignProfile, resolveDesignProfileProperties, } from "./registry.js";
+export type { ApplyDesignProfileOptions, DesignProfileChangeDetail, DesignProfileController, DesignProfileControllerOptions, DesignProfileDefinition, DesignProfileDensity, DesignProfileElevation, DesignProfileMotion, DesignProfileRadius, DesignProfileSpacing, DesignProfileTypography, } from "./types.js";

package/dist/foundations/profiles/index.js

@@ -0,0 +1,3 @@
+export { boxDefaultDesignProfile, compactNeutralDesignProfile, registerBuiltInDesignProfiles, } from "./built-ins.js";
+export { DEFAULT_DESIGN_PROFILE_STORAGE_KEY, DESIGN_PROFILE_CHANGE_EVENT, createDesignProfileController, } from "./controller.js";
+export { DESIGN_PROFILE_VARIABLES, applyDesignProfile, createDesignProfileStyleText, getDesignProfile, listDesignProfiles, registerDesignProfile, resolveDesignProfileProperties, } from "./registry.js";

package/dist/foundations/profiles/registry.d.ts

@@ -0,0 +1,72 @@
+import type { ApplyDesignProfileOptions, DesignProfileDefinition } from "./types.js";
+export declare const DESIGN_PROFILE_VARIABLES: {
+    readonly spacing: {
+        readonly unit: "--boe-profile-space-unit";
+        readonly space1: "--boe-profile-space-1";
+        readonly space2: "--boe-profile-space-2";
+        readonly space3: "--boe-profile-space-3";
+        readonly space4: "--boe-profile-space-4";
+        readonly space5: "--boe-profile-space-5";
+        readonly space6: "--boe-profile-space-6";
+        readonly space8: "--boe-profile-space-8";
+        readonly space10: "--boe-profile-space-10";
+        readonly space12: "--boe-profile-space-12";
+    };
+    readonly radius: {
+        readonly size: "--boe-profile-radius-size";
+        readonly medium: "--boe-profile-radius-medium";
+        readonly large: "--boe-profile-radius-large";
+        readonly xlarge: "--boe-profile-radius-xlarge";
+        readonly control: "--boe-profile-radius-control";
+        readonly field: "--boe-profile-radius-field";
+        readonly nav: "--boe-profile-radius-nav";
+        readonly pill: "--boe-profile-radius-pill";
+    };
+    readonly density: {
+        readonly panelPadding: "--boe-profile-panel-padding";
+        readonly panelGap: "--boe-profile-panel-gap";
+        readonly overlayPadding: "--boe-profile-overlay-padding";
+        readonly overlayItemPadding: "--boe-profile-overlay-item-padding";
+        readonly overlayItemMinHeight: "--boe-profile-overlay-item-min-height";
+        readonly modalPadding: "--boe-profile-modal-padding";
+        readonly modalWidth: "--boe-profile-modal-width";
+        readonly drawerWidth: "--boe-profile-drawer-width";
+        readonly controlHeight: "--boe-profile-control-height";
+        readonly controlHeightLarge: "--boe-profile-control-height-large";
+        readonly controlPaddingInline: "--boe-profile-control-padding-inline";
+        readonly inputPadding: "--boe-profile-input-padding";
+        readonly selectHeight: "--boe-profile-select-height";
+        readonly disabledOpacity: "--boe-profile-disabled-opacity";
+    };
+    readonly typography: {
+        readonly fontFamilyBase: "--boe-profile-font-family-base";
+        readonly controlFontSize: "--boe-profile-control-font-size";
+        readonly controlLetterSpacing: "--boe-profile-control-letter-spacing";
+        readonly modalTitleSize: "--boe-profile-modal-title-size";
+    };
+    readonly elevation: {
+        readonly panel: "--boe-profile-shadow-panel";
+        readonly overlay: "--boe-profile-shadow-overlay";
+        readonly modal: "--boe-profile-shadow-modal";
+        readonly inputInset: "--boe-profile-shadow-input-inset";
+        readonly primaryFocus: "--boe-profile-shadow-primary-focus";
+    };
+    readonly motion: {
+        readonly fast: "--boe-profile-motion-fast";
+        readonly interactive: "--boe-profile-motion-interactive";
+        readonly medium: "--boe-profile-motion-medium";
+        readonly slow: "--boe-profile-motion-slow";
+        readonly spin: "--boe-profile-motion-spin";
+        readonly shimmer: "--boe-profile-motion-shimmer";
+        readonly easingStandard: "--boe-profile-easing-standard";
+        readonly easingEnter: "--boe-profile-easing-enter";
+        readonly easingExit: "--boe-profile-easing-exit";
+        readonly easingLinear: "--boe-profile-easing-linear";
+    };
+};
+export declare const resolveDesignProfileProperties: (definition: DesignProfileDefinition) => Record<string, string>;
+export declare const registerDesignProfile: (definition: DesignProfileDefinition) => DesignProfileDefinition;
+export declare const getDesignProfile: (name: string | null | undefined) => DesignProfileDefinition | null;
+export declare const listDesignProfiles: () => DesignProfileDefinition[];
+export declare const applyDesignProfile: (target: HTMLElement, profileOrName: DesignProfileDefinition | string) => string[];
+export declare const createDesignProfileStyleText: (profileOrName: DesignProfileDefinition | string, options?: ApplyDesignProfileOptions) => string;

package/dist/foundations/profiles/registry.js

@@ -0,0 +1,119 @@
+export const DESIGN_PROFILE_VARIABLES = {
+    spacing: {
+        unit: "--boe-profile-space-unit",
+        space1: "--boe-profile-space-1",
+        space2: "--boe-profile-space-2",
+        space3: "--boe-profile-space-3",
+        space4: "--boe-profile-space-4",
+        space5: "--boe-profile-space-5",
+        space6: "--boe-profile-space-6",
+        space8: "--boe-profile-space-8",
+        space10: "--boe-profile-space-10",
+        space12: "--boe-profile-space-12",
+    },
+    radius: {
+        size: "--boe-profile-radius-size",
+        medium: "--boe-profile-radius-medium",
+        large: "--boe-profile-radius-large",
+        xlarge: "--boe-profile-radius-xlarge",
+        control: "--boe-profile-radius-control",
+        field: "--boe-profile-radius-field",
+        nav: "--boe-profile-radius-nav",
+        pill: "--boe-profile-radius-pill",
+    },
+    density: {
+        panelPadding: "--boe-profile-panel-padding",
+        panelGap: "--boe-profile-panel-gap",
+        overlayPadding: "--boe-profile-overlay-padding",
+        overlayItemPadding: "--boe-profile-overlay-item-padding",
+        overlayItemMinHeight: "--boe-profile-overlay-item-min-height",
+        modalPadding: "--boe-profile-modal-padding",
+        modalWidth: "--boe-profile-modal-width",
+        drawerWidth: "--boe-profile-drawer-width",
+        controlHeight: "--boe-profile-control-height",
+        controlHeightLarge: "--boe-profile-control-height-large",
+        controlPaddingInline: "--boe-profile-control-padding-inline",
+        inputPadding: "--boe-profile-input-padding",
+        selectHeight: "--boe-profile-select-height",
+        disabledOpacity: "--boe-profile-disabled-opacity",
+    },
+    typography: {
+        fontFamilyBase: "--boe-profile-font-family-base",
+        controlFontSize: "--boe-profile-control-font-size",
+        controlLetterSpacing: "--boe-profile-control-letter-spacing",
+        modalTitleSize: "--boe-profile-modal-title-size",
+    },
+    elevation: {
+        panel: "--boe-profile-shadow-panel",
+        overlay: "--boe-profile-shadow-overlay",
+        modal: "--boe-profile-shadow-modal",
+        inputInset: "--boe-profile-shadow-input-inset",
+        primaryFocus: "--boe-profile-shadow-primary-focus",
+    },
+    motion: {
+        fast: "--boe-profile-motion-fast",
+        interactive: "--boe-profile-motion-interactive",
+        medium: "--boe-profile-motion-medium",
+        slow: "--boe-profile-motion-slow",
+        spin: "--boe-profile-motion-spin",
+        shimmer: "--boe-profile-motion-shimmer",
+        easingStandard: "--boe-profile-easing-standard",
+        easingEnter: "--boe-profile-easing-enter",
+        easingExit: "--boe-profile-easing-exit",
+        easingLinear: "--boe-profile-easing-linear",
+    },
+};
+const designProfiles = new Map();
+export const resolveDesignProfileProperties = (definition) => {
+    const properties = {};
+    for (const [sectionName, variableMap] of Object.entries(DESIGN_PROFILE_VARIABLES)) {
+        const section = definition[sectionName];
+        if (!section) {
+            continue;
+        }
+        for (const [propertyName, value] of Object.entries(section)) {
+            const variableName = variableMap[propertyName];
+            if (variableName && value !== undefined) {
+                properties[variableName] = value;
+            }
+        }
+    }
+    for (const [variableName, value] of Object.entries(definition.customProperties ?? {})) {
+        if (properties[variableName] !== undefined) {
+            throw new Error(`Design profile property "${variableName}" was provided by both the typed schema and customProperties`);
+        }
+        properties[variableName] = value;
+    }
+    return properties;
+};
+export const registerDesignProfile = (definition) => {
+    designProfiles.set(definition.name, definition);
+    return definition;
+};
+export const getDesignProfile = (name) => name ? designProfiles.get(name) ?? null : null;
+export const listDesignProfiles = () => Array.from(designProfiles.values());
+const resolveDefinition = (profileOrName) => {
+    if (typeof profileOrName !== "string") {
+        return profileOrName;
+    }
+    const definition = getDesignProfile(profileOrName);
+    if (!definition) {
+        throw new Error(`Unknown design profile: ${profileOrName}`);
+    }
+    return definition;
+};
+export const applyDesignProfile = (target, profileOrName) => {
+    const properties = resolveDesignProfileProperties(resolveDefinition(profileOrName));
+    for (const [name, value] of Object.entries(properties)) {
+        target.style.setProperty(name, value);
+    }
+    return Object.keys(properties);
+};
+export const createDesignProfileStyleText = (profileOrName, options = {}) => {
+    const selector = options.selector ?? ":root";
+    const properties = resolveDesignProfileProperties(resolveDefinition(profileOrName));
+    const declarations = Object.entries(properties)
+        .map(([name, value]) => `  ${name}: ${value};`)
+        .join("\n");
+    return `${selector} {\n${declarations}\n}`;
+};

package/dist/foundations/profiles/types.d.ts

@@ -0,0 +1,94 @@
+export interface DesignProfileSpacing {
+    unit?: string;
+    space1?: string;
+    space2?: string;
+    space3?: string;
+    space4?: string;
+    space5?: string;
+    space6?: string;
+    space8?: string;
+    space10?: string;
+    space12?: string;
+}
+export interface DesignProfileRadius {
+    size?: string;
+    medium?: string;
+    large?: string;
+    xlarge?: string;
+    control?: string;
+    field?: string;
+    nav?: string;
+    pill?: string;
+}
+export interface DesignProfileDensity {
+    panelPadding?: string;
+    panelGap?: string;
+    overlayPadding?: string;
+    overlayItemPadding?: string;
+    overlayItemMinHeight?: string;
+    modalPadding?: string;
+    modalWidth?: string;
+    drawerWidth?: string;
+    controlHeight?: string;
+    controlHeightLarge?: string;
+    controlPaddingInline?: string;
+    inputPadding?: string;
+    selectHeight?: string;
+    disabledOpacity?: string;
+}
+export interface DesignProfileTypography {
+    fontFamilyBase?: string;
+    controlFontSize?: string;
+    controlLetterSpacing?: string;
+    modalTitleSize?: string;
+}
+export interface DesignProfileElevation {
+    panel?: string;
+    overlay?: string;
+    modal?: string;
+    inputInset?: string;
+    primaryFocus?: string;
+}
+export interface DesignProfileMotion {
+    fast?: string;
+    interactive?: string;
+    medium?: string;
+    slow?: string;
+    spin?: string;
+    shimmer?: string;
+    easingStandard?: string;
+    easingEnter?: string;
+    easingExit?: string;
+    easingLinear?: string;
+}
+export interface DesignProfileDefinition {
+    name: string;
+    description?: string;
+    spacing?: DesignProfileSpacing;
+    radius?: DesignProfileRadius;
+    density?: DesignProfileDensity;
+    typography?: DesignProfileTypography;
+    elevation?: DesignProfileElevation;
+    motion?: DesignProfileMotion;
+    customProperties?: Record<`--${string}`, string>;
+}
+export interface DesignProfileChangeDetail {
+    profileName: string;
+}
+export interface DesignProfileController {
+    start(): void;
+    stop(): void;
+    setProfile(name: string): void;
+    getProfile(): string;
+}
+export interface DesignProfileControllerOptions {
+    root?: HTMLElement;
+    profile?: string;
+    registerBuiltIns?: boolean;
+    profileAttribute?: string | null;
+    storageKey?: string | null;
+    storage?: Storage | null;
+}
+export interface ApplyDesignProfileOptions {
+    selector?: string;
+}

package/dist/foundations/profiles/types.js

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

package/dist/foundations/theming/controller.d.ts

@@ -0,0 +1,37 @@
+export declare const THEME_CHANGE_EVENT = "boe:theme-change";
+export declare const DEFAULT_THEME_STORAGE_KEY = "boe-theme";
+export declare const DARK_MODE_MEDIA_QUERY = "(prefers-color-scheme: dark)";
+export type ThemePreference = "light" | "dark" | "system";
+export type ResolvedTheme = Exclude<ThemePreference, "system">;
+export interface ThemeChangeDetail {
+    preference: ThemePreference;
+    resolvedTheme: ResolvedTheme;
+    designSystemName: string;
+}
+export interface ThemeControllerOptions {
+    root?: HTMLElement;
+    preference?: ThemePreference;
+    storageKey?: string | null;
+    storage?: Storage | null;
+    mediaQueryList?: MediaQueryList | null;
+    lightDesignSystem?: string;
+    darkDesignSystem?: string;
+    registerBuiltIns?: boolean;
+    themeAttribute?: string | null;
+    applyColorScheme?: boolean;
+}
+export interface ThemeController {
+    start(): void;
+    stop(): void;
+    toggle(): void;
+    setPreference(preference: ThemePreference): void;
+    getPreference(): ThemePreference;
+    getResolvedTheme(): ResolvedTheme;
+}
+export interface ThemeInitializationScriptOptions {
+    preference?: ThemePreference;
+    storageKey?: string | null;
+    themeAttribute?: string | null;
+}
+export declare const createThemeInitializationScript: (options?: ThemeInitializationScriptOptions) => string;
+export declare const createThemeController: (options?: ThemeControllerOptions) => ThemeController;