@cometchat/card-builder 1.0.1

package/dist/lib.d.ts

@@ -0,0 +1,81 @@
+import type { CardMessage, ElementType } from './types/schema';
+import type { ComponentTemplateName } from './config/component-templates';
+import type { CardVariable, NotificationConfig, BuilderChannels } from './config/builder-config';
+import './index.css';
+export type { CardVariable } from './config/builder-config';
+export type { NotificationConfig, BuilderChannels } from './config/builder-config';
+export interface CardBuilderOptions {
+    /** CometChat app ID (required for template save/load APIs) */
+    appId?: string;
+    /** App region — us, eu, etc. (required for template save/load APIs) */
+    region?: string;
+    /** Bearer token for REST API calls (required for template save/load APIs) */
+    token?: string;
+    /** CometChat REST API Key (required for sending messages) */
+    apiKey?: string;
+    /** Existing card JSON to load for editing */
+    card?: CardMessage;
+    /** Initial notification title (only used when channels includes push). */
+    notificationTitle?: string;
+    /** Initial notification body (only used when channels includes push). */
+    notificationBody?: string;
+    /** Template name */
+    templateName?: string;
+    /** Called when user clicks Save */
+    onSave?: (json: CardMessage, name: string, description: string) => void;
+    /** Called whenever the card JSON changes (any edit). Use for real-time sync. */
+    onChange?: (json: CardMessage) => void;
+    /** Available variables for {{placeholder}} insertion in text/URL fields */
+    variables?: CardVariable[];
+    /** Hide the top toolbar (save, export, import, undo/redo, template name). Default: false */
+    hideTopBar?: boolean;
+    /** Hide the template library view — go straight to editor. Default: false */
+    hideTemplateLibrary?: boolean;
+    /** Disable all editing interactions — read-only preview mode. Default: false */
+    readOnly?: boolean;
+    /** Show the variable editor tab for creating/managing variables in the builder. Default: true */
+    enableVariableEditor?: boolean;
+    /** Which channels to show: 'inapp', 'push', or 'both' (default). */
+    channels?: BuilderChannels;
+    /** Push notification preview config (app name, icon). Only used when channels is 'push' or 'both'. */
+    notification?: NotificationConfig;
+    /** Element types to hide from the palette (e.g. ['codeBlock', 'table', 'markdown']) */
+    hiddenElements?: ElementType[];
+    /** Component template names to hide from the palette (e.g. ['Product Card', 'Data Table']) */
+    hiddenComponents?: ComponentTemplateName[];
+    /** Hide the left panel (elements & components palette). Default: false */
+    hideElementPalette?: boolean;
+    /** Hide the right panel (tree, element properties, card settings). Default: false */
+    hidePropertyPanel?: boolean;
+    /** Show the canvas toolbar (zoom, dark mode, preview, JSON). Default: false */
+    showCanvasToolbar?: boolean;
+}
+export interface CardBuilderInstance {
+    loadCard: (card: CardMessage, name?: string) => void;
+    getCardJSON: () => CardMessage;
+    setVariables: (variables: CardVariable[]) => void;
+    setChannels: (channels: BuilderChannels) => void;
+    setCanvasView: (view: 'card' | 'notification') => void;
+    setReadOnly: (readOnly: boolean) => void;
+    /** Hide specific element types from the palette. Pass element type names (e.g. 'codeBlock', 'table'). */
+    setHiddenElements: (types: ElementType[]) => void;
+    /** Hide specific component templates from the palette. Pass template names (e.g. 'Product Card'). */
+    setHiddenComponents: (names: ComponentTemplateName[]) => void;
+    /** Show or hide the left panel at runtime. */
+    setHideElementPalette: (hide: boolean) => void;
+    /** Show or hide the right panel at runtime. */
+    setHidePropertyPanel: (hide: boolean) => void;
+    /** Show or hide the canvas toolbar at runtime. */
+    setShowCanvasToolbar: (show: boolean) => void;
+    /** Set notification title at runtime. */
+    setNotificationTitle: (title: string) => void;
+    /** Set notification body at runtime. */
+    setNotificationBody: (body: string) => void;
+    /** Set API key at runtime. */
+    setApiKey: (apiKey: string) => void;
+    destroy: () => void;
+}
+export { builderConfig } from './config/builder-config';
+export declare function mountCardBuilder(container: HTMLElement, options: CardBuilderOptions): CardBuilderInstance;
+export type { CardMessage, ElementType } from './types/schema';
+export type { ComponentTemplateName } from './config/component-templates';

package/dist/store/builder-store.d.ts

@@ -0,0 +1,127 @@
+import type { CardElement, CardStyle, CardMessage, Template, ElementType, MessageData } from '../types/schema';
+import type { ComponentTemplateName } from '../config/component-templates';
+import { type CardVariable } from '../config/builder-config';
+export interface BuilderState {
+    templateId: string | null;
+    templateName: string;
+    templateDescription: string;
+    body: CardElement[];
+    style: CardStyle;
+    fallbackText: string;
+    notificationTitle: string;
+    notificationBody: string;
+    notificationData: Array<{
+        key: string;
+        value: string;
+    }>;
+    /** Custom message type for CometChat message structure (e.g. 'product', 'order') */
+    messageType: string;
+    notificationEnabled: boolean;
+    /** Which view the canvas shows: card editor or notification preview */
+    canvasView: 'card' | 'notification';
+    /** Which channels are available */
+    channels: 'inapp' | 'push' | 'both';
+    /** Whether channels was explicitly set (vs default) */
+    channelsExplicit: boolean;
+    /** Read-only mode — disables all editing interactions */
+    readOnly: boolean;
+    selectedPath: number[] | null;
+    selectedPaths: number[][];
+    isDirty: boolean;
+    useThemePlaceholders: boolean;
+    /** Element types hidden from the palette */
+    hiddenElements: Set<ElementType>;
+    /** Component template names hidden from the palette */
+    hiddenComponents: Set<ComponentTemplateName>;
+    view: 'library' | 'editor';
+    clipboard: CardElement | null;
+    showTemplatePicker: boolean;
+    /** Hide the left panel (elements & components palette) */
+    hideElementPalette: boolean;
+    /** Hide the right panel (tree, element properties, card settings) */
+    hidePropertyPanel: boolean;
+    /** Show the canvas toolbar (zoom, dark mode, preview, JSON). Default: false */
+    showCanvasToolbar: boolean;
+    /** Show the variable editor tab. Default: true */
+    enableVariableEditor: boolean;
+    variables: CardVariable[];
+    history: {
+        body: CardElement[];
+        style: CardStyle;
+    }[];
+    historyIndex: number;
+    templates: Template[];
+    templatesLoading: boolean;
+    templatesMeta: {
+        previous?: {
+            affix: string;
+            createdAt: number;
+        };
+        next?: {
+            affix: string;
+            createdAt: number;
+        };
+    } | null;
+    setView: (view: 'library' | 'editor') => void;
+    setShowTemplatePicker: (show: boolean) => void;
+    setHideElementPalette: (hide: boolean) => void;
+    setHidePropertyPanel: (hide: boolean) => void;
+    setShowCanvasToolbar: (show: boolean) => void;
+    setEnableVariableEditor: (enable: boolean) => void;
+    selectElement: (path: number[] | null) => void;
+    toggleSelectElement: (path: number[]) => void;
+    addElement: (element: CardElement, parentPath?: number[]) => void;
+    updateElement: (path: number[], updates: Partial<CardElement>) => void;
+    removeElement: (path: number[]) => void;
+    moveElement: (path: number[], direction: 'up' | 'down') => void;
+    updateStyle: (settings: Partial<CardStyle>) => void;
+    setFallbackText: (text: string) => void;
+    setNotificationTitle: (text: string) => void;
+    setNotificationBody: (text: string) => void;
+    setMessageType: (type: string) => void;
+    setNotificationData: (data: Array<{
+        key: string;
+        value: string;
+    }>) => void;
+    setNotificationEnabled: (enabled: boolean) => void;
+    setCanvasView: (view: 'card' | 'notification') => void;
+    setChannels: (channels: 'inapp' | 'push' | 'both') => void;
+    setReadOnly: (readOnly: boolean) => void;
+    setHiddenElements: (types: ElementType[]) => void;
+    setHiddenComponents: (names: ComponentTemplateName[]) => void;
+    setUseThemePlaceholders: (use: boolean) => void;
+    setVariables: (variables: CardVariable[]) => void;
+    addVariable: (variable: CardVariable) => void;
+    updateVariable: (index: number, variable: CardVariable) => void;
+    removeVariable: (index: number) => void;
+    setTemplateName: (name: string) => void;
+    setTemplateDescription: (desc: string) => void;
+    loadCard: (card: CardMessage, templateId?: string, name?: string, desc?: string) => void;
+    loadTemplate: (template: Template) => void;
+    newCard: () => void;
+    getCardJSON: (opts?: {
+        stripEmpty?: boolean;
+    }) => CardMessage;
+    /** Get the full CometChat message structure wrapping the card (used when channels not set) */
+    getMessageJSON: () => MessageData;
+    setTemplates: (templates: Template[]) => void;
+    fetchTemplates: (search?: string) => Promise<void>;
+    fetchNextPage: () => Promise<void>;
+    fetchPrevPage: () => Promise<void>;
+    saveTemplate: () => Promise<void>;
+    deleteTemplate: (id: string) => Promise<void>;
+    reorderElement: (fromPath: number[], toPath: number[], toIndex: number) => void;
+    moveElementToPath: (fromPath: number[], toParentPath: number[], toIndex: number) => void;
+    wrapElement: (path: number[], wrapperType: 'row' | 'column' | 'grid') => void;
+    unwrapElement: (path: number[]) => void;
+    wrapSelected: (wrapperType: 'row' | 'column' | 'grid') => void;
+    duplicateElement: (path: number[]) => void;
+    copyElement: (path: number[]) => void;
+    pasteElement: (targetPath?: number[]) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    clearAll: () => void;
+}
+export declare const useBuilderStore: import("zustand").UseBoundStore<import("zustand").StoreApi<BuilderState>>;

package/dist/types/schema.d.ts

@@ -0,0 +1,338 @@
+export type Padding = number | {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+export type SizeOrPercentage = number | string;
+export type ColorValue = {
+    light: string;
+    dark: string;
+} | 'transparent';
+/** Resolve a ColorValue to a hex string for the given mode. Returns 'transparent' for "transparent". */
+export declare function resolveColor(cv: ColorValue | undefined, mode?: 'light' | 'dark'): string | undefined;
+/** Create a ColorValue from a single hex (same for both modes). */
+export declare function colorVal(hex: string): ColorValue;
+/** Create a ColorValue with distinct light/dark values. */
+export declare function colorValLD(light?: string, dark?: string): ColorValue;
+export interface OpenUrlAction {
+    type: 'openUrl';
+    url: string;
+    openIn?: 'browser' | 'webview';
+}
+export interface ChatWithUserAction {
+    type: 'chatWithUser';
+    uid: string;
+}
+export interface ChatWithGroupAction {
+    type: 'chatWithGroup';
+    guid: string;
+}
+export interface SendMessageAction {
+    type: 'sendMessage';
+    text: string;
+    receiverUid?: string;
+    receiverGuid?: string;
+}
+export interface CopyToClipboardAction {
+    type: 'copyToClipboard';
+    value: string;
+}
+export interface DownloadFileAction {
+    type: 'downloadFile';
+    url: string;
+    filename?: string;
+}
+export interface InitiateCallAction {
+    type: 'initiateCall';
+    uid?: string;
+    guid?: string;
+    callType: 'audio' | 'video';
+}
+export interface ApiCallAction {
+    type: 'apiCall';
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: Record<string, unknown>;
+}
+export interface CustomCallbackAction {
+    type: 'customCallback';
+}
+export type CardAction = OpenUrlAction | ChatWithUserAction | ChatWithGroupAction | SendMessageAction | CopyToClipboardAction | DownloadFileAction | InitiateCallAction | ApiCallAction | CustomCallbackAction;
+export declare const ACTION_TYPES: readonly ["openUrl", "chatWithUser", "chatWithGroup", "sendMessage", "copyToClipboard", "downloadFile", "initiateCall", "apiCall", "customCallback"];
+export type ActionType = typeof ACTION_TYPES[number];
+/** Reference to an icon. Use 'name' for built-in icons, 'url' for custom icon URLs. If both present, url takes precedence. */
+export interface IconRef {
+    name?: string;
+    url?: string;
+}
+export interface TextElement {
+    id: string;
+    type: 'text';
+    content: string;
+    variant?: 'title' | 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'body' | 'caption1' | 'caption2';
+    color?: ColorValue;
+    align?: 'left' | 'center' | 'right' | 'justify';
+    fontWeight?: 'regular' | 'medium' | 'bold';
+    maxLines?: number;
+    padding?: Padding;
+}
+export interface ImageElement {
+    id: string;
+    type: 'image';
+    url: string;
+    altText?: string;
+    fit?: 'cover' | 'contain' | 'fill';
+    width?: SizeOrPercentage;
+    height?: SizeOrPercentage;
+    borderRadius?: number;
+    padding?: Padding;
+}
+export interface IconElement {
+    id: string;
+    type: 'icon';
+    name?: string;
+    url?: string;
+    size?: number;
+    color?: ColorValue;
+    backgroundColor?: ColorValue;
+    borderRadius?: number;
+    padding?: number;
+}
+export interface AvatarElement {
+    id: string;
+    type: 'avatar';
+    imageUrl?: string;
+    fallbackInitials?: string;
+    size?: number;
+    borderRadius?: number;
+    backgroundColor?: ColorValue;
+    fontSize?: number;
+    fontWeight?: 'regular' | 'medium' | 'bold';
+}
+export interface BadgeElement {
+    id: string;
+    type: 'badge';
+    text: string;
+    color?: ColorValue;
+    size?: number;
+    backgroundColor?: ColorValue;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+    borderRadius?: number;
+    padding?: Padding;
+    fontSize?: number;
+}
+export interface DividerElement {
+    id: string;
+    type: 'divider';
+    color?: ColorValue;
+    thickness?: number;
+    margin?: number;
+}
+export interface SpacerElement {
+    id: string;
+    type: 'spacer';
+    height: number;
+}
+export interface ChipElement {
+    id: string;
+    type: 'chip';
+    text: string;
+    color?: ColorValue;
+    icon?: IconRef;
+    backgroundColor?: ColorValue;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+    borderRadius?: number;
+    padding?: Padding;
+    fontSize?: number;
+}
+export interface ProgressBarElement {
+    id: string;
+    type: 'progressBar';
+    value: number;
+    color?: ColorValue;
+    trackColor?: ColorValue;
+    height?: number;
+    label?: string;
+    borderRadius?: number;
+    labelFontSize?: number;
+    labelColor?: ColorValue;
+}
+export interface CodeBlockElement {
+    id: string;
+    type: 'codeBlock';
+    content: string;
+    language?: string;
+    backgroundColor?: ColorValue;
+    textColor?: ColorValue;
+    padding?: Padding;
+    borderRadius?: number;
+    fontSize?: number;
+    languageLabelFontSize?: number;
+    languageLabelColor?: ColorValue;
+}
+export interface MarkdownElement {
+    id: string;
+    type: 'markdown';
+    content: string;
+    baseFontSize?: number;
+    linkColor?: ColorValue;
+    color?: ColorValue;
+    lineHeight?: number;
+}
+export interface RowElement {
+    id: string;
+    type: 'row';
+    items: CardElement[];
+    gap?: number;
+    align?: 'start' | 'center' | 'end' | 'spaceBetween' | 'spaceAround';
+    crossAlign?: 'start' | 'center' | 'end';
+    wrap?: boolean;
+    scrollable?: boolean;
+    peek?: number;
+    snap?: 'item' | 'free';
+    padding?: Padding;
+    backgroundColor?: ColorValue;
+    borderRadius?: number;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+}
+export interface ColumnElement {
+    id: string;
+    type: 'column';
+    items: CardElement[];
+    gap?: number;
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    crossAlign?: 'start' | 'center' | 'end';
+    padding?: Padding;
+    backgroundColor?: ColorValue;
+    borderRadius?: number;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+}
+export interface GridElement {
+    id: string;
+    type: 'grid';
+    items: CardElement[];
+    columns?: 2 | 3 | 4;
+    gap?: number;
+    padding?: Padding;
+    backgroundColor?: ColorValue;
+    borderRadius?: number;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+}
+export interface AccordionElement {
+    id: string;
+    type: 'accordion';
+    header: string;
+    headerIcon?: IconRef;
+    body: CardElement[];
+    expandedByDefault?: boolean;
+    border?: boolean;
+    padding?: Padding;
+    fontSize?: number;
+    fontWeight?: 'regular' | 'medium' | 'bold';
+    borderRadius?: number;
+}
+export interface TabsElement {
+    id: string;
+    type: 'tabs';
+    tabs: {
+        label: string;
+        content: CardElement[];
+    }[];
+    defaultActiveTab?: number;
+    tabAlign?: 'start' | 'center' | 'stretch';
+    tabPadding?: Padding;
+    contentPadding?: Padding;
+    fontSize?: number;
+}
+export interface ButtonElement {
+    id: string;
+    type: 'button';
+    label: string;
+    action: CardAction;
+    backgroundColor?: ColorValue;
+    textColor?: ColorValue;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+    borderRadius?: number;
+    icon?: IconRef;
+    iconPosition?: 'left' | 'right';
+    size?: number;
+    fullWidth?: boolean;
+    padding?: Padding;
+    fontSize?: number;
+}
+export interface IconButtonElement {
+    id: string;
+    type: 'iconButton';
+    icon: IconRef;
+    action: CardAction;
+    size?: number;
+    color?: ColorValue;
+    backgroundColor?: ColorValue;
+    borderRadius?: number;
+}
+export interface LinkElement {
+    id: string;
+    type: 'link';
+    text: string;
+    action: CardAction;
+    color?: ColorValue;
+    underline?: boolean;
+    fontSize?: number;
+}
+export interface TableElement {
+    id: string;
+    type: 'table';
+    columns: string[];
+    rows: string[][];
+    headerBackgroundColor?: ColorValue;
+    border?: boolean;
+    stripedRows?: boolean;
+    cellPadding?: number;
+    fontSize?: number;
+    stripedRowColor?: ColorValue;
+    borderColor?: ColorValue;
+}
+export type CardElement = TextElement | ImageElement | IconElement | AvatarElement | BadgeElement | DividerElement | SpacerElement | ChipElement | ProgressBarElement | CodeBlockElement | MarkdownElement | RowElement | ColumnElement | GridElement | AccordionElement | TabsElement | ButtonElement | IconButtonElement | LinkElement | TableElement;
+export type ElementType = CardElement['type'];
+export interface CardStyle {
+    background?: ColorValue;
+    borderRadius?: number;
+    borderColor?: ColorValue;
+    borderWidth?: number;
+    padding?: Padding;
+}
+export interface CardMessage {
+    version: '1.0';
+    body: CardElement[];
+    style?: CardStyle;
+    fallbackText: string;
+}
+export interface MessageData {
+    category: string;
+    type: string;
+    data: {
+        text: string;
+        card: CardMessage;
+    };
+}
+export interface Template {
+    id: string;
+    name: string;
+    description?: string;
+    schemaVersion?: string;
+    messageData: MessageData;
+    thumbnail?: string;
+    createdBy?: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare function isContainerElement(el: CardElement): el is RowElement | ColumnElement | GridElement | AccordionElement;
+export declare function getContainerChildren(el: CardElement): CardElement[] | null;

package/dist/utils/element-errors.d.ts

@@ -0,0 +1,9 @@
+import type { CardElement } from '../types/schema';
+export interface FieldError {
+    field: string;
+    message: string;
+}
+/** Returns field-level validation errors for a single element. */
+export declare function getElementErrors(el: CardElement): FieldError[];
+/** Quick check: does this element have any errors? Useful for tree indicators. */
+export declare function hasElementErrors(el: CardElement): boolean;

package/dist/utils/id.d.ts

@@ -0,0 +1,4 @@
+export declare function generateId(type: string): string;
+import type { CardElement } from '../types/schema';
+/** Recursively assign IDs to all elements that don't have one */
+export declare function assignIds(elements: CardElement[]): CardElement[];

package/dist/utils/portal-root.d.ts

@@ -0,0 +1,2 @@
+export declare function setPortalRoot(el: HTMLElement): void;
+export declare function getPortalRoot(): HTMLElement;

package/dist/utils/validate.d.ts

@@ -0,0 +1,6 @@
+import type { CardMessage } from '../types/schema';
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+export declare function validateCard(card: CardMessage): ValidationError[];

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@cometchat/card-builder",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "dist/bubble-builder.umd.js",
+  "module": "dist/bubble-builder.es.js",
+  "types": "dist/lib.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/bubble-builder.es.js",
+      "require": "./dist/bubble-builder.umd.js",
+      "types": "./dist/lib.d.ts"
+    },
+    "./style.css": "./dist/bubble-builder.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "build:lib": "tsc -b && vite build --mode lib && tsc -p tsconfig.lib.json",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "lucide-react": "^1.6.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "zustand": "^5.0.12"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "postcss-prefix-selector": "^2.1.1",
+    "postcss-pxtorem": "^6.1.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vite": "^8.0.1",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}