@stackable-labs/sdk-extension-contracts 1.29.0 → 1.31.0

package/dist/index.d.ts

@@ -27,22 +27,296 @@ interface ApiError {
 
 /**
  * UI Component Contract
- * Defines the fixed set of UI tags that extensions can render.
- * The host maps these to real React components.
+ *
+ * Single source of truth for all UI tag metadata. Every other export
+ * in this file is derived from UI_TAG_DEFINITIONS.
+ *
+ * To add a new component:
+ * 1. Add an entry to UI_TAG_DEFINITIONS
+ * 2. Add a host wrapper in embeddables/src/lib/hostComponents.tsx
+ * 3. Run `pnpm check:values` to verify consistency
  */
-declare const UI_TAGS: readonly ["ui-card", "ui-card-content", "ui-card-header", "ui-button", "ui-text", "ui-heading", "ui-badge", "ui-input", "ui-textarea", "ui-select", "ui-select-option", "ui-checkbox", "ui-switch", "ui-label", "ui-radio-group", "ui-radio-group-item", "ui-stack", "ui-inline", "ui-separator", "ui-tabs", "ui-tabs-list", "ui-tabs-trigger", "ui-tabs-content", "ui-scroll-area", "ui-avatar", "ui-icon", "ui-link", "ui-menu", "ui-menu-item", "ui-skeleton", "ui-tooltip", "ui-progress", "ui-alert", "ui-collapsible", "ui-collapsible-trigger", "ui-collapsible-content"];
-type UITag = (typeof UI_TAGS)[number];
+type UITagCategory = 'layout' | 'text' | 'input' | 'feedback' | 'navigation' | 'composite';
+declare const UI_TAG_DEFINITIONS: {
+    readonly 'ui-card': {
+        readonly description: "Card container for grouping related content";
+        readonly icon: "square";
+        readonly category: "layout";
+        readonly attributes: readonly ["className", "onClick"];
+        readonly children: readonly ["ui-card-header", "ui-card-content"];
+    };
+    readonly 'ui-card-content': {
+        readonly description: "Content area within a Card";
+        readonly icon: "square";
+        readonly category: "layout";
+        readonly attributes: readonly ["className"];
+    };
+    readonly 'ui-card-header': {
+        readonly description: "Header area within a Card";
+        readonly icon: "square";
+        readonly category: "layout";
+        readonly attributes: readonly ["className"];
+    };
+    readonly 'ui-button': {
+        readonly description: "Interactive button with variant and size options";
+        readonly icon: "mouse-pointer-click";
+        readonly category: "input";
+        readonly attributes: readonly ["variant", "size", "disabled", "onClick", "type", "className", "title"];
+        readonly attributeValues: {
+            readonly variant: readonly ["default", "destructive", "outline", "secondary", "ghost", "link"];
+            readonly size: readonly ["default", "xs", "sm", "lg", "icon"];
+        };
+    };
+    readonly 'ui-text': {
+        readonly description: "Paragraph text";
+        readonly icon: "type";
+        readonly category: "text";
+        readonly attributes: readonly ["className", "tone"];
+        readonly attributeValues: {
+            readonly tone: readonly ["default", "muted", "destructive"];
+        };
+    };
+    readonly 'ui-heading': {
+        readonly description: "Heading element (h1–h6)";
+        readonly icon: "heading";
+        readonly category: "text";
+        readonly attributes: readonly ["level", "className"];
+        readonly attributeValues: {
+            readonly level: readonly ["1", "2", "3", "4", "5", "6"];
+        };
+    };
+    readonly 'ui-badge': {
+        readonly description: "Small label for status, category, or count";
+        readonly icon: "tag";
+        readonly category: "text";
+        readonly attributes: readonly ["variant", "hue", "tone", "className"];
+        readonly attributeValues: {
+            readonly variant: readonly ["default", "secondary", "destructive", "outline", "ghost", "link"];
+            readonly hue: readonly ["amber", "blue", "emerald", "red", "purple", "pink", "gray"];
+            readonly tone: readonly ["default", "muted", "destructive"];
+        };
+    };
+    readonly 'ui-input': {
+        readonly description: "Single-line text input field";
+        readonly icon: "text-cursor-input";
+        readonly category: "input";
+        readonly attributes: readonly ["type", "placeholder", "value", "onChange", "disabled", "className", "id"];
+    };
+    readonly 'ui-textarea': {
+        readonly description: "Multi-line text input field";
+        readonly icon: "text";
+        readonly category: "input";
+        readonly attributes: readonly ["placeholder", "value", "onChange", "disabled", "rows", "className", "id"];
+    };
+    readonly 'ui-select': {
+        readonly description: "Dropdown select with options";
+        readonly icon: "chevrons-up-down";
+        readonly category: "input";
+        readonly attributes: readonly ["value", "defaultValue", "onChange", "placeholder", "disabled", "className"];
+        readonly children: readonly ["ui-select-option"];
+    };
+    readonly 'ui-select-option': {
+        readonly description: "Option within a Select dropdown";
+        readonly icon: "chevrons-up-down";
+        readonly category: "input";
+        readonly attributes: readonly ["value", "disabled", "className"];
+    };
+    readonly 'ui-checkbox': {
+        readonly description: "Checkbox toggle for boolean values";
+        readonly icon: "square-check";
+        readonly category: "input";
+        readonly attributes: readonly ["checked", "onChange", "disabled", "className", "id"];
+    };
+    readonly 'ui-switch': {
+        readonly description: "Toggle switch for on/off states";
+        readonly icon: "toggle-left";
+        readonly category: "input";
+        readonly attributes: readonly ["checked", "onChange", "disabled", "size", "className", "id"];
+        readonly attributeValues: {
+            readonly size: readonly ["sm", "default"];
+        };
+    };
+    readonly 'ui-label': {
+        readonly description: "Form label associated with an input";
+        readonly icon: "tag";
+        readonly category: "input";
+        readonly attributes: readonly ["htmlFor", "className"];
+    };
+    readonly 'ui-radio-group': {
+        readonly description: "Group of radio buttons for single selection";
+        readonly icon: "circle-dot";
+        readonly category: "input";
+        readonly attributes: readonly ["value", "defaultValue", "onChange", "className"];
+        readonly children: readonly ["ui-radio-group-item", "ui-label", "ui-inline"];
+    };
+    readonly 'ui-radio-group-item': {
+        readonly description: "Individual radio button within a RadioGroup";
+        readonly icon: "circle-dot";
+        readonly category: "input";
+        readonly attributes: readonly ["value", "disabled", "className", "id"];
+    };
+    readonly 'ui-stack': {
+        readonly description: "Vertical or horizontal flex container with gap";
+        readonly icon: "rows-3";
+        readonly category: "layout";
+        readonly attributes: readonly ["gap", "direction", "className"];
+        readonly attributeValues: {
+            readonly direction: readonly ["row", "column"];
+            readonly gap: readonly ["0", "1", "2", "3", "4", "5", "6", "8", "10", "12"];
+        };
+    };
+    readonly 'ui-inline': {
+        readonly description: "Horizontal flex container with centered items";
+        readonly icon: "columns-3";
+        readonly category: "layout";
+        readonly attributes: readonly ["gap", "className"];
+        readonly attributeValues: {
+            readonly gap: readonly ["0", "1", "2", "3", "4", "5", "6", "8", "10", "12"];
+        };
+    };
+    readonly 'ui-separator': {
+        readonly description: "Horizontal divider line";
+        readonly icon: "minus";
+        readonly category: "layout";
+        readonly attributes: readonly ["className"];
+    };
+    readonly 'ui-tabs': {
+        readonly description: "Tabbed content container";
+        readonly icon: "panel-top";
+        readonly category: "navigation";
+        readonly attributes: readonly ["defaultValue", "className"];
+        readonly children: readonly ["ui-tabs-list", "ui-tabs-content"];
+    };
+    readonly 'ui-tabs-list': {
+        readonly description: "Container for tab triggers";
+        readonly icon: "panel-top";
+        readonly category: "navigation";
+        readonly attributes: readonly ["className"];
+        readonly children: readonly ["ui-tabs-trigger"];
+    };
+    readonly 'ui-tabs-trigger': {
+        readonly description: "Clickable tab label within TabsList";
+        readonly icon: "panel-top";
+        readonly category: "navigation";
+        readonly attributes: readonly ["value", "className"];
+    };
+    readonly 'ui-tabs-content': {
+        readonly description: "Content panel shown when its tab is active";
+        readonly icon: "panel-top";
+        readonly category: "navigation";
+        readonly attributes: readonly ["value", "className"];
+    };
+    readonly 'ui-scroll-area': {
+        readonly description: "Scrollable content container";
+        readonly icon: "scroll";
+        readonly category: "layout";
+        readonly attributes: readonly ["className"];
+    };
+    readonly 'ui-avatar': {
+        readonly description: "User avatar with image and initials fallback";
+        readonly icon: "circle-user";
+        readonly category: "composite";
+        readonly attributes: readonly ["src", "alt", "className"];
+    };
+    readonly 'ui-icon': {
+        readonly description: "Icon from the allowed icon set";
+        readonly icon: "sparkles";
+        readonly category: "composite";
+        readonly attributes: readonly ["name", "size", "className"];
+        readonly attributeValues: {
+            readonly size: readonly ["sm", "md", "lg"];
+        };
+    };
+    readonly 'ui-link': {
+        readonly description: "Hyperlink element";
+        readonly icon: "link";
+        readonly category: "navigation";
+        readonly attributes: readonly ["href", "target", "rel", "className"];
+    };
+    readonly 'ui-menu': {
+        readonly description: "Card-based menu with clickable items";
+        readonly icon: "menu";
+        readonly category: "navigation";
+        readonly attributes: readonly ["title", "className"];
+        readonly children: readonly ["ui-menu-item"];
+    };
+    readonly 'ui-menu-item': {
+        readonly description: "Clickable item within a Menu";
+        readonly icon: "menu";
+        readonly category: "navigation";
+        readonly attributes: readonly ["icon", "label", "description", "onClick", "className"];
+    };
+    readonly 'ui-skeleton': {
+        readonly description: "Loading placeholder with shimmer effect";
+        readonly icon: "loader";
+        readonly category: "feedback";
+        readonly attributes: readonly ["width", "height", "className"];
+    };
+    readonly 'ui-tooltip': {
+        readonly description: "Hover tooltip with text content";
+        readonly icon: "message-square";
+        readonly category: "feedback";
+        readonly attributes: readonly ["content", "className"];
+    };
+    readonly 'ui-progress': {
+        readonly description: "Progress bar with percentage value";
+        readonly icon: "bar-chart";
+        readonly category: "feedback";
+        readonly attributes: readonly ["value", "className"];
+    };
+    readonly 'ui-alert': {
+        readonly description: "Alert banner with icon and optional title";
+        readonly icon: "alert-circle";
+        readonly category: "feedback";
+        readonly attributes: readonly ["variant", "title", "className"];
+        readonly attributeValues: {
+            readonly variant: readonly ["default", "destructive"];
+        };
+    };
+    readonly 'ui-collapsible': {
+        readonly description: "Expandable/collapsible content section";
+        readonly icon: "chevrons-down-up";
+        readonly category: "composite";
+        readonly attributes: readonly ["defaultOpen", "className"];
+        readonly children: readonly ["ui-collapsible-trigger", "ui-collapsible-content"];
+    };
+    readonly 'ui-collapsible-trigger': {
+        readonly description: "Clickable trigger to toggle Collapsible";
+        readonly icon: "chevrons-down-up";
+        readonly category: "composite";
+        readonly attributes: readonly ["className"];
+    };
+    readonly 'ui-collapsible-content': {
+        readonly description: "Content revealed when Collapsible is open";
+        readonly icon: "chevrons-down-up";
+        readonly category: "composite";
+        readonly attributes: readonly ["className"];
+    };
+};
+/** Union type of all valid UI tag names */
+type UITag = keyof typeof UI_TAG_DEFINITIONS;
+/** All valid UI tag names */
+declare const UI_TAGS: readonly UITag[];
+/** Allowed attributes per UI tag. Host should reject any not in this list. */
+declare const UI_TAG_ATTRIBUTES: Record<UITag, readonly string[]>;
 /**
- * Allowed attributes per UI tag.
- * Host should reject any attributes not in this allowlist.
+ * Valid attribute values per UI tag (for attributes with enumerable options).
+ * Cross-referenced from hostComponents.tsx type casts and @workspace/ui CVA definitions.
  */
-declare const UI_TAG_ATTRIBUTES: Record<UITag, readonly string[]>;
+declare const UI_TAG_ATTRIBUTE_VALUES: Partial<Record<UITag, Record<string, readonly string[]>>>;
 /**
  * Valid children per parent UI tag.
  * Only parents with strict composition rules are listed.
  * Host should warn (not block) when children violate these rules.
  */
 declare const UI_TAG_CHILDREN: Partial<Record<UITag, readonly UITag[]>>;
+/** Category for each UI tag — used for grouping in stories and palettes. */
+declare const UI_TAG_CATEGORIES: Record<UITag, UITagCategory>;
+/**
+ * Convert a UI tag to its PascalCase component name.
+ * e.g., 'ui-card-content' → 'CardContent'
+ */
+declare const tagToComponentName: (tag: UITag) => string;
 /**
  * Supported icon names (subset of lucide-react).
  * Extensions reference icons by name; host renders the actual icon component.
@@ -93,9 +367,20 @@ interface ToastPayload {
     /** Error message shown when fetch rejects (requires fetch) */
     error?: string;
 }
+/**
+ * Messenger commands supported by the Zendesk Web Widget (zE('messenger', command)).
+ * NOTE: These only apply in floating mode. In embedded mode (mode: 'embedded'),
+ * these are no-ops — the widget renders into target DOM elements and has no
+ * launcher button or floating panel to show/hide.
+ */
+type MessengerCommand = 'open' | 'close' | 'show' | 'hide';
+/** Widget-only actions handled by WidgetComponent (not forwarded to Zendesk) */
+type WidgetAction = 'toggle';
+/** Known actions for actions.invoke capability */
+type InvokeAction = 'newConversation' | MessengerCommand | WidgetAction;
 /** Payload for actions.invoke capability */
 interface ActionInvokePayload {
-    action: string;
+    action: InvokeAction;
     payload?: Record<string, unknown>;
 }
 /** Context returned by context.read capability */
@@ -494,4 +779,4 @@ interface Order {
     display_status?: OrderStatus;
 }
 
-export { ALLOWED_ICONS, type ActionInvokePayload, type Address, type AllowedIconName, type ApiError, type ApiRequest, type ApiResponse, CAPABILITY_PERMISSION_MAP, type CapabilityCall, type CapabilityRequest, type CapabilityResponse, type CapabilityType, type ContextData, type Customer, type DataField, type DataFieldType, type EncryptedPayload, type ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, type HostToSandboxMessage, type InstanceOption, type InstanceSettings, type MarketplaceExtension, type NamedEntity, type Order, type OrderAction, type OrderItem, type OrderStatus, type OrderStatuses, PERMISSIONS, type Permission, type Price, type SandboxToHostMessage, type Shipment, type SurfaceContext, type SurfaceLifecycleMessage, type Target, type Theme, type ToastPayload, type UITag, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_CHILDREN };
+export { ALLOWED_ICONS, type ActionInvokePayload, type Address, type AllowedIconName, type ApiError, type ApiRequest, type ApiResponse, CAPABILITY_PERMISSION_MAP, type CapabilityCall, type CapabilityRequest, type CapabilityResponse, type CapabilityType, type ContextData, type Customer, type DataField, type DataFieldType, type EncryptedPayload, type ExtensionManifest, type ExtensionRegistryEntry, type FetchRequest, type FetchRequestInit, type FetchResponse, type HostToSandboxMessage, type InstanceOption, type InstanceSettings, type InvokeAction, type MarketplaceExtension, type MessengerCommand, type NamedEntity, type Order, type OrderAction, type OrderItem, type OrderStatus, type OrderStatuses, PERMISSIONS, type Permission, type Price, type SandboxToHostMessage, type Shipment, type SurfaceContext, type SurfaceLifecycleMessage, type Target, type Theme, type ToastPayload, type UITag, type UITagCategory, UI_TAGS, UI_TAG_ATTRIBUTES, UI_TAG_ATTRIBUTE_VALUES, UI_TAG_CATEGORIES, UI_TAG_CHILDREN, UI_TAG_DEFINITIONS, type WidgetAction, tagToComponentName };

package/dist/index.js

@@ -1,89 +1,277 @@
 // src/components.ts
-var UI_TAGS = [
-  "ui-card",
-  "ui-card-content",
-  "ui-card-header",
-  "ui-button",
-  "ui-text",
-  "ui-heading",
-  "ui-badge",
-  "ui-input",
-  "ui-textarea",
-  "ui-select",
-  "ui-select-option",
-  "ui-checkbox",
-  "ui-switch",
-  "ui-label",
-  "ui-radio-group",
-  "ui-radio-group-item",
-  "ui-stack",
-  "ui-inline",
-  "ui-separator",
-  "ui-tabs",
-  "ui-tabs-list",
-  "ui-tabs-trigger",
-  "ui-tabs-content",
-  "ui-scroll-area",
-  "ui-avatar",
-  "ui-icon",
-  "ui-link",
-  "ui-menu",
-  "ui-menu-item",
-  "ui-skeleton",
-  "ui-tooltip",
-  "ui-progress",
-  "ui-alert",
-  "ui-collapsible",
-  "ui-collapsible-trigger",
-  "ui-collapsible-content"
-];
-var UI_TAG_ATTRIBUTES = {
-  "ui-card": ["className", "onClick"],
-  "ui-card-content": ["className"],
-  "ui-card-header": ["className"],
-  "ui-button": ["variant", "size", "disabled", "onClick", "type", "className", "title"],
-  "ui-text": ["className", "tone"],
-  "ui-heading": ["level", "className"],
-  "ui-badge": ["variant", "hue", "tone", "className"],
-  "ui-input": ["type", "placeholder", "value", "onChange", "disabled", "className", "id"],
-  "ui-textarea": ["placeholder", "value", "onChange", "disabled", "rows", "className", "id"],
-  "ui-select": ["value", "defaultValue", "onChange", "placeholder", "disabled", "className"],
-  "ui-select-option": ["value", "disabled", "className"],
-  "ui-checkbox": ["checked", "onChange", "disabled", "className", "id"],
-  "ui-switch": ["checked", "onChange", "disabled", "size", "className", "id"],
-  "ui-label": ["htmlFor", "className"],
-  "ui-radio-group": ["value", "defaultValue", "onChange", "className"],
-  "ui-radio-group-item": ["value", "disabled", "className", "id"],
-  "ui-stack": ["gap", "direction", "align", "className"],
-  "ui-inline": ["gap", "align", "className"],
-  "ui-separator": ["className"],
-  "ui-tabs": ["defaultValue", "className"],
-  "ui-tabs-list": ["className"],
-  "ui-tabs-trigger": ["value", "className"],
-  "ui-tabs-content": ["value", "className"],
-  "ui-scroll-area": ["className"],
-  "ui-avatar": ["src", "alt", "className"],
-  "ui-icon": ["name", "size", "className"],
-  "ui-link": ["href", "target", "rel", "className"],
-  "ui-menu-item": ["icon", "label", "description", "onClick", "className"],
-  "ui-menu": ["title", "className"],
-  "ui-skeleton": ["width", "height", "className"],
-  "ui-tooltip": ["content", "className"],
-  "ui-progress": ["value", "className"],
-  "ui-alert": ["variant", "title", "className"],
-  "ui-collapsible": ["defaultOpen", "className"],
-  "ui-collapsible-trigger": ["className"],
-  "ui-collapsible-content": ["className"]
-};
-var UI_TAG_CHILDREN = {
-  "ui-tabs": ["ui-tabs-list", "ui-tabs-content"],
-  "ui-tabs-list": ["ui-tabs-trigger"],
-  "ui-card": ["ui-card-header", "ui-card-content"],
-  "ui-menu": ["ui-menu-item"],
-  "ui-select": ["ui-select-option"],
-  "ui-radio-group": ["ui-radio-group-item", "ui-label", "ui-inline"],
-  "ui-collapsible": ["ui-collapsible-trigger", "ui-collapsible-content"]
+var UI_TAG_DEFINITIONS = {
+  "ui-card": {
+    description: "Card container for grouping related content",
+    icon: "square",
+    category: "layout",
+    attributes: ["className", "onClick"],
+    children: ["ui-card-header", "ui-card-content"]
+  },
+  "ui-card-content": {
+    description: "Content area within a Card",
+    icon: "square",
+    category: "layout",
+    attributes: ["className"]
+  },
+  "ui-card-header": {
+    description: "Header area within a Card",
+    icon: "square",
+    category: "layout",
+    attributes: ["className"]
+  },
+  "ui-button": {
+    description: "Interactive button with variant and size options",
+    icon: "mouse-pointer-click",
+    category: "input",
+    attributes: ["variant", "size", "disabled", "onClick", "type", "className", "title"],
+    attributeValues: {
+      variant: ["default", "destructive", "outline", "secondary", "ghost", "link"],
+      size: ["default", "xs", "sm", "lg", "icon"]
+    }
+  },
+  "ui-text": {
+    description: "Paragraph text",
+    icon: "type",
+    category: "text",
+    attributes: ["className", "tone"],
+    attributeValues: {
+      tone: ["default", "muted", "destructive"]
+    }
+  },
+  "ui-heading": {
+    description: "Heading element (h1\u2013h6)",
+    icon: "heading",
+    category: "text",
+    attributes: ["level", "className"],
+    attributeValues: {
+      level: ["1", "2", "3", "4", "5", "6"]
+    }
+  },
+  "ui-badge": {
+    description: "Small label for status, category, or count",
+    icon: "tag",
+    category: "text",
+    attributes: ["variant", "hue", "tone", "className"],
+    attributeValues: {
+      variant: ["default", "secondary", "destructive", "outline", "ghost", "link"],
+      hue: ["amber", "blue", "emerald", "red", "purple", "pink", "gray"],
+      tone: ["default", "muted", "destructive"]
+    }
+  },
+  "ui-input": {
+    description: "Single-line text input field",
+    icon: "text-cursor-input",
+    category: "input",
+    attributes: ["type", "placeholder", "value", "onChange", "disabled", "className", "id"]
+  },
+  "ui-textarea": {
+    description: "Multi-line text input field",
+    icon: "text",
+    category: "input",
+    attributes: ["placeholder", "value", "onChange", "disabled", "rows", "className", "id"]
+  },
+  "ui-select": {
+    description: "Dropdown select with options",
+    icon: "chevrons-up-down",
+    category: "input",
+    attributes: ["value", "defaultValue", "onChange", "placeholder", "disabled", "className"],
+    children: ["ui-select-option"]
+  },
+  "ui-select-option": {
+    description: "Option within a Select dropdown",
+    icon: "chevrons-up-down",
+    category: "input",
+    attributes: ["value", "disabled", "className"]
+  },
+  "ui-checkbox": {
+    description: "Checkbox toggle for boolean values",
+    icon: "square-check",
+    category: "input",
+    attributes: ["checked", "onChange", "disabled", "className", "id"]
+  },
+  "ui-switch": {
+    description: "Toggle switch for on/off states",
+    icon: "toggle-left",
+    category: "input",
+    attributes: ["checked", "onChange", "disabled", "size", "className", "id"],
+    attributeValues: {
+      size: ["sm", "default"]
+    }
+  },
+  "ui-label": {
+    description: "Form label associated with an input",
+    icon: "tag",
+    category: "input",
+    attributes: ["htmlFor", "className"]
+  },
+  "ui-radio-group": {
+    description: "Group of radio buttons for single selection",
+    icon: "circle-dot",
+    category: "input",
+    attributes: ["value", "defaultValue", "onChange", "className"],
+    children: ["ui-radio-group-item", "ui-label", "ui-inline"]
+  },
+  "ui-radio-group-item": {
+    description: "Individual radio button within a RadioGroup",
+    icon: "circle-dot",
+    category: "input",
+    attributes: ["value", "disabled", "className", "id"]
+  },
+  "ui-stack": {
+    // TODO: explore adding `align` attribute (e.g., 'start', 'center', 'end') — needs host implementation in hostComponents.tsx
+    description: "Vertical or horizontal flex container with gap",
+    icon: "rows-3",
+    category: "layout",
+    attributes: ["gap", "direction", "className"],
+    attributeValues: {
+      direction: ["row", "column"],
+      gap: ["0", "1", "2", "3", "4", "5", "6", "8", "10", "12"]
+    }
+  },
+  "ui-inline": {
+    // TODO: explore adding `align` attribute (e.g., 'start', 'center', 'end') — needs host implementation in hostComponents.tsx
+    description: "Horizontal flex container with centered items",
+    icon: "columns-3",
+    category: "layout",
+    attributes: ["gap", "className"],
+    attributeValues: {
+      gap: ["0", "1", "2", "3", "4", "5", "6", "8", "10", "12"]
+    }
+  },
+  "ui-separator": {
+    description: "Horizontal divider line",
+    icon: "minus",
+    category: "layout",
+    attributes: ["className"]
+  },
+  "ui-tabs": {
+    description: "Tabbed content container",
+    icon: "panel-top",
+    category: "navigation",
+    attributes: ["defaultValue", "className"],
+    children: ["ui-tabs-list", "ui-tabs-content"]
+  },
+  "ui-tabs-list": {
+    description: "Container for tab triggers",
+    icon: "panel-top",
+    category: "navigation",
+    attributes: ["className"],
+    children: ["ui-tabs-trigger"]
+  },
+  "ui-tabs-trigger": {
+    description: "Clickable tab label within TabsList",
+    icon: "panel-top",
+    category: "navigation",
+    attributes: ["value", "className"]
+  },
+  "ui-tabs-content": {
+    description: "Content panel shown when its tab is active",
+    icon: "panel-top",
+    category: "navigation",
+    attributes: ["value", "className"]
+  },
+  "ui-scroll-area": {
+    description: "Scrollable content container",
+    icon: "scroll",
+    category: "layout",
+    attributes: ["className"]
+  },
+  "ui-avatar": {
+    description: "User avatar with image and initials fallback",
+    icon: "circle-user",
+    category: "composite",
+    attributes: ["src", "alt", "className"]
+  },
+  "ui-icon": {
+    description: "Icon from the allowed icon set",
+    icon: "sparkles",
+    category: "composite",
+    attributes: ["name", "size", "className"],
+    attributeValues: {
+      size: ["sm", "md", "lg"]
+    }
+  },
+  "ui-link": {
+    description: "Hyperlink element",
+    icon: "link",
+    category: "navigation",
+    attributes: ["href", "target", "rel", "className"]
+  },
+  "ui-menu": {
+    description: "Card-based menu with clickable items",
+    icon: "menu",
+    category: "navigation",
+    attributes: ["title", "className"],
+    children: ["ui-menu-item"]
+  },
+  "ui-menu-item": {
+    description: "Clickable item within a Menu",
+    icon: "menu",
+    category: "navigation",
+    attributes: ["icon", "label", "description", "onClick", "className"]
+  },
+  "ui-skeleton": {
+    description: "Loading placeholder with shimmer effect",
+    icon: "loader",
+    category: "feedback",
+    attributes: ["width", "height", "className"]
+  },
+  "ui-tooltip": {
+    description: "Hover tooltip with text content",
+    icon: "message-square",
+    category: "feedback",
+    attributes: ["content", "className"]
+  },
+  "ui-progress": {
+    description: "Progress bar with percentage value",
+    icon: "bar-chart",
+    category: "feedback",
+    attributes: ["value", "className"]
+  },
+  "ui-alert": {
+    description: "Alert banner with icon and optional title",
+    icon: "alert-circle",
+    category: "feedback",
+    attributes: ["variant", "title", "className"],
+    attributeValues: {
+      variant: ["default", "destructive"]
+    }
+  },
+  "ui-collapsible": {
+    description: "Expandable/collapsible content section",
+    icon: "chevrons-down-up",
+    category: "composite",
+    attributes: ["defaultOpen", "className"],
+    children: ["ui-collapsible-trigger", "ui-collapsible-content"]
+  },
+  "ui-collapsible-trigger": {
+    description: "Clickable trigger to toggle Collapsible",
+    icon: "chevrons-down-up",
+    category: "composite",
+    attributes: ["className"]
+  },
+  "ui-collapsible-content": {
+    description: "Content revealed when Collapsible is open",
+    icon: "chevrons-down-up",
+    category: "composite",
+    attributes: ["className"]
+  }
 };
+var defs = UI_TAG_DEFINITIONS;
+var UI_TAGS = Object.keys(UI_TAG_DEFINITIONS);
+var UI_TAG_ATTRIBUTES = Object.fromEntries(
+  UI_TAGS.map((tag) => [tag, defs[tag].attributes])
+);
+var UI_TAG_ATTRIBUTE_VALUES = Object.fromEntries(
+  UI_TAGS.filter((tag) => defs[tag].attributeValues).map((tag) => [tag, defs[tag].attributeValues])
+);
+var UI_TAG_CHILDREN = Object.fromEntries(
+  UI_TAGS.filter((tag) => defs[tag].children).map((tag) => [tag, defs[tag].children])
+);
+var UI_TAG_CATEGORIES = Object.fromEntries(
+  UI_TAGS.map((tag) => [tag, defs[tag].category])
+);
+var tagToComponentName = (tag) => tag.replace(/^ui-/, "").split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
 var ALLOWED_ICONS = [
   "arrow-left",
   "calendar",
@@ -165,5 +353,9 @@ export {
   PERMISSIONS,
   UI_TAGS,
   UI_TAG_ATTRIBUTES,
-  UI_TAG_CHILDREN
+  UI_TAG_ATTRIBUTE_VALUES,
+  UI_TAG_CATEGORIES,
+  UI_TAG_CHILDREN,
+  UI_TAG_DEFINITIONS,
+  tagToComponentName
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/sdk-extension-contracts",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",