The Open Standard for Generative UI
Design update for shell and conversion starter (#248)
Ankit Das94b387e80b37
diff --git a/.cursor/rules/styling-rule.mdc b/.cursor/rules/styling-rule.mdcindex f4e22a07b..6105e931b 100644--- a/.cursor/rules/styling-rule.mdc+++ b/.cursor/rules/styling-rule.mdc@@ -88,128 +88,450 @@ Use the `.crayon-component-name` prefix with BEM-like modifiers:}```-### 3. Typography System+----#### Available Typography Mixins+## Color System++### Background Colors++| Token | Usage |+| ---------------------- | --------------------------------------- |+| `$bg-fill` | Main page/app background |+| `$bg-container` | Card/container backgrounds |+| `$bg-overlay` | Modal/overlay backgrounds |+| `$bg-sunk` | Input fields, recessed areas |+| `$bg-sunk-bg` | Alternative sunk background |+| `$bg-elevated` | Elevated surfaces (dropdowns, popovers) |+| `$bg-inverted` | Inverted/dark backgrounds |+| `$bg-danger` | Error/danger state backgrounds |+| `$bg-success` | Success state backgrounds |+| `$bg-info` | Informational backgrounds |+| `$bg-alert` | Warning/alert backgrounds |+| `$bg-highlight-subtle` | Subtle highlight (hover states) |+| `$bg-highlight-strong` | Strong highlight (selection) |```scss-// Body text variants-@include cssUtils.typography(body, default); // Regular body text-@include cssUtils.typography(body, small); // Smaller body text-@include cssUtils.typography(body, large); // Larger body text-@include cssUtils.typography(body, heavy); // Bold body text--// Label variants-@include cssUtils.typography(label, default); // Regular labels-@include cssUtils.typography(label, small); // Small labels-@include cssUtils.typography(label, large); // Large labels--// Heading variants-@include cssUtils.typography(heading, large); // H1 equivalent-@include cssUtils.typography(heading, medium); // H2 equivalent-@include cssUtils.typography(heading, small); // H3 equivalent--// Number variants (for data display)-@include cssUtils.typography(number, default); // Regular numbers-@include cssUtils.typography(number, large); // Large numbers-@include cssUtils.typography(number, title); // Title numbers+// Example usage+.crayon-card {+ background-color: cssUtils.$bg-container;+}++.crayon-modal-backdrop {+ background-color: cssUtils.$bg-overlay;+}++.crayon-input {+ background-color: cssUtils.$bg-sunk;+}++.crayon-error-banner {+ background-color: cssUtils.$bg-danger;+}```-### 4. Color System+### Interactive Colors++For buttons, clickable elements, and interactive states:++| Token | Usage |+| ----------------------- | -------------------- |+| `$interactive-default` | Default state |+| `$interactive-hover` | Hover state |+| `$interactive-pressed` | Active/pressed state |+| `$interactive-disabled` | Disabled state |++**Accent (Primary Actions):**-#### Background Colors+| Token | Usage |+| ------------------------------ | ----------------------- |+| `$interactive-accent` | Primary button default |+| `$interactive-accent-hover` | Primary button hover |+| `$interactive-accent-pressed` | Primary button pressed |+| `$interactive-accent-disabled` | Primary button disabled |++**Destructive (Danger Actions):**++| Token | Usage |+| ------------------------------------------ | --------------------------- |+| `$interactive-destructive` | Destructive button default |+| `$interactive-destructive-hover` | Destructive button hover |+| `$interactive-destructive-pressed` | Destructive button pressed |+| `$interactive-destructive-disabled` | Destructive button disabled |+| `$interactive-destructive-accent` | Filled destructive button |+| `$interactive-destructive-accent-hover` | Filled destructive hover |+| `$interactive-destructive-accent-pressed` | Filled destructive pressed |+| `$interactive-destructive-accent-disabled` | Filled destructive disabled |```scss-cssUtils.$bg-fill // Main background-cssUtils.$bg-container // Card/container backgrounds-cssUtils.$bg-overlay // Modal/overlay backgrounds-cssUtils.$bg-sunk // Input field backgrounds-cssUtils.$bg-elevated // Elevated surfaces-cssUtils.$bg-danger // Error/danger backgrounds-cssUtils.$bg-success // Success backgrounds-cssUtils.$bg-info // Info backgrounds+// Primary button example+.crayon-button-primary {+ background-color: cssUtils.$interactive-accent;++ &:not(:disabled):hover {+ background-color: cssUtils.$interactive-accent-hover;+ }++ &:not(:disabled):active {+ background-color: cssUtils.$interactive-accent-pressed;+ }++ &:disabled {+ background-color: cssUtils.$interactive-accent-disabled;+ }+}++// Destructive button example+.crayon-button-destructive {+ background-color: cssUtils.$interactive-destructive-accent;++ &:not(:disabled):hover {+ background-color: cssUtils.$interactive-destructive-accent-hover;+ }+}```-#### Interactive Colors+### Text Colors++**Primary Text:**++| Token | Usage |+| ----------------- | ---------------------------------- |+| `$primary-text` | Main body text |+| `$secondary-text` | Secondary/muted text, placeholders |+| `$disabled-text` | Disabled text |+| `$link-text` | Hyperlinks |++**Accent Text:**++| Token | Usage |+| ------------------------ | ------------------------------------ |+| `$accent-primary-text` | Text on accent backgrounds |+| `$accent-secondary-text` | Secondary text on accent backgrounds |+| `$accent-disabled-text` | Disabled text on accent backgrounds |++**Status Text:**++| Token | Usage |+| ------------------------ | --------------------------- |+| `$success-primary-text` | Success messages |+| `$success-inverted-text` | Text on success backgrounds |+| `$alert-primary-text` | Warning messages |+| `$alert-inverted-text` | Text on alert backgrounds |+| `$info-primary-text` | Info messages |+| `$info-inverted-text` | Text on info backgrounds |++**Danger Text:**++| Token | Usage |+| --------------------------------- | ------------------------------------ |+| `$danger-primary-text` | Error messages |+| `$danger-secondary-text` | Secondary error text |+| `$danger-disabled-text` | Disabled error text |+| `$danger-inverted-primary-text` | Primary text on danger backgrounds |+| `$danger-inverted-secondary-text` | Secondary text on danger backgrounds |+| `$danger-inverted-disabled-text` | Disabled text on danger backgrounds |```scss-cssUtils.$interactive-default // Default button background-cssUtils.$interactive-hover // Hover state-cssUtils.$interactive-pressed // Pressed/active state-cssUtils.$interactive-disabled // Disabled state-cssUtils.$interactive-accent // Primary action color+// Example usage+.crayon-label {+ color: cssUtils.$secondary-text;+}++.crayon-error-message {+ color: cssUtils.$danger-primary-text;+}++.crayon-link {+ color: cssUtils.$link-text;+}```-#### Text Colors+### Stroke/Border Colors++| Token | Usage |+| --------------------------------- | ------------------------------------ |+| `$stroke-default` | Default borders |+| `$stroke-emphasis` | Emphasized borders |+| `$stroke-interactive-el` | Interactive element borders |+| `$stroke-interactive-el-selected` | Selected interactive element borders |++**Semantic Strokes:**++| Token | Usage |+| -------------------------- | -------------------------- |+| `$stroke-accent` | Accent/brand borders |+| `$stroke-accent-emphasis` | Emphasized accent borders |+| `$stroke-success` | Success state borders |+| `$stroke-success-emphasis` | Emphasized success borders |+| `$stroke-info` | Info state borders |+| `$stroke-info-emphasis` | Emphasized info borders |+| `$stroke-alert` | Alert/warning borders |+| `$stroke-alert-emphasis` | Emphasized alert borders |+| `$stroke-danger` | Error state borders |+| `$stroke-danger-emphasis` | Emphasized error borders |```scss-cssUtils.$primary-text // Main text color-cssUtils.$secondary-text // Secondary/muted text-cssUtils.$disabled-text // Disabled text-cssUtils.$accent-primary-text // Primary accent text-cssUtils.$success-primary-text // Success text-cssUtils.$danger-primary-text // Error text+// Example usage+.crayon-input {+ border: 1px solid cssUtils.$stroke-default;++ &:focus {+ border-color: cssUtils.$stroke-emphasis;+ }++ &-error {+ border-color: cssUtils.$stroke-danger-emphasis;+ }+}```-#### Stroke/Border Colors+### Chat Colors++For chat/conversation UI components:++| Token | Usage |+| ------------------------------- | ------------------------------- |+| `$chat-container-bg` | Chat container background |+| `$chat-assistant-response-bg` | AI/assistant message background |+| `$chat-assistant-response-text` | AI/assistant message text |+| `$chat-user-response-bg` | User message background |+| `$chat-user-response-text` | User message text |```scss-cssUtils.$stroke-default // Default borders-cssUtils.$stroke-interactive-el // Interactive element borders-cssUtils.$stroke-emphasis // Emphasis borders-cssUtils.$stroke-accent // Accent borders-cssUtils.$stroke-danger // Error borders+// Example chat message styling+.crayon-chat-message {+ &-assistant {+ background-color: cssUtils.$chat-assistant-response-bg;+ color: cssUtils.$chat-assistant-response-text;+ }++ &-user {+ background-color: cssUtils.$chat-user-response-bg;+ color: cssUtils.$chat-user-response-text;+ }+}```-### 5. Spacing System+---++## Spacing System-Use the predefined spacing scale:+Use the predefined spacing scale consistently:++| Token | Value | Usage |+| -------------- | ----- | ---------------------- |+| `$spacing-0` | 0px | No spacing |+| `$spacing-3xs` | 2px | Minimal spacing |+| `$spacing-2xs` | 4px | Very tight spacing |+| `$spacing-xs` | 8px | Tight spacing |+| `$spacing-s` | 12px | Small spacing |+| `$spacing-m` | 16px | Medium/default spacing |+| `$spacing-l` | 20px | Large spacing |+| `$spacing-xl` | 24px | Extra large spacing |+| `$spacing-2xl` | 32px | Section spacing |+| `$spacing-3xl` | 40px | Large section spacing |```scss-cssUtils.$spacing-0 // 0px-cssUtils.$spacing-3xs // 2px-cssUtils.$spacing-2xs // 4px-cssUtils.$spacing-xs // 8px-cssUtils.$spacing-s // 12px-cssUtils.$spacing-m // 16px-cssUtils.$spacing-l // 20px-cssUtils.$spacing-xl // 24px-cssUtils.$spacing-2xl // 32px-cssUtils.$spacing-3xl // 40px+// Example usage+.crayon-card {+ padding: cssUtils.$spacing-m;+ gap: cssUtils.$spacing-s;+}++.crayon-section {+ margin-bottom: cssUtils.$spacing-2xl;+}```-### 6. Border Radius System+---++## Border Radius System++| Token | Value | Usage |+| --------------- | ------ | ------------------------------ |+| `$rounded-0` | 0px | Sharp corners |+| `$rounded-3xs` | 2px | Minimal rounding |+| `$rounded-2xs` | 4px | Subtle rounding |+| `$rounded-xs` | 6px | Small rounding |+| `$rounded-s` | 8px | Standard small |+| `$rounded-m` | 12px | Standard medium |+| `$rounded-l` | 16px | Large rounding |+| `$rounded-xl` | 20px | Extra large rounding |+| `$rounded-2xl` | 24px | Very large rounding |+| `$rounded-3xl` | 28px | Maximum rounding |+| `$rounded-full` | 9999px | Fully rounded (pills, circles) |```scss-cssUtils.$rounded-0 // 0px (sharp corners)-cssUtils.$rounded-3xs // 2px-cssUtils.$rounded-2xs // 4px-cssUtils.$rounded-xs // 6px-cssUtils.$rounded-s // 8px-cssUtils.$rounded-m // 12px-cssUtils.$rounded-l // 16px-cssUtils.$rounded-xl // 20px-cssUtils.$rounded-full // 9999px (fully rounded)+// Example usage+.crayon-button {+ border-radius: cssUtils.$rounded-m;+}++.crayon-avatar {+ border-radius: cssUtils.$rounded-full;+}++.crayon-card {+ border-radius: cssUtils.$rounded-l;+}```-### 7. Shadow System+---++## Shadow System++| Token | Usage |+| ------------- | ------------------------------ |+| `$shadow-s` | Subtle elevation (buttons) |+| `$shadow-m` | Medium elevation (cards) |+| `$shadow-l` | Large elevation (dropdowns) |+| `$shadow-xl` | Extra large elevation (modals) |+| `$shadow-2xl` | High elevation (popovers) |+| `$shadow-3xl` | Maximum elevation |```scss-cssUtils.$shadow-s // Small shadow-cssUtils.$shadow-m // Medium shadow-cssUtils.$shadow-l // Large shadow-cssUtils.$shadow-xl // Extra large shadow-cssUtils.$shadow-2xl // 2X large shadow-cssUtils.$shadow-3xl // 3X large shadow+// Example usage+.crayon-dropdown {+ box-shadow: cssUtils.$shadow-l;+}++.crayon-modal {+ box-shadow: cssUtils.$shadow-xl;+}```-## Component Patterns+---++## Typography System++Use the `typography` mixin for consistent text styling:++```scss+@include cssUtils.typography($category, $variant);+```++### Body Text++| Variant | Usage |+| ------------- | ------------------ |+| `default` | Standard body text |+| `small` | Smaller body text |+| `small-heavy` | Small bold text |+| `medium` | Medium weight body |+| `large` | Larger body text |+| `large-heavy` | Large bold text |+| `heavy` | Bold body text |+| `link` | Link text styling |-### Standard Component Variants+```scss+.crayon-paragraph {+ @include cssUtils.typography(body, default);+}-Most components should support these variants:+.crayon-caption {+ @include cssUtils.typography(body, small);+}-#### Size Variants+.crayon-emphasis {+ @include cssUtils.typography(body, heavy);+}+```++### Labels++| Variant | Usage |+| --------------------- | ----------------------- |+| `default` | Standard labels |+| `heavy` | Bold labels |+| `small` | Small labels |+| `small-heavy` | Small bold labels |+| `medium` | Medium labels |+| `medium-heavy` | Medium bold labels |+| `large` | Large labels |+| `large-heavy` | Large bold labels |+| `extra-small` | Extra small labels |+| `extra-small-heavy` | Extra small bold labels |+| `2-extra-small` | Tiny labels |+| `2-extra-small-heavy` | Tiny bold labels |++```scss+.crayon-form-label {+ @include cssUtils.typography(label, default);+}++.crayon-badge {+ @include cssUtils.typography(label, small-heavy);+}+```++### Headings++| Variant | Usage |+| ------------- | ------------- |+| `large` | H1 equivalent |+| `medium` | H2 equivalent |+| `small` | H3 equivalent |+| `extra-small` | H4 equivalent |++```scss+.crayon-page-title {+ @include cssUtils.typography(heading, large);+}++.crayon-section-title {+ @include cssUtils.typography(heading, medium);+}+```++### Numbers++For data display and metrics:++| Variant | Usage |+| ------------------- | ------------------------------ |+| `default` | Standard numbers |+| `small` | Small numbers |+| `small-heavy` | Small bold numbers |+| `large` | Large numbers |+| `large-heavy` | Large bold numbers |+| `heavy` | Bold numbers |+| `extra-small` | Extra small numbers |+| `extra-small-heavy` | Extra small bold numbers |+| `title` | Display numbers (hero metrics) |+| `title-medium` | Medium display numbers |++```scss+.crayon-metric {+ @include cssUtils.typography(number, large-heavy);+}++.crayon-stat-value {+ @include cssUtils.typography(number, title);+}+```++---++## Utility Mixins++### Button Reset++Removes default button styling:++```scss+.crayon-icon-button {+ @include cssUtils.button-reset;+ // Add your custom styles+ padding: cssUtils.$spacing-xs;+ border-radius: cssUtils.$rounded-m;+}+```++---++## Component Patterns++### Standard Size Variants```scss&-small {@@ -228,7 +550,7 @@ Most components should support these variants:}```-#### Button Variants+### Button Variants```scss&-primary {@@ -240,6 +562,10 @@ Most components should support these variants:background-color: cssUtils.$interactive-accent-hover;}+ &:not(:disabled):active {+ background-color: cssUtils.$interactive-accent-pressed;+ }+&:disabled {background-color: cssUtils.$interactive-accent-disabled;cursor: not-allowed;@@ -254,6 +580,29 @@ Most components should support these variants:&:not(:disabled):hover {background-color: cssUtils.$interactive-hover;}++ &:not(:disabled):active {+ background-color: cssUtils.$interactive-pressed;+ }+}++&-destructive {+ background-color: cssUtils.$interactive-destructive-accent;+ color: cssUtils.$danger-inverted-primary-text;+ border-color: cssUtils.$stroke-danger;++ &:not(:disabled):hover {+ background-color: cssUtils.$interactive-destructive-accent-hover;+ }++ &:not(:disabled):active {+ background-color: cssUtils.$interactive-destructive-accent-pressed;+ }++ &:disabled {+ background-color: cssUtils.$interactive-destructive-accent-disabled;+ cursor: not-allowed;+ }}```@@ -266,6 +615,7 @@ Most components should support these variants:border-radius: cssUtils.$rounded-m;background-color: cssUtils.$bg-sunk;color: cssUtils.$primary-text;+ padding: cssUtils.$spacing-xs cssUtils.$spacing-s;&::placeholder {color: cssUtils.$secondary-text;@@ -285,9 +635,45 @@ Most components should support these variants:&-error {border-color: cssUtils.$stroke-danger-emphasis;}++ &-success {+ border-color: cssUtils.$stroke-success-emphasis;+ }+}+```++### Status Badges Pattern++```scss+.crayon-badge {+ @include cssUtils.typography(label, small-heavy);+ padding: cssUtils.$spacing-2xs cssUtils.$spacing-xs;+ border-radius: cssUtils.$rounded-full;++ &-success {+ background-color: cssUtils.$bg-success;+ color: cssUtils.$success-primary-text;+ }++ &-danger {+ background-color: cssUtils.$bg-danger;+ color: cssUtils.$danger-primary-text;+ }++ &-info {+ background-color: cssUtils.$bg-info;+ color: cssUtils.$info-primary-text;+ }++ &-alert {+ background-color: cssUtils.$bg-alert;+ color: cssUtils.$alert-primary-text;+ }}```+---+## Best Practices### 1. Avoid Magic Numbers@@ -318,20 +704,43 @@ Use the `:not(:disabled)` pattern for hover/active states:}```-### 3. Responsive Design+### 3. Focus States (Accessibility)-For responsive components, use CSS custom properties that can be controlled via JavaScript:+Always include visible focus states:++```scss+&:focus-visible {+ outline: 2px solid cssUtils.$stroke-accent;+ outline-offset: 2px;+}+```++### 4. Responsive Design++Use CSS custom properties for values that can be controlled via JavaScript:```scss.my-responsive-component {- gap: var(--component-gap, cssUtils.$spacing-m);- padding: var(--component-padding, cssUtils.$spacing-m);+ gap: var(--component-gap, #{cssUtils.$spacing-m});+ padding: var(--component-padding, #{cssUtils.$spacing-m});}```-### 4. Component Composition+### 5. CSS Custom Properties for Theming-Prefer composition over complex variants. Create small, focused components that can be combined:+```scss+.crayon-themeable-component {+ --component-bg: #{cssUtils.$bg-container};+ --component-text: #{cssUtils.$primary-text};++ background-color: var(--component-bg);+ color: var(--component-text);+}+```++### 6. Component Composition++Prefer composition over complex variants:```tsx// ✅ Good - Composable@@ -356,33 +765,7 @@ Prefer composition over complex variants. Create small, focused components that/>```-### 5. CSS Custom Properties for Theming--Use CSS custom properties for values that might need to be overridden:--```scss-.crayon-themeable-component {- --component-bg: #{cssUtils.$bg-container};- --component-text: #{cssUtils.$primary-text};-- background-color: var(--component-bg);- color: var(--component-text);-}-```--### 6. Accessibility Considerations--- Always include focus states-- Use appropriate color contrasts (handled by design tokens)-- Support keyboard navigation-- Include proper ARIA attributes in component markup--### 7. Performance--- Avoid deeply nested selectors-- Use efficient CSS selectors-- Minimize CSS specificity conflicts-- Consider CSS-in-JS only when necessary (prefer SCSS for static styles)+---## When to Create New Components@@ -405,6 +788,8 @@ Use CSS custom properties for values that might need to be overridden:- Layout-only components (use CSS Grid/Flexbox)- Text styling (use typography mixins)+---+## Migration GuideWhen updating existing components:@@ -415,18 +800,12 @@ When updating existing components:4. **Add missing states** - Include hover, focus, disabled, active states5. **Test thoroughly** - Verify all variants work correctly+---+## Tooling- **SCSS Compilation**: `pnpm build:scss`-- **Linting**: ESLint with custom rules-- **Storybook**: For component development and testing-- **Design Tokens**: All available in `cssUtils.scss`--## Questions?--When in doubt:--1. Check existing components for similar patterns-2. Look at `cssUtils.scss` for available tokens-3. Ask in #design-system Slack channel-4. Reference the design system documentation+- **Watch Mode**: `pnpm watch`+- **Storybook**: `pnpm storybook`+- **Linting**: `pnpm lint:check`+- **Format**: `pnpm format:check`diff --git a/js/packages/react-core/package.json b/js/packages/react-core/package.jsonindex 9de3ce69a..491cb559d 100644--- a/js/packages/react-core/package.json+++ b/js/packages/react-core/package.json@@ -1,6 +1,6 @@{"name": "@crayonai/react-core",- "version": "0.7.6",+ "version": "0.7.7","description": "Generative UI SDK","license": "MIT","main": "dist/index.js",diff --git a/js/packages/react-core/src/hooks/useThreadState.ts b/js/packages/react-core/src/hooks/useThreadState.tsindex 898228e8d..a3ba475d7 100644--- a/js/packages/react-core/src/hooks/useThreadState.ts+++ b/js/packages/react-core/src/hooks/useThreadState.ts@@ -19,5 +19,6 @@ export const useThreadState = (): ThreadState => {messages: useStore(threadManager, (store) => store.messages),error: useStore(threadManager, (store) => store.error),responseTemplates: useStore(threadManager, (store) => store.responseTemplates),+ isInitialized: useStore(threadManager, (store) => store.isInitialized),};};diff --git a/js/packages/react-core/src/internal/useThreadManagerStore.ts b/js/packages/react-core/src/internal/useThreadManagerStore.tsindex 3f1693f30..68ce7c2b7 100644--- a/js/packages/react-core/src/internal/useThreadManagerStore.ts+++ b/js/packages/react-core/src/internal/useThreadManagerStore.ts@@ -10,6 +10,7 @@ export const useThreadManagerStore = (inputThreadManager: ThreadManager) => {const [threadManagerStore] = useState(() =>create<ThreadManager>(() => ({+ isInitialized: inputThreadManager.isInitialized,isLoadingMessages: inputThreadManager.isLoadingMessages,isRunning: inputThreadManager.isRunning,messages: inputThreadManager.messages,@@ -31,12 +32,14 @@ export const useThreadManagerStore = (inputThreadManager: ThreadManager) => {messages: inputThreadManager.messages,error: inputThreadManager.error,isLoadingMessages: inputThreadManager.isLoadingMessages,+ isInitialized: inputThreadManager.isInitialized,});}, [inputThreadManager.isRunning,inputThreadManager.messages,inputThreadManager.error,inputThreadManager.isLoadingMessages,+ inputThreadManager.isInitialized,]);if (inputThreadManagerRef.current.responseTemplates !== inputThreadManager.responseTemplates) {diff --git a/js/packages/react-core/src/types/chatManager.ts b/js/packages/react-core/src/types/chatManager.tsindex 30c217e8a..1ff286f51 100644--- a/js/packages/react-core/src/types/chatManager.ts+++ b/js/packages/react-core/src/types/chatManager.ts@@ -57,6 +57,8 @@ export type ThreadState = {* `responseTemplates` property provided to the hook.*/responseTemplates: Record<string, ResponseTemplate>;+ /** Indicates if the thread manager is initialized and the thread can show threadList or welcome screen */+ isInitialized: boolean;};/**diff --git a/js/packages/react-core/src/useThreadManager.ts b/js/packages/react-core/src/useThreadManager.tsindex fa33e3225..1fe31944e 100644--- a/js/packages/react-core/src/useThreadManager.ts+++ b/js/packages/react-core/src/useThreadManager.ts@@ -43,7 +43,7 @@ export const useThreadManager = (params: UseThreadManagerParams): ThreadManagerpropsRef.current = params;const store = useMemo(() => {- return createStore<+ const store = createStore<ThreadManager & {abortController: AbortController | null;}@@ -54,6 +54,7 @@ export const useThreadManager = (params: UseThreadManagerParams): ThreadManagerabortController: null,isRunning: false,isLoadingMessages: false,+ isInitialized: false,setMessages: (messages: Message[]) => {set({ messages });},@@ -117,6 +118,21 @@ export const useThreadManager = (params: UseThreadManagerParams): ThreadManager),};});++ /**+ * Delay initialization to ensure proper thread manager setup.+ *+ * Why this delay is necessary:+ * - Multiple React effects must run to determine the initial `selectedThreadId`+ * - Without a definitive thread ID state (null vs. valid ID), the UI cannot+ * determine whether to render the thread list or welcome screen+ * - This 200ms buffer allows all effects to complete, providing a stable state+ * before marking initialization as complete+ */+ setTimeout(() => {+ store.setState({ isInitialized: true });+ }, 200);+ return store;}, [propsRef]);useEffect(() => {diff --git a/js/packages/react-ui/package.json b/js/packages/react-ui/package.jsonindex f5f80363c..a52b50d8f 100644--- a/js/packages/react-ui/package.json+++ b/js/packages/react-ui/package.json@@ -2,7 +2,7 @@"type": "module","name": "@crayonai/react-ui","license": "MIT",- "version": "0.9.11",+ "version": "0.9.12","description": "Component library for Generative UI SDK","main": "dist/index.js","types": "dist/index.d.ts",diff --git a/js/packages/react-ui/src/components/BottomTray/ConversationStarter.tsx b/js/packages/react-ui/src/components/BottomTray/ConversationStarter.tsxnew file mode 100644index 000000000..267d7da18--- /dev/null+++ b/js/packages/react-ui/src/components/BottomTray/ConversationStarter.tsx@@ -0,0 +1,145 @@+import { useThreadActions, useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ArrowUp, Lightbulb } from "lucide-react";+import { Fragment, ReactNode } from "react";+import { ConversationStarterIcon, ConversationStarterProps } from "../../types/ConversationStarter";+import { Separator } from "../Separator";++export type ConversationStarterVariant = "short" | "long";++interface ConversationStarterItemProps extends ConversationStarterProps {+ onClick: (prompt: string) => void;+ variant: ConversationStarterVariant;+}++/**+ * Renders the appropriate icon based on the icon prop value+ * - undefined: Show default lightbulb icon+ * - ReactNode: Show the provided icon (use <></> or React.Fragment for no icon)+ */+const renderIcon = (icon: ConversationStarterIcon | undefined): ReactNode => {+ if (icon === undefined) {+ return <Lightbulb size={16} />;+ }+ return icon;+};++const ConversationStarterItem = ({+ displayText,+ prompt,+ onClick,+ variant,+ icon,+}: ConversationStarterItemProps) => {+ const renderedIcon = renderIcon(icon);++ if (variant === "short") {+ return (+ <button+ type="button"+ className="crayon-bottom-tray-conversation-starter-item-short"+ onClick={() => onClick(prompt)}+ >+ {renderedIcon && (+ <span className="crayon-bottom-tray-conversation-starter-item-short__icon">+ {renderedIcon}+ </span>+ )}+ <span className="crayon-bottom-tray-conversation-starter-item-short__text">+ {displayText}+ </span>+ </button>+ );+ }++ // Long variant (detailed list style)+ return (+ <button+ type="button"+ className="crayon-bottom-tray-conversation-starter-item-long"+ onClick={() => onClick(prompt)}+ >+ <div className="crayon-bottom-tray-conversation-starter-item-long__content">+ {renderedIcon && (+ <span className="crayon-bottom-tray-conversation-starter-item-long__icon">+ {renderedIcon}+ </span>+ )}+ <span className="crayon-bottom-tray-conversation-starter-item-long__text">+ {displayText}+ </span>+ </div>+ <span className="crayon-bottom-tray-conversation-starter-item-long__arrow">+ <ArrowUp size={16} />+ </span>+ </button>+ );+};++export interface ConversationStarterContainerProps {+ starters: ConversationStarterProps[];+ className?: string;+ /**+ * Variant of the conversation starter+ * - "short": Pill-style horizontal buttons (default)+ * - "long": List items with icons and hover arrow+ */+ variant?: ConversationStarterVariant;+}++export const ConversationStarter = ({+ starters,+ className,+ variant = "short",+}: ConversationStarterContainerProps) => {+ const { processMessage } = useThreadActions();+ const { isRunning, messages } = useThreadState();++ const handleClick = (prompt: string) => {+ if (isRunning) return;+ processMessage({+ type: "prompt",+ role: "user",+ message: prompt,+ });+ };++ // Only show when there are no messages+ if (messages.length > 0) {+ return null;+ }++ if (starters.length === 0) {+ return null;+ }++ return (+ <div+ className={clsx(+ "crayon-bottom-tray-conversation-starter",+ `crayon-bottom-tray-conversation-starter--${variant}`,+ className,+ )}+ >+ {starters.map((item, index) => (+ <Fragment key={`${item.displayText}-${index}`}>+ <ConversationStarterItem+ displayText={item.displayText}+ prompt={item.prompt}+ icon={item.icon}+ onClick={handleClick}+ variant={variant}+ />+ {/* Add separator between items in long variant */}+ {variant === "long" && index < starters.length - 1 && (+ <div className="crayon-bottom-tray-conversation-starter__separator">+ <Separator />+ </div>+ )}+ </Fragment>+ ))}+ </div>+ );+};++export default ConversationStarter;diff --git a/js/packages/react-ui/src/components/BottomTray/Thread.tsx b/js/packages/react-ui/src/components/BottomTray/Thread.tsxindex d1114697c..7a7c875f3 100644--- a/js/packages/react-ui/src/components/BottomTray/Thread.tsx+++ b/js/packages/react-ui/src/components/BottomTray/Thread.tsx@@ -6,7 +6,7 @@ import {useThreadState,} from "@crayonai/react-core";import clsx from "clsx";-import { ArrowRight, Square } from "lucide-react";+import { ArrowUp, Square } from "lucide-react";import React, { memo, useEffect, useLayoutEffect, useRef } from "react";import { useComposerState } from "../../hooks/useComposerState";import { ScrollVariant, useScrollToBottom } from "../../hooks/useScrollToBottom";@@ -35,7 +35,20 @@ export const ThreadContainer = ({setArtifactRenderer(renderArtifact);}, [isArtifactActive, renderArtifact, setIsArtifactActive, setArtifactRenderer]);- return <div className={clsx("crayon-bottom-tray-thread-container", className)}>{children}</div>;+ const { isInitialized } = useThreadManagerSelector((store) => ({+ isInitialized: store.isInitialized,+ }));++ return (+ <div+ className={clsx("crayon-bottom-tray-thread-container", className)}+ style={{+ visibility: isInitialized ? undefined : "hidden",+ }}+ >+ {children}+ </div>+ );};export const ScrollArea = ({@@ -265,7 +278,7 @@ export const Composer = ({ className }: { className?: string }) => {/><IconButtononClick={isRunning ? onCancel : handleSubmit}- icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowRight size="1em" />}+ icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowUp size="1em" />}/></div></div>diff --git a/js/packages/react-ui/src/components/BottomTray/WelcomeScreen.tsx b/js/packages/react-ui/src/components/BottomTray/WelcomeScreen.tsxnew file mode 100644index 000000000..8cdb3da24--- /dev/null+++ b/js/packages/react-ui/src/components/BottomTray/WelcomeScreen.tsx@@ -0,0 +1,106 @@+import { useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ReactNode } from "react";++interface WelcomeScreenBaseProps {+ /**+ * Additional CSS class name+ */+ className?: string;+}++interface WelcomeScreenWithContentProps extends WelcomeScreenBaseProps {+ /**+ * The greeting/title text to display+ */+ title?: string;+ /**+ * Optional description text to add more context+ */+ description?: string;+ /**+ * Image to display - can be a URL object or a ReactNode+ * - { url: string }: Renders an <img> tag with default styling (64x64, object-fit: cover, rounded)+ * - ReactNode: Renders the provided element directly (for custom icons, styled images, etc.)+ */+ image?: { url: string } | ReactNode;+ /**+ * Children are not allowed when using props-based content+ */+ children?: never;+}++interface WelcomeScreenWithChildrenProps extends WelcomeScreenBaseProps {+ /**+ * Custom content to render inside the welcome screen+ * When children are provided, title, description, and image are ignored+ */+ children: ReactNode;+ title?: never;+ description?: never;+ image?: never;+}++export type WelcomeScreenProps = WelcomeScreenWithContentProps | WelcomeScreenWithChildrenProps;++/**+ * Type guard to check if image is a URL object+ */+const isImageUrl = (image: { url: string } | ReactNode): image is { url: string } => {+ return typeof image === "object" && image !== null && "url" in image;+};++export const WelcomeScreen = (props: WelcomeScreenProps) => {+ const { className } = props;++ const { messages } = useThreadState();++ // Only show when there are no messages+ if (messages.length > 0) {+ return null;+ }++ // Check if children are provided+ if ("children" in props && props.children) {+ return (+ <div className={clsx("crayon-bottom-tray-welcome-screen", className)}>{props.children}</div>+ );+ }++ // Props-based content+ const { title, description, image } = props as WelcomeScreenWithContentProps;++ const renderImage = () => {+ if (!image) return null;++ if (isImageUrl(image)) {+ return (+ <img+ src={image.url}+ alt={title || ""}+ className="crayon-bottom-tray-welcome-screen__image"+ />+ );+ }++ return image;+ };++ return (+ <div className={clsx("crayon-bottom-tray-welcome-screen", className)}>+ {image && (+ <div className="crayon-bottom-tray-welcome-screen__image-container">{renderImage()}</div>+ )}+ {(title || description) && (+ <div className="crayon-bottom-tray-welcome-screen__content">+ {title && <h2 className="crayon-bottom-tray-welcome-screen__title">{title}</h2>}+ {description && (+ <p className="crayon-bottom-tray-welcome-screen__description">{description}</p>+ )}+ </div>+ )}+ </div>+ );+};++export default WelcomeScreen;diff --git a/js/packages/react-ui/src/components/BottomTray/bottomTray.scss b/js/packages/react-ui/src/components/BottomTray/bottomTray.scssindex 9ccbdaf8c..164830724 100644--- a/js/packages/react-ui/src/components/BottomTray/bottomTray.scss+++ b/js/packages/react-ui/src/components/BottomTray/bottomTray.scss@@ -6,3 +6,5 @@@use "./header.scss";@use "./threadList.scss";@use "./thread.scss";+@use "./conversationStarter.scss";+@use "./welcomeScreen.scss";diff --git a/js/packages/react-ui/src/components/BottomTray/container.scss b/js/packages/react-ui/src/components/BottomTray/container.scssindex f5fa719d2..dbb667759 100644--- a/js/packages/react-ui/src/components/BottomTray/container.scss+++ b/js/packages/react-ui/src/components/BottomTray/container.scss@@ -11,9 +11,13 @@width: 448px;overflow: hidden;flex-direction: column;++ // Cone animation: expand from bottom-right (where trigger is)+ transform-origin: bottom right;transition:- transform 0.3s cubic-bezier(0.4, 0, 0.2, 1),- opacity 0.3s ease;+ transform 0.25s ease-in-out,+ opacity 0.25s ease-in-out,+ clip-path 0.25s ease-in-out;border: 1px solid cssUtils.$stroke-default;border-radius: cssUtils.$rounded-2xl cssUtils.$rounded-2xl cssUtils.$rounded-3xl@@ -26,17 +30,19 @@box-sizing: border-box;}- // Open state+ // Open state - fully expanded&--open {- transform: translateY(0);+ transform: scale(1);opacity: 1;+ clip-path: ellipse(150% 150% at 100% 100%);}- // Closed state+ // Closed state - collapsed to trigger point with cone clip&--closed {- transform: translateY(calc(100% + cssUtils.$spacing-l));+ transform: scale(0.1);opacity: 0;pointer-events: none;+ clip-path: ellipse(0% 0% at 100% 100%);}// Mobile fullscreen@@ -52,8 +58,10 @@border-radius: 0;border: none;+ // On mobile, expand from bottom-right corner where trigger was&--closed {- transform: translateY(100dvh);+ transform: scale(0.1);+ clip-path: ellipse(0% 0% at 100% 100%);}}}diff --git a/js/packages/react-ui/src/components/BottomTray/conversationStarter.scss b/js/packages/react-ui/src/components/BottomTray/conversationStarter.scssnew file mode 100644index 000000000..c52a69c84--- /dev/null+++ b/js/packages/react-ui/src/components/BottomTray/conversationStarter.scss@@ -0,0 +1,140 @@+@use "../../cssUtils" as cssUtils;++// Container styles+.crayon-bottom-tray-conversation-starter {+ display: flex;+ padding: 0 cssUtils.$spacing-s;+ margin-bottom: cssUtils.$spacing-s;++ // Short variant - horizontal pill buttons+ &--short {+ flex-direction: column;+ gap: cssUtils.$spacing-s;+ }++ // Long variant - vertical list items with separators+ &--long {+ flex-direction: column;+ gap: cssUtils.$spacing-2xs;+ }++ // Separator wrapper for long variant+ &__separator {+ padding: cssUtils.$spacing-3xs cssUtils.$spacing-xs;+ }+}++// Short variant item (pill-style buttons)+.crayon-bottom-tray-conversation-starter-item-short {+ display: flex;+ align-items: flex-start;+ gap: cssUtils.$spacing-xs;+ width: fit-content;+ padding: cssUtils.$spacing-s cssUtils.$spacing-m;+ background-color: cssUtils.$bg-container;+ border: 1px solid cssUtils.$stroke-default;+ border-radius: cssUtils.$rounded-m;+ cursor: pointer;+ transition: all 0.15s ease;+ @include cssUtils.typography(body, small);+ color: cssUtils.$primary-text;+ text-align: left;++ // Icon container+ &__icon {+ display: flex;+ align-items: flex-start;+ justify-content: center;+ flex-shrink: 0;+ padding-top: cssUtils.$spacing-3xs;+ color: cssUtils.$primary-text;+ }++ // Text+ &__text {+ flex: 1;+ }++ &:not(:disabled):hover {+ background-color: cssUtils.$bg-sunk;+ border-color: cssUtils.$stroke-emphasis;+ }++ &:not(:disabled):active {+ background-color: cssUtils.$bg-sunk;+ }++ @media (max-width: 480px) {+ padding: cssUtils.$spacing-xs cssUtils.$spacing-s;+ }+}++// Long variant item (list-style with icon and arrow)+.crayon-bottom-tray-conversation-starter-item-long {+ display: flex;+ align-items: center;+ gap: cssUtils.$spacing-0;+ width: 100%;+ padding: cssUtils.$spacing-xs cssUtils.$spacing-xs;+ background-color: transparent;+ border: none;+ border-radius: cssUtils.$rounded-m;+ cursor: pointer;+ transition: background-color 0.15s ease;+ @include cssUtils.typography(body, default);+ color: cssUtils.$primary-text;+ text-align: left;+ overflow: hidden;++ // Content wrapper (icon + text)+ &__content {+ display: flex;+ align-items: flex-start;+ gap: cssUtils.$spacing-xs;+ flex: 1;+ min-width: 0;+ }++ // Icon container - aligned to top with padding to align with first line of text+ &__icon {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ padding-top: cssUtils.$spacing-2xs;+ color: cssUtils.$primary-text;+ }++ // Text - allows wrapping for long content+ &__text {+ flex: 1;+ min-width: 0;+ line-height: 1.5;+ // Text wraps naturally, no truncation+ }++ // Arrow icon (shown on hover)+ &__arrow {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ opacity: 0;+ transition: opacity 0.15s ease;+ color: cssUtils.$primary-text;+ }++ // Hover state+ &:not(:disabled):hover {+ background-color: cssUtils.$bg-sunk;++ .crayon-bottom-tray-conversation-starter-item-long__arrow {+ opacity: 1;+ }+ }++ // Active/pressed state+ &:not(:disabled):active {+ background-color: cssUtils.$interactive-pressed;+ }+}diff --git a/js/packages/react-ui/src/components/BottomTray/index.ts b/js/packages/react-ui/src/components/BottomTray/index.tsindex c7fc7b5aa..4306ca7ac 100644--- a/js/packages/react-ui/src/components/BottomTray/index.ts+++ b/js/packages/react-ui/src/components/BottomTray/index.ts@@ -1,4 +1,6 @@export * from "./Container";+export * from "./ConversationStarter";export * from "./Header";export * from "./Thread";export * from "./Trigger";+export * from "./WelcomeScreen";diff --git a/js/packages/react-ui/src/components/BottomTray/stories/BottomTray.mdx b/js/packages/react-ui/src/components/BottomTray/stories/BottomTray.mdxnew file mode 100644index 000000000..ea160a8d5--- /dev/null+++ b/js/packages/react-ui/src/components/BottomTray/stories/BottomTray.mdx@@ -0,0 +1,361 @@+import { Meta } from "@storybook/blocks";+import * as BottomTrayStories from "./BottomTray.stories";++<Meta of={BottomTrayStories} />++# BottomTray++The BottomTray is a **composable chat interface** that appears as a floating panel in the bottom-right corner of your application. It uses a composition pattern, giving you full control over placement and styling.++## Component Structure++```+ChatProvider+├── Trigger (floating button to open/close)+└── Container (the tray panel)+ └── ThreadContainer+ ├── Header (logo, agent name, actions)+ ├── WelcomeScreen (optional, shown when empty)+ ├── ScrollArea (scrollable message area)+ │ └── Messages+ ├── ConversationStarter (optional, shown when empty)+ └── Composer (text input)+```++## Basic Usage++```tsx+import { useState } from "react";+import { ChatProvider, useThreadListManager, useThreadManager } from "@crayonai/react-core";+import {+ Composer,+ Container,+ ConversationStarter,+ Header,+ MessageLoading,+ Messages,+ ScrollArea,+ ThreadContainer,+ Trigger,+ WelcomeScreen,+} from "@crayonai/react-ui";++function MyApp() {+ const [isOpen, setIsOpen] = useState(false);++ // Set up thread list management+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => {+ // Fetch threads from your backend+ return [];+ },+ deleteThread: async (id) => {+ // Delete thread from your backend+ },+ updateThread: async (thread) => thread,+ onSwitchToNew: () => {},+ onSelectThread: (threadId) => {},+ });++ // Set up thread management+ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async (threadId) => {+ // Return empty for new thread, otherwise load messages+ if (!threadId) return [];+ // Fetch messages from your backend+ return [];+ },+ onProcessMessage: async ({ message, threadManager }) => {+ // Send message to your AI backend+ // Return assistant response+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: "Response from AI" }],+ },+ ];+ },+ responseTemplates: [],+ });++ const hasMessages = threadManager.messages.length > 0;++ return (+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ {/* Trigger - floating button */}+ <Trigger onClick={() => setIsOpen(!isOpen)} isOpen={isOpen} />++ {/* Container - the tray panel */}+ <Container logoUrl="/path/to/logo.png" agentName="AI Assistant" isOpen={isOpen}>+ <ThreadContainer>+ <Header onMinimize={() => setIsOpen(false)} />++ {/* WelcomeScreen - shown when no messages */}+ {!hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={+ <img+ src="/path/to/logo.png"+ alt="AI Assistant"+ style={{ width: 64, height: 64, borderRadius: 16, objectFit: "cover" }}+ />+ }+ />+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter+ starters={[+ { displayText: "Help me get started", prompt: "Help me get started" },+ { displayText: "What can you do?", prompt: "What can you do?" },+ ]}+ />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ );+}+```++## Components++### Trigger++The floating button that opens/closes the tray. Positioned fixed in the bottom-right corner.++```tsx+<Trigger+ onClick={() => setIsOpen(!isOpen)}+ isOpen={isOpen} // Controls shrink animation when open+ className="custom-class" // Optional custom styling+>+ {/* Optional custom content, defaults to chevron icon */}+ 💬 Need Help?+</Trigger>+```++### Container++The main tray panel. Controls visibility with `isOpen` prop.++```tsx+<Container+ logoUrl="/logo.png" // Logo shown in header+ agentName="AI Assistant" // Name shown in header+ isOpen={isOpen} // Controls open/closed animation+ className="custom-class" // Optional custom styling+>+ {children}+</Container>+```++### ThreadContainer++Wrapper for thread content. Manages layout and artifact panels.++```tsx+<ThreadContainer+ isArtifactActive={false} // Show artifact panel+ renderArtifact={() => <div />} // Artifact content+>+ {children}+</ThreadContainer>+```++### Header++Header with logo, agent name, thread list, new chat button, and minimize.++```tsx+<Header+ onMinimize={() => setIsOpen(false)} // Minimize callback+ hideMinimizeButton={false} // Hide X button+ hideNewChatButton={false} // Hide new chat button+ hideThreadListContainer={false} // Hide thread list+ rightChildren={<CustomActions />} // Custom actions+/>+```++### ScrollArea++Scrollable container for messages with auto-scroll behavior.++```tsx+<ScrollArea+ scrollVariant="user-message-anchor" // Scroll behavior+ userMessageSelector=".user-message" // CSS selector for user messages+>+ <Messages loader={<MessageLoading />} />+</ScrollArea>+```++### ConversationStarter++Clickable prompts shown when thread is empty. Automatically hides when messages exist.++```tsx+<ConversationStarter+ variant="short" // "short" (pill buttons) or "long" (list items)+ starters={[+ {+ displayText: "Help me get started",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ { displayText: "What can you do?", prompt: "What can you do?" }, // Default lightbulb icon+ { displayText: "No icon example", prompt: "No icon", icon: <></> }, // No icon (use empty fragment)+ ]}+/>+```++**Props:**++- `variant` - `"short"` (pill-style buttons) or `"long"` (list items with separators)+- `starters` - Array of objects with:+ - `displayText` - Text shown on the button+ - `prompt` - Message sent when clicked+ - `icon` - Optional: `ReactNode` for custom icon, `undefined` for default lightbulb, `<></>` (empty fragment) for no icon++### WelcomeScreen++A centered welcome message shown when the thread is empty. Supports either props-based content or custom children.++**Props-based usage with URL:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={{ url: "/path/to/logo.png" }}+ />+ );+}+```++**Props-based usage with styled image:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={+ <img+ src="/path/to/logo.png"+ alt="AI Assistant"+ style={{ width: 64, height: 64, borderRadius: 16, objectFit: "cover" }}+ />+ }+ />+ );+}+```++**Props-based usage with custom icon:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={<Sparkles size={32} />}+ />+ );+}+```++**Custom children usage:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen>+ <div style={{ textAlign: "center" }}>+ <MyCustomLogo />+ <h2>Welcome!</h2>+ <p>Custom welcome content</p>+ </div>+ </WelcomeScreen>+ );+}+```++**Props:**++- `title` - Greeting/title text (optional)+- `description` - Description text (optional)+- `image` - Image to display: `{ url: string }` for simple URL (renders with default 64x64 size, rounded corners), or `ReactNode` for custom styled elements (optional)+- `children` - Custom content (mutually exclusive with title/description/image)+- `className` - Additional CSS class (optional)++**Note:** You must conditionally render WelcomeScreen based on `hasMessages` state.++### Composer++Text input with submit button. Handles enter key and running state.++```tsx+<Composer className="custom-class" />+```++## Customization Examples++### Custom Trigger Content++```tsx+<Trigger onClick={() => setIsOpen(!isOpen)} isOpen={isOpen}>+ <img src="/custom-icon.png" alt="Chat" />+</Trigger>+```++### Without ConversationStarter++Simply omit the component:++```tsx+<ThreadContainer>+ <Header onMinimize={() => setIsOpen(false)} />+ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <Composer />+</ThreadContainer>+```++### Minimal Header++```tsx+<Header onMinimize={() => setIsOpen(false)} hideNewChatButton hideThreadListContainer />+```++## Animation++The tray uses a **cone animation** that expands from the trigger button:++- Opens with scale + clip-path animation from bottom-right+- Trigger shrinks when tray is open+- Smooth spring easing for natural feel++## Mobile Behavior++- Tray goes fullscreen on mobile (less than 768px)+- Trigger hides when tray is open on mobile+- Touch-friendly interactionsdiff --git a/js/packages/react-ui/src/components/BottomTray/stories/BottomTray.stories.tsx b/js/packages/react-ui/src/components/BottomTray/stories/BottomTray.stories.tsxindex f2a6b0d41..231ac936e 100644--- a/js/packages/react-ui/src/components/BottomTray/stories/BottomTray.stories.tsx+++ b/js/packages/react-ui/src/components/BottomTray/stories/BottomTray.stories.tsx@@ -4,16 +4,19 @@ import {useThreadListManager,useThreadManager,} from "@crayonai/react-core";+import { MessageSquare, Sparkles, Zap } from "lucide-react";import { useState } from "react";import {Composer,Container,+ ConversationStarter,Header,MessageLoading,Messages,ScrollArea,ThreadContainer,Trigger,+ WelcomeScreen,} from "../../BottomTray";// @ts-ignoreimport styles from "./style.module.scss";@@ -21,16 +24,27 @@ import logoUrl from "./thesysdev_logo.jpeg";export default {title: "Components/BottomTray",- tags: ["dev", "!autodocs"],+ tags: ["dev"],argTypes: {defaultOpen: {control: "boolean",description: "Whether the tray starts open",},+ variant: {+ control: "select",+ options: ["short", "long"],+ description: "Conversation starter variant",+ },},};-const BottomTrayStory = ({ defaultOpen = false }: { defaultOpen?: boolean }) => {+const BottomTrayStory = ({+ defaultOpen = false,+ variant = "short",+}: {+ defaultOpen?: boolean;+ variant?: "short" | "long";+}) => {const [isOpen, setIsOpen] = useState(defaultOpen);const threadListManager = useThreadListManager({@@ -73,7 +87,9 @@ const BottomTrayStory = ({ defaultOpen = false }: { defaultOpen?: boolean }) =>const threadManager = useThreadManager({threadId: threadListManager.selectedThreadId,- loadThread: async () => {+ loadThread: async (threadId) => {+ // Return empty for new thread (null), otherwise return existing messages+ if (!threadId) return [];return [{id: crypto.randomUUID(),@@ -135,6 +151,28 @@ const BottomTrayStory = ({ defaultOpen = false }: { defaultOpen?: boolean }) =><ScrollArea><Messages loader={<MessageLoading />} /></ScrollArea>+ <ConversationStarter+ variant={variant}+ starters={[+ {+ displayText: "Tell me about my portfolio",+ prompt:+ "Tell me about the latest stock market trends and how they affect my portfolio",+ icon: <Sparkles size={16} />,+ },+ {+ displayText:+ "Who is the president of Venezuela and where is he currently located (icon was not passed)",+ prompt: "Who is the president of Venezuela and where is he currently located?",+ // icon undefined = shows default lightbulb+ },+ {+ displayText: "Tell me about major stock (no icon with empty fragment)",+ prompt: "Tell me about major stock",+ icon: <></>, // Empty fragment = no icon+ },+ ]}+ /><Composer /></ThreadContainer></Container>@@ -146,6 +184,7 @@ const BottomTrayStory = ({ defaultOpen = false }: { defaultOpen?: boolean }) =>export const Default = {args: {defaultOpen: false,+ variant: "short",},render: (args: any) => <BottomTrayStory {...args} />,};@@ -153,12 +192,27 @@ export const Default = {export const OpenByDefault = {args: {defaultOpen: true,+ variant: "short",+ },+ render: (args: any) => <BottomTrayStory {...args} />,+};++export const LongVariant = {+ args: {+ defaultOpen: true,+ variant: "long",},render: (args: any) => <BottomTrayStory {...args} />,};// Example with custom trigger-const CustomTriggerStory = ({ defaultOpen = false }: { defaultOpen?: boolean }) => {+const CustomTriggerStory = ({+ defaultOpen = false,+ variant = "short",+}: {+ defaultOpen?: boolean;+ variant?: "short" | "long";+}) => {const [isOpen, setIsOpen] = useState(defaultOpen);const threadListManager = useThreadListManager({@@ -183,20 +237,24 @@ const CustomTriggerStory = ({ defaultOpen = false }: { defaultOpen?: boolean })const threadManager = useThreadManager({threadId: threadListManager.selectedThreadId,- loadThread: async () => [- {- id: crypto.randomUUID(),- role: "user",- type: "prompt",- message: "Hello",- },- {- id: crypto.randomUUID(),- role: "assistant",- type: "response",- message: [{ type: "text", text: "Hello! How can I help you today?" }],- },- ],+ loadThread: async (threadId) => {+ // Return empty for new thread (null), otherwise return existing messages+ if (!threadId) return [];+ return [+ {+ id: crypto.randomUUID(),+ role: "user",+ type: "prompt",+ message: "Hello",+ },+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: "Hello! How can I help you today?" }],+ },+ ];+ },onProcessMessage: async ({ message, threadManager }) => {const newMessage = Object.assign({}, message, { id: crypto.randomUUID() }) as Message;threadManager.appendMessages(newMessage);@@ -236,6 +294,29 @@ const CustomTriggerStory = ({ defaultOpen = false }: { defaultOpen?: boolean })<ScrollArea><Messages loader={<MessageLoading />} /></ScrollArea>+ <ConversationStarter+ variant={variant}+ starters={[+ {+ displayText:+ "Help me understand what features are available and how to get started with this application",+ prompt:+ "Help me understand what features are available and how to get started with this application",+ icon: <Zap size={16} />,+ },+ {+ displayText:+ "What can you help me with today? I need assistance with multiple tasks",+ prompt: "What can you help me with today? I need assistance with multiple tasks",+ icon: <MessageSquare size={16} />,+ },+ {+ displayText: "No icon example - this is a shorter prompt",+ prompt: "No icon example - this is a shorter prompt",+ icon: <></>, // Empty fragment = no icon+ },+ ]}+ /><Composer /></ThreadContainer></Container>@@ -247,6 +328,243 @@ const CustomTriggerStory = ({ defaultOpen = false }: { defaultOpen?: boolean })export const CustomTrigger = {args: {defaultOpen: false,+ variant: "short",+ },+ render: (args: any) => <CustomTriggerStory {...args} />,+};++export const CustomTriggerLongVariant = {+ args: {+ defaultOpen: true,+ variant: "long",},render: (args: any) => <CustomTriggerStory {...args} />,};++// Example with WelcomeScreen+const WelcomeScreenStory = ({+ defaultOpen = true,+ variant = "short",+}: {+ defaultOpen?: boolean;+ variant?: "short" | "long";+}) => {+ const [isOpen, setIsOpen] = useState(defaultOpen);++ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [], // Start with empty thread to show welcome screen+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = Object.assign({}, message, { id: crypto.randomUUID() }) as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ // this can be used instead of thread state+ const hasMessages = threadManager.messages.length > 0;++ return (+ <div className={styles.container}>+ <div className={styles.content}>+ <h1>Welcome Screen Example</h1>+ <p>This example shows the WelcomeScreen component with title, description, and logo.</p>+ </div>++ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Trigger onClick={() => setIsOpen(!isOpen)} isOpen={isOpen} />++ <Container logoUrl={logoUrl} agentName="Crayon Assistant" isOpen={isOpen}>+ <ThreadContainer>+ <Header onMinimize={() => setIsOpen(false)} />++ {hasMessages ? null : (+ <WelcomeScreen+ title="Hi, I'm Crayon Assistant"+ description="I can help you with questions about your account, products, and more."+ image={{ url: logoUrl }}+ />+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter+ variant={variant}+ starters={[+ {+ displayText: "Help me get started",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "What can you do?",+ prompt: "What can you do?",+ },+ ]}+ />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ </div>+ );+};++export const WithWelcomeScreen = {+ args: {+ defaultOpen: true,+ variant: "short",+ },+ render: (args: any) => <WelcomeScreenStory {...args} />,+};++export const WithWelcomeScreenLongVariant = {+ args: {+ defaultOpen: true,+ variant: "long",+ },+ render: (args: any) => <WelcomeScreenStory {...args} />,+};++// Example with custom children in WelcomeScreen+const CustomWelcomeScreenStory = ({+ defaultOpen = true,+ variant = "short",+}: {+ defaultOpen?: boolean;+ variant?: "short" | "long";+}) => {+ const [isOpen, setIsOpen] = useState(defaultOpen);++ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [],+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = Object.assign({}, message, { id: crypto.randomUUID() }) as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ const hasMessages = threadManager.messages.length > 0;++ return (+ <div className={styles.container}>+ <div className={styles.content}>+ <h1>Custom Welcome Screen Example</h1>+ <p>This example shows WelcomeScreen with custom children instead of props.</p>+ </div>++ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Trigger onClick={() => setIsOpen(!isOpen)} isOpen={isOpen} />++ <Container logoUrl={logoUrl} agentName="Crayon Assistant" isOpen={isOpen}>+ <ThreadContainer>+ <Header onMinimize={() => setIsOpen(false)} />++ {hasMessages ? null : (+ <WelcomeScreen>+ <div style={{ textAlign: "center" }}>+ <div+ style={{+ width: 80,+ height: 80,+ borderRadius: 16,+ background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",+ display: "flex",+ alignItems: "center",+ justifyContent: "center",+ margin: "0 auto 16px",+ }}+ >+ <Sparkles size={40} color="white" />+ </div>+ <h2 style={{ margin: "0 0 8px", fontSize: 20, fontWeight: 600 }}>+ Welcome to AI Assistant+ </h2>+ <p style={{ margin: 0, color: "rgba(0,0,0,0.5)", fontSize: 14 }}>+ Your personal AI helper for all your questions+ </p>+ </div>+ </WelcomeScreen>+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter+ variant={variant}+ starters={[+ {+ displayText: "Help me get started",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "What can you do?",+ prompt: "What can you do?",+ },+ ]}+ />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ </div>+ );+};++export const WithCustomWelcomeScreen = {+ args: {+ defaultOpen: true,+ variant: "short",+ },+ render: (args: any) => <CustomWelcomeScreenStory {...args} />,+};diff --git a/js/packages/react-ui/src/components/BottomTray/trigger.scss b/js/packages/react-ui/src/components/BottomTray/trigger.scssindex 43b493c4b..5201bca17 100644--- a/js/packages/react-ui/src/components/BottomTray/trigger.scss+++ b/js/packages/react-ui/src/components/BottomTray/trigger.scss@@ -14,7 +14,7 @@color: cssUtils.$accent-primary-text;box-shadow: cssUtils.$shadow-xl;cursor: pointer;- transition: all 0.2s ease;+ transition: all 0.1s ease;z-index: 1000;overflow: hidden;@@ -26,6 +26,12 @@&:active {transform: translateY(0);+ scale: 0.95;+ }++ // Desktop open state - shrink the trigger+ &--open {+ transform: scale(0.85);}// Mobilediff --git a/js/packages/react-ui/src/components/BottomTray/welcomeScreen.scss b/js/packages/react-ui/src/components/BottomTray/welcomeScreen.scssnew file mode 100644index 000000000..ef12c10c2--- /dev/null+++ b/js/packages/react-ui/src/components/BottomTray/welcomeScreen.scss@@ -0,0 +1,50 @@+@use "../../cssUtils" as cssUtils;++.crayon-bottom-tray-welcome-screen {+ display: flex;+ flex-direction: column;+ gap: cssUtils.$spacing-l;+ height: 100%;+ justify-content: center;+ align-items: center;++ // Image container - minimal wrapper, styling handled by consumer+ &__image-container {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ }++ // Default image styles when using { url: string }+ &__image {+ width: 64px;+ height: 64px;+ object-fit: cover;+ border-radius: cssUtils.$rounded-xl;+ }++ // Content container (title + description)+ &__content {+ display: flex;+ flex-direction: column;+ align-items: center;+ gap: cssUtils.$spacing-xs;+ text-align: center;+ }++ // Title/greeting text+ &__title {+ @include cssUtils.typography(heading, small);+ color: cssUtils.$primary-text;+ margin: 0;+ }++ // Description text+ &__description {+ @include cssUtils.typography(body, small);+ color: cssUtils.$secondary-text;+ margin: 0;+ max-width: 280px;+ }+}diff --git a/js/packages/react-ui/src/components/CopilotShell/ConversationStarter.tsx b/js/packages/react-ui/src/components/CopilotShell/ConversationStarter.tsxnew file mode 100644index 000000000..5679253af--- /dev/null+++ b/js/packages/react-ui/src/components/CopilotShell/ConversationStarter.tsx@@ -0,0 +1,145 @@+import { useThreadActions, useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ArrowUp, Lightbulb } from "lucide-react";+import { Fragment, ReactNode } from "react";+import { ConversationStarterIcon, ConversationStarterProps } from "../../types/ConversationStarter";+import { Separator } from "../Separator";++export type ConversationStarterVariant = "short" | "long";++interface ConversationStarterItemProps extends ConversationStarterProps {+ onClick: (prompt: string) => void;+ variant: ConversationStarterVariant;+}++/**+ * Renders the appropriate icon based on the icon prop value+ * - undefined: Show default lightbulb icon+ * - ReactNode: Show the provided icon (use <></> or React.Fragment for no icon)+ */+const renderIcon = (icon: ConversationStarterIcon | undefined): ReactNode => {+ if (icon === undefined) {+ return <Lightbulb size={16} />;+ }+ return icon;+};++const ConversationStarterItem = ({+ displayText,+ prompt,+ onClick,+ variant,+ icon,+}: ConversationStarterItemProps) => {+ const renderedIcon = renderIcon(icon);++ if (variant === "short") {+ return (+ <button+ type="button"+ className="crayon-copilot-shell-conversation-starter-item-short"+ onClick={() => onClick(prompt)}+ >+ {renderedIcon && (+ <span className="crayon-copilot-shell-conversation-starter-item-short__icon">+ {renderedIcon}+ </span>+ )}+ <span className="crayon-copilot-shell-conversation-starter-item-short__text">+ {displayText}+ </span>+ </button>+ );+ }++ // Long variant (detailed list style)+ return (+ <button+ type="button"+ className="crayon-copilot-shell-conversation-starter-item-long"+ onClick={() => onClick(prompt)}+ >+ <div className="crayon-copilot-shell-conversation-starter-item-long__content">+ {renderedIcon && (+ <span className="crayon-copilot-shell-conversation-starter-item-long__icon">+ {renderedIcon}+ </span>+ )}+ <span className="crayon-copilot-shell-conversation-starter-item-long__text">+ {displayText}+ </span>+ </div>+ <span className="crayon-copilot-shell-conversation-starter-item-long__arrow">+ <ArrowUp size={16} />+ </span>+ </button>+ );+};++export interface ConversationStarterContainerProps {+ starters: ConversationStarterProps[];+ className?: string;+ /**+ * Variant of the conversation starter+ * - "short": Pill-style horizontal buttons (default)+ * - "long": List items with icons and hover arrow+ */+ variant?: ConversationStarterVariant;+}++export const ConversationStarter = ({+ starters,+ className,+ variant = "short",+}: ConversationStarterContainerProps) => {+ const { processMessage } = useThreadActions();+ const { isRunning, messages } = useThreadState();++ const handleClick = (prompt: string) => {+ if (isRunning) return;+ processMessage({+ type: "prompt",+ role: "user",+ message: prompt,+ });+ };++ // Only show when there are no messages+ if (messages.length > 0) {+ return null;+ }++ if (starters.length === 0) {+ return null;+ }++ return (+ <div+ className={clsx(+ "crayon-copilot-shell-conversation-starter",+ `crayon-copilot-shell-conversation-starter--${variant}`,+ className,+ )}+ >+ {starters.map((item, index) => (+ <Fragment key={`${item.displayText}-${index}`}>+ <ConversationStarterItem+ displayText={item.displayText}+ prompt={item.prompt}+ icon={item.icon}+ onClick={handleClick}+ variant={variant}+ />+ {/* Add separator between items in long variant */}+ {variant === "long" && index < starters.length - 1 && (+ <div className="crayon-copilot-shell-conversation-starter__separator">+ <Separator />+ </div>+ )}+ </Fragment>+ ))}+ </div>+ );+};++export default ConversationStarter;diff --git a/js/packages/react-ui/src/components/CopilotShell/Thread.tsx b/js/packages/react-ui/src/components/CopilotShell/Thread.tsxindex f53a403bb..f9d3c45e4 100644--- a/js/packages/react-ui/src/components/CopilotShell/Thread.tsx+++ b/js/packages/react-ui/src/components/CopilotShell/Thread.tsx@@ -6,7 +6,7 @@ import {useThreadState,} from "@crayonai/react-core";import clsx from "clsx";-import { ArrowRight, Square } from "lucide-react";+import { ArrowUp, Square } from "lucide-react";import React, { memo, useEffect, useLayoutEffect, useRef } from "react";import { useComposerState } from "../../hooks/useComposerState";import { ScrollVariant, useScrollToBottom } from "../../hooks/useScrollToBottom";@@ -35,7 +35,20 @@ export const ThreadContainer = ({setArtifactRenderer(renderArtifact);}, [isArtifactActive, setIsArtifactActive]);- return <div className={clsx("crayon-copilot-shell-thread-container", className)}>{children}</div>;+ const { isInitialized } = useThreadManagerSelector((store) => ({+ isInitialized: store.isInitialized,+ }));++ return (+ <div+ className={clsx("crayon-copilot-shell-thread-container", className)}+ style={{+ visibility: isInitialized ? undefined : "hidden",+ }}+ >+ {children}+ </div>+ );};export const ScrollArea = ({@@ -268,7 +281,7 @@ export const Composer = ({ className }: { className?: string }) => {/><IconButtononClick={isRunning ? onCancel : handleSubmit}- icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowRight size="1em" />}+ icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowUp size="1em" />}/></div></div>diff --git a/js/packages/react-ui/src/components/CopilotShell/WelcomeScreen.tsx b/js/packages/react-ui/src/components/CopilotShell/WelcomeScreen.tsxnew file mode 100644index 000000000..b59125eef--- /dev/null+++ b/js/packages/react-ui/src/components/CopilotShell/WelcomeScreen.tsx@@ -0,0 +1,106 @@+import { useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ReactNode } from "react";++interface WelcomeScreenBaseProps {+ /**+ * Additional CSS class name+ */+ className?: string;+}++interface WelcomeScreenWithContentProps extends WelcomeScreenBaseProps {+ /**+ * The greeting/title text to display+ */+ title?: string;+ /**+ * Optional description text to add more context+ */+ description?: string;+ /**+ * Image to display - can be a URL object or a ReactNode+ * - { url: string }: Renders an <img> tag with default styling (64x64, object-fit: cover, rounded)+ * - ReactNode: Renders the provided element directly (for custom icons, styled images, etc.)+ */+ image?: { url: string } | ReactNode;+ /**+ * Children are not allowed when using props-based content+ */+ children?: never;+}++interface WelcomeScreenWithChildrenProps extends WelcomeScreenBaseProps {+ /**+ * Custom content to render inside the welcome screen+ * When children are provided, title, description, and image are ignored+ */+ children: ReactNode;+ title?: never;+ description?: never;+ image?: never;+}++export type WelcomeScreenProps = WelcomeScreenWithContentProps | WelcomeScreenWithChildrenProps;++/**+ * Type guard to check if image is a URL object+ */+const isImageUrl = (image: { url: string } | ReactNode): image is { url: string } => {+ return typeof image === "object" && image !== null && "url" in image;+};++export const WelcomeScreen = (props: WelcomeScreenProps) => {+ const { className } = props;++ const { messages } = useThreadState();++ // Only show when there are no messages+ if (messages.length > 0) {+ return null;+ }++ // Check if children are provided+ if ("children" in props && props.children) {+ return (+ <div className={clsx("crayon-copilot-shell-welcome-screen", className)}>{props.children}</div>+ );+ }++ // Props-based content+ const { title, description, image } = props as WelcomeScreenWithContentProps;++ const renderImage = () => {+ if (!image) return null;++ if (isImageUrl(image)) {+ return (+ <img+ src={image.url}+ alt={title || ""}+ className="crayon-copilot-shell-welcome-screen__image"+ />+ );+ }++ return image;+ };++ return (+ <div className={clsx("crayon-copilot-shell-welcome-screen", className)}>+ {image && (+ <div className="crayon-copilot-shell-welcome-screen__image-container">{renderImage()}</div>+ )}+ {(title || description) && (+ <div className="crayon-copilot-shell-welcome-screen__content">+ {title && <h2 className="crayon-copilot-shell-welcome-screen__title">{title}</h2>}+ {description && (+ <p className="crayon-copilot-shell-welcome-screen__description">{description}</p>+ )}+ </div>+ )}+ </div>+ );+};++export default WelcomeScreen;diff --git a/js/packages/react-ui/src/components/CopilotShell/conversationStarter.scss b/js/packages/react-ui/src/components/CopilotShell/conversationStarter.scssnew file mode 100644index 000000000..71ceb2806--- /dev/null+++ b/js/packages/react-ui/src/components/CopilotShell/conversationStarter.scss@@ -0,0 +1,140 @@+@use "../../cssUtils" as cssUtils;++// Container styles+.crayon-copilot-shell-conversation-starter {+ display: flex;+ padding: 0 cssUtils.$spacing-l;+ margin-bottom: cssUtils.$spacing-s;++ // Short variant - horizontal pill buttons+ &--short {+ flex-direction: column;+ gap: cssUtils.$spacing-s;+ }++ // Long variant - vertical list items with separators+ &--long {+ flex-direction: column;+ gap: cssUtils.$spacing-2xs;+ }++ // Separator wrapper for long variant+ &__separator {+ padding: cssUtils.$spacing-3xs cssUtils.$spacing-xs;+ }+}++// Short variant item (pill-style buttons)+.crayon-copilot-shell-conversation-starter-item-short {+ display: flex;+ align-items: flex-start;+ gap: cssUtils.$spacing-xs;+ width: fit-content;+ padding: cssUtils.$spacing-s cssUtils.$spacing-m;+ background-color: cssUtils.$bg-container;+ border: 1px solid cssUtils.$stroke-default;+ border-radius: cssUtils.$rounded-m;+ cursor: pointer;+ transition: all 0.15s ease;+ @include cssUtils.typography(body, small);+ color: cssUtils.$primary-text;+ text-align: left;++ // Icon container+ &__icon {+ display: flex;+ align-items: flex-start;+ justify-content: center;+ flex-shrink: 0;+ padding-top: cssUtils.$spacing-3xs;+ color: cssUtils.$primary-text;+ }++ // Text+ &__text {+ flex: 1;+ }++ &:not(:disabled):hover {+ background-color: cssUtils.$bg-sunk;+ border-color: cssUtils.$stroke-emphasis;+ }++ &:not(:disabled):active {+ background-color: cssUtils.$bg-sunk;+ }++ @media (max-width: 480px) {+ padding: cssUtils.$spacing-xs cssUtils.$spacing-s;+ }+}++// Long variant item (list-style with icon and arrow)+.crayon-copilot-shell-conversation-starter-item-long {+ display: flex;+ align-items: center;+ gap: cssUtils.$spacing-0;+ width: 100%;+ padding: cssUtils.$spacing-xs cssUtils.$spacing-s;+ background-color: transparent;+ border: none;+ border-radius: cssUtils.$rounded-m;+ cursor: pointer;+ transition: background-color 0.15s ease;+ @include cssUtils.typography(body, default);+ color: cssUtils.$primary-text;+ text-align: left;+ overflow: hidden;++ // Content wrapper (icon + text)+ &__content {+ display: flex;+ align-items: flex-start;+ gap: cssUtils.$spacing-s;+ flex: 1;+ min-width: 0;+ }++ // Icon container - aligned to top with padding to align with first line of text+ &__icon {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ padding-top: cssUtils.$spacing-2xs;+ color: cssUtils.$primary-text;+ }++ // Text - allows wrapping for long content+ &__text {+ flex: 1;+ min-width: 0;+ line-height: 1.5;+ // Text wraps naturally, no truncation+ }++ // Arrow icon (shown on hover)+ &__arrow {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ opacity: 0;+ transition: opacity 0.15s ease;+ color: cssUtils.$primary-text;+ }++ // Hover state+ &:not(:disabled):hover {+ background-color: cssUtils.$bg-sunk;++ .crayon-copilot-shell-conversation-starter-item-long__arrow {+ opacity: 1;+ }+ }++ // Active/pressed state+ &:not(:disabled):active {+ background-color: cssUtils.$interactive-pressed;+ }+}diff --git a/js/packages/react-ui/src/components/CopilotShell/copilotShell.scss b/js/packages/react-ui/src/components/CopilotShell/copilotShell.scssindex 16c7f0c47..32987f56b 100644--- a/js/packages/react-ui/src/components/CopilotShell/copilotShell.scss+++ b/js/packages/react-ui/src/components/CopilotShell/copilotShell.scss@@ -1,6 +1,8 @@@use "../../cssUtils" as cssUtils;@use "./thread.scss";@use "./header.scss";+@use "./conversationStarter.scss";+@use "./welcomeScreen.scss";.crayon-copilot-shell-container {display: flex;diff --git a/js/packages/react-ui/src/components/CopilotShell/index.ts b/js/packages/react-ui/src/components/CopilotShell/index.tsindex f19ab917b..7c3629b7c 100644--- a/js/packages/react-ui/src/components/CopilotShell/index.ts+++ b/js/packages/react-ui/src/components/CopilotShell/index.ts@@ -1,3 +1,5 @@export * from "./Container";+export * from "./ConversationStarter";export * from "./Header";export * from "./Thread";+export * from "./WelcomeScreen";diff --git a/js/packages/react-ui/src/components/CopilotShell/stories/Shell.mdx b/js/packages/react-ui/src/components/CopilotShell/stories/Shell.mdxnew file mode 100644index 000000000..9a5a5e101--- /dev/null+++ b/js/packages/react-ui/src/components/CopilotShell/stories/Shell.mdx@@ -0,0 +1,363 @@+import { Meta } from "@storybook/blocks";+import * as ShellStories from "./Shell.stories";++<Meta of={ShellStories} />++# CopilotShell++The CopilotShell is a **composable sidebar chat interface** designed to be embedded as a side panel in your application. It uses a composition pattern, giving you full control over placement and styling.++## Component Structure++```+ChatProvider+└── Container (sidebar panel)+ └── ThreadContainer+ ├── Header (logo, agent name)+ ├── WelcomeScreen (optional, shown when empty)+ ├── ScrollArea (scrollable message area)+ │ └── Messages+ ├── ConversationStarter (optional, shown when empty)+ └── Composer (text input)+```++## Basic Usage++```tsx+import { useState } from "react";+import { ChatProvider, useThreadListManager, useThreadManager } from "@crayonai/react-core";+import {+ Composer,+ Container,+ ConversationStarter,+ Header,+ MessageLoading,+ Messages,+ ScrollArea,+ ThreadContainer,+ WelcomeScreen,+} from "@crayonai/react-ui/CopilotShell";++function MyCopilot() {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async (threadId) => {+ if (!threadId) return [];+ // Load messages for thread+ return [];+ },+ onProcessMessage: async ({ message, threadManager }) => {+ threadManager.appendMessages({ ...message, id: crypto.randomUUID() });+ // Send message to your AI backend+ // Return assistant response+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: "Response from AI" }],+ },+ ];+ },+ responseTemplates: [],+ });++ const hasMessages = threadManager.messages.length > 0;++ return (+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl="/path/to/logo.png" agentName="AI Assistant">+ <ThreadContainer>+ <Header />++ {/* WelcomeScreen - shown when no messages */}+ {!hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={+ <img+ src="/path/to/logo.png"+ alt="AI Assistant"+ style={{ width: 64, height: 64, borderRadius: 16, objectFit: "cover" }}+ />+ }+ />+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter+ starters={[+ { displayText: "Help me get started", prompt: "Help me get started" },+ { displayText: "What can you do?", prompt: "What can you do?" },+ ]}+ />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ );+}+```++## Individual Components++### Container++The main wrapper for the CopilotShell sidebar.++```tsx+<Container+ logoUrl="/logo.png" // Logo shown in header+ agentName="AI Assistant" // Name shown in header+ className="custom-class" // Optional custom styling+>+ {children}+</Container>+```++### ThreadContainer++Wrapper for the thread content with optional artifact panel support.++```tsx+<ThreadContainer+ isArtifactActive={false} // Show artifact panel+ renderArtifact={() => <div />} // Artifact content+>+ {children}+</ThreadContainer>+```++### Header++The header with logo and agent name.++```tsx+<Header />+```++### ScrollArea++Scrollable container for messages with smart scroll behavior.++```tsx+<ScrollArea+ scrollVariant="user-message-anchor" // Scroll behavior+ userMessageSelector=".crayon-copilot-shell-thread-message-user" // CSS selector for user messages+>+ <Messages loader={<MessageLoading />} />+</ScrollArea>+```++### ConversationStarter++Clickable prompts shown when the thread is empty. Automatically submits the prompt as a message when clicked.++```tsx+<ConversationStarter+ variant="short" // "short" (pill buttons) or "long" (list items)+ starters={[+ {+ displayText: "Help me get started",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ { displayText: "What can you do?", prompt: "What can you do?" }, // Default lightbulb icon+ { displayText: "No icon example", prompt: "No icon", icon: <></> }, // No icon (use empty fragment)+ ]}+ className="custom-class" // Optional custom styling+/>+```++**Props:**++- `variant` - `"short"` (pill-style buttons) or `"long"` (list items with separators)+- `starters` - Array of objects with:+ - `displayText` - Text shown on the button+ - `prompt` - Message sent when clicked+ - `icon` - Optional: `ReactNode` for custom icon, `undefined` for default lightbulb, `<></>` (empty fragment) for no icon+- `className` - Optional additional CSS class++**Behavior:**++- Only visible when there are no messages in the thread+- Clicking a button submits the `prompt` as a user message+- Clicks are ignored when a response is being generated++### WelcomeScreen++A centered welcome message shown when the thread is empty. Supports either props-based content or custom children.++**Props-based usage with URL:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={{ url: "/path/to/logo.png" }}+ />+ );+}+```++**Props-based usage with styled image:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={+ <img+ src="/path/to/logo.png"+ alt="AI Assistant"+ style={{ width: 64, height: 64, borderRadius: 16, objectFit: "cover" }}+ />+ }+ />+ );+}+```++**Props-based usage with custom icon:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={<Sparkles size={32} />}+ />+ );+}+```++**Custom children usage:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen>+ <div style={{ textAlign: "center" }}>+ <MyCustomLogo />+ <h2>Welcome!</h2>+ <p>Custom welcome content</p>+ </div>+ </WelcomeScreen>+ );+}+```++**Props:**++- `title` - Greeting/title text (optional)+- `description` - Description text (optional)+- `image` - Image to display: `{ url: string }` for simple URL (renders with default 64x64 size, rounded corners), or `ReactNode` for custom styled elements (optional)+- `children` - Custom content (mutually exclusive with title/description/image)+- `className` - Additional CSS class (optional)++**Note:** You must conditionally render WelcomeScreen based on `hasMessages` state.++### Composer++Text input for sending messages.++```tsx+<Composer className="custom-class" />+```++## Layout Integration++CopilotShell is designed to be placed as a sidebar:++```tsx+function AppLayout() {+ const hasMessages = threadManager.messages.length > 0;++ return (+ <div style={{ display: "flex", height: "100vh" }}>+ {/* Main content area */}+ <main style={{ flex: 1 }}>{/* Your app content */}</main>++ {/* Copilot sidebar */}+ <aside style={{ width: 400, borderLeft: "1px solid #eee" }}>+ <ChatProvider {...}>+ <Container logoUrl={logo} agentName="Assistant">+ <ThreadContainer>+ <Header />+ {!hasMessages && (+ <WelcomeScreen+ title="Hi, I'm Assistant"+ description="How can I help you today?"+ image={+ <img+ src={logo}+ alt="Assistant"+ style={{ width: 64, height: 64, borderRadius: 16, objectFit: "cover" }}+ />+ }+ />+ )}+ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={[...]} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ </aside>+ </div>+ );+}+```++## Comparison with BottomTray++| Feature | CopilotShell | BottomTray |+| -------- | ------------------- | ---------------------- |+| Layout | Sidebar panel | Floating panel |+| Position | Fixed sidebar | Bottom-right corner |+| Trigger | Always visible | Floating button |+| Mobile | Responsive | Fullscreen |+| Use case | Main chat interface | Secondary/support chat |++## CSS Classes++All CopilotShell components use the `crayon-copilot-shell-` prefix:++- `.crayon-copilot-shell-thread-container`+- `.crayon-copilot-shell-thread-scroll-area`+- `.crayon-copilot-shell-thread-messages`+- `.crayon-copilot-shell-thread-message-user`+- `.crayon-copilot-shell-thread-message-assistant`+- `.crayon-copilot-shell-thread-composer`+- `.crayon-copilot-shell-conversation-starter`+- `.crayon-copilot-shell-conversation-starter-item-short`+- `.crayon-copilot-shell-conversation-starter-item-long`+- `.crayon-copilot-shell-welcome-screen`+- `.crayon-copilot-shell-welcome-screen__image-container`+- `.crayon-copilot-shell-welcome-screen__content`+- `.crayon-copilot-shell-welcome-screen__title`+- `.crayon-copilot-shell-welcome-screen__description`diff --git a/js/packages/react-ui/src/components/CopilotShell/stories/Shell.stories.tsx b/js/packages/react-ui/src/components/CopilotShell/stories/Shell.stories.tsxindex fecfb6aee..0041821da 100644--- a/js/packages/react-ui/src/components/CopilotShell/stories/Shell.stories.tsx+++ b/js/packages/react-ui/src/components/CopilotShell/stories/Shell.stories.tsx@@ -4,14 +4,17 @@ import {useThreadListManager,useThreadManager,} from "@crayonai/react-core";+import { Sparkles } from "lucide-react";import {Composer,Container,+ ConversationStarter,Header,MessageLoading,Messages,ScrollArea,ThreadContainer,+ WelcomeScreen,} from "../../CopilotShell";// @ts-ignoreimport styles from "./style.module.scss";@@ -19,11 +22,39 @@ import logoUrl from "./thesysdev_logo.jpeg";export default {title: "Components/CopilotShell",- tags: ["dev", "!autodocs"],+ tags: ["dev"],+ argTypes: {+ variant: {+ control: "select",+ options: ["short", "long"],+ description: "Conversation starter variant",+ },+ },};+const SAMPLE_STARTERS = [+ {+ displayText: "Tell me about my portfolio",+ prompt: "Tell me about the latest stock market trends and how they affect my portfolio",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "Who is the president of Venezuela and where is he currently located?",+ prompt: "Who is the president of Venezuela and where is he currently located?",+ // icon undefined = shows default lightbulb+ },+ {+ displayText: "Tell me about major stock (no icon)",+ prompt: "Tell me about major stock",+ icon: <></>, // Empty fragment = no icon+ },+];+export const Default = {- render: (args: any) => {+ args: {+ variant: "short",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {const threadListManager = useThreadListManager({createThread: async () => {return {@@ -64,7 +95,8 @@ export const Default = {const threadManager = useThreadManager({threadId: threadListManager.selectedThreadId,- loadThread: async () => {+ loadThread: async (threadId) => {+ if (!threadId) return [];return [{id: crypto.randomUUID(),@@ -76,11 +108,11 @@ export const Default = {id: crypto.randomUUID(),role: "assistant",type: "response",- message: [{ type: "text", text: "Hello" }],+ message: [{ type: "text", text: "Hello! How can I help you today?" }],},];},- onProcessMessage: async ({ message, threadManager, abortController }) => {+ onProcessMessage: async ({ message, threadManager }) => {const newMessage = Object.assign({}, message, {id: crypto.randomUUID(),}) as Message;@@ -91,7 +123,7 @@ export const Default = {id: crypto.randomUUID(),role: "assistant",type: "response",- message: [{ type: "text", text: "sadfasdf" }],+ message: [{ type: "text", text: "This is a response from the AI assistant." }],},];},@@ -108,6 +140,230 @@ export const Default = {<ScrollArea><Messages loader={<MessageLoading />} /></ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ </div>+ );+ },+};++export const LongVariant = {+ args: {+ variant: "long",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [], // Start with empty thread to show starters+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = Object.assign({}, message, {+ id: crypto.randomUUID(),+ }) as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ return (+ <div className={styles.container}>+ <div className={styles.left} />+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl={logoUrl} agentName="Crayon">+ <ThreadContainer>+ <Header />+ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ </div>+ );+ },+};++// Example with WelcomeScreen+export const WithWelcomeScreen = {+ args: {+ variant: "short",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [], // Start with empty thread to show welcome screen+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = Object.assign({}, message, {+ id: crypto.randomUUID(),+ }) as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ const hasMessages = threadManager.messages.length > 0;++ return (+ <div className={styles.container}>+ <div className={styles.left} />+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl={logoUrl} agentName="Crayon Assistant">+ <ThreadContainer>+ <Header />++ {hasMessages ? null : (+ <WelcomeScreen+ title="Hi, I'm Crayon Assistant"+ description="I can help you with questions about your account, products, and more."+ image={{ url: logoUrl }}+ />+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ </div>+ );+ },+};++// Example with custom children in WelcomeScreen+export const WithCustomWelcomeScreen = {+ args: {+ variant: "short",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [],+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = Object.assign({}, message, {+ id: crypto.randomUUID(),+ }) as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ const hasMessages = threadManager.messages.length > 0;++ return (+ <div className={styles.container}>+ <div className={styles.left} />+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl={logoUrl} agentName="Crayon Assistant">+ <ThreadContainer>+ <Header />++ {hasMessages ? null : (+ <WelcomeScreen>+ <div style={{ textAlign: "center" }}>+ <div+ style={{+ width: 80,+ height: 80,+ borderRadius: 16,+ background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",+ display: "flex",+ alignItems: "center",+ justifyContent: "center",+ margin: "0 auto 16px",+ }}+ >+ <Sparkles size={40} color="white" />+ </div>+ <h2 style={{ margin: "0 0 8px", fontSize: 20, fontWeight: 600 }}>+ Welcome to AI Assistant+ </h2>+ <p style={{ margin: 0, color: "rgba(0,0,0,0.5)", fontSize: 14 }}>+ Your personal AI helper for all your questions+ </p>+ </div>+ </WelcomeScreen>+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} /><Composer /></ThreadContainer></Container>diff --git a/js/packages/react-ui/src/components/CopilotShell/welcomeScreen.scss b/js/packages/react-ui/src/components/CopilotShell/welcomeScreen.scssnew file mode 100644index 000000000..df13edfbe--- /dev/null+++ b/js/packages/react-ui/src/components/CopilotShell/welcomeScreen.scss@@ -0,0 +1,50 @@+@use "../../cssUtils" as cssUtils;++.crayon-copilot-shell-welcome-screen {+ display: flex;+ flex-direction: column;+ gap: cssUtils.$spacing-l;+ height: 100%;+ justify-content: center;+ align-items: center;++ // Image container - minimal wrapper, styling handled by consumer+ &__image-container {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ }++ // Default image styles when using { url: string }+ &__image {+ width: 64px;+ height: 64px;+ object-fit: cover;+ border-radius: cssUtils.$rounded-xl;+ }++ // Content container (title + description)+ &__content {+ display: flex;+ flex-direction: column;+ align-items: center;+ gap: cssUtils.$spacing-xs;+ text-align: center;+ }++ // Title/greeting text+ &__title {+ @include cssUtils.typography(heading, small);+ color: cssUtils.$primary-text;+ margin: 0;+ }++ // Description text+ &__description {+ @include cssUtils.typography(body, small);+ color: cssUtils.$secondary-text;+ margin: 0;+ max-width: 280px;+ }+}diff --git a/js/packages/react-ui/src/components/CrayonChat/ComposedBottomTray.tsx b/js/packages/react-ui/src/components/CrayonChat/ComposedBottomTray.tsxindex ee9124b76..a6f06a2e3 100644--- a/js/packages/react-ui/src/components/CrayonChat/ComposedBottomTray.tsx+++ b/js/packages/react-ui/src/components/CrayonChat/ComposedBottomTray.tsx@@ -1,15 +1,20 @@+import { useThreadState } from "@crayonai/react-core";import { useState } from "react";import { ScrollVariant } from "../../hooks/useScrollToBottom";import {Composer,Container,+ ConversationStarter,Header,MessageLoading,Messages,ScrollArea,ThreadContainer,Trigger,+ WelcomeScreen,} from "../BottomTray";+import { ConversationStartersConfig, WelcomeMessageConfig } from "./types";+import { isChatEmpty, isWelcomeComponent } from "./utils";interface ComposedBottomTrayProps {logoUrl?: string;@@ -24,8 +29,59 @@ interface ComposedBottomTrayProps {onOpenChange?: (isOpen: boolean) => void;/** Default open state (uncontrolled) */defaultOpen?: boolean;+ /** Welcome message shown when thread is empty */+ welcomeMessage?: WelcomeMessageConfig;+ /** Conversation starters shown when thread is empty */+ conversationStarters?: ConversationStartersConfig;}+/**+ * Internal component to render welcome message based on thread state+ */+const WelcomeMessageRenderer = ({ welcomeMessage }: { welcomeMessage?: WelcomeMessageConfig }) => {+ const { messages, isLoadingMessages } = useThreadState();++ if (!welcomeMessage || isChatEmpty({ isLoadingMessages, messages })) {+ return null;+ }++ if (isWelcomeComponent(welcomeMessage)) {+ const CustomWelcome = welcomeMessage;+ // Wrap custom component with WelcomeScreen for proper container styling+ return (+ <WelcomeScreen>+ <CustomWelcome />+ </WelcomeScreen>+ );+ }++ return (+ <WelcomeScreen+ title={welcomeMessage.title}+ description={welcomeMessage.description}+ image={welcomeMessage.image}+ />+ );+};++const ConversationStartersRenderer = ({+ conversationStarters,+}: {+ conversationStarters?: ConversationStartersConfig;+}) => {+ const { messages, isLoadingMessages } = useThreadState();++ if (!conversationStarters || isChatEmpty({ isLoadingMessages, messages })) {+ return null;+ }++ return (+ <ConversationStarter+ variant={conversationStarters.variant}+ starters={conversationStarters.options}+ />+ );+};export const ComposedBottomTray = ({logoUrl = "https://crayonai.org/img/logo.png",agentName = "My Agent",@@ -36,6 +92,8 @@ export const ComposedBottomTray = ({isOpen: controlledIsOpen,onOpenChange,defaultOpen = false,+ welcomeMessage,+ conversationStarters,}: ComposedBottomTrayProps) => {const [uncontrolledIsOpen, setUncontrolledIsOpen] = useState(defaultOpen);@@ -53,16 +111,20 @@ export const ComposedBottomTray = ({<>{/* Trigger is always visible - toggles the tray (hidden on mobile when open) */}<Trigger onClick={() => handleOpenChange(!isOpen)} isOpen={isOpen}>- <img src={logoUrl} alt="Logo" className="crayon-bottom-tray-trigger-logo" />+ {logoUrl ? (+ <img src={logoUrl} alt="Logo" className="crayon-bottom-tray-trigger-logo" />+ ) : null}</Trigger>{/* Controlled container */}<Container logoUrl={logoUrl} agentName={agentName} isOpen={isOpen}><ThreadContainer isArtifactActive={isArtifactActive} renderArtifact={renderArtifact}><Header onMinimize={() => handleOpenChange(false)} />+ <WelcomeMessageRenderer welcomeMessage={welcomeMessage} /><ScrollArea scrollVariant={scrollVariant}><Messages loader={<MessageLoadingComponent />} /></ScrollArea>+ <ConversationStartersRenderer conversationStarters={conversationStarters} /><Composer /></ThreadContainer></Container>diff --git a/js/packages/react-ui/src/components/CrayonChat/ComposedCopilot.tsx b/js/packages/react-ui/src/components/CrayonChat/ComposedCopilot.tsxindex 2957757e8..30910f151 100644--- a/js/packages/react-ui/src/components/CrayonChat/ComposedCopilot.tsx+++ b/js/packages/react-ui/src/components/CrayonChat/ComposedCopilot.tsx@@ -1,13 +1,19 @@+import { useThreadState } from "@crayonai/react-core";import { ScrollVariant } from "../../hooks/useScrollToBottom";import {Composer,Container,+ ConversationStarter,Header,MessageLoading,Messages,ScrollArea,ThreadContainer,+ WelcomeScreen,} from "../CopilotShell";+import { ConversationStartersConfig, WelcomeMessageConfig } from "./types";+import { isChatEmpty, isWelcomeComponent } from "./utils";+interface ComposedCopilotProps {logoUrl?: string;agentName?: string;@@ -15,8 +21,59 @@ interface ComposedCopilotProps {scrollVariant: ScrollVariant;isArtifactActive?: boolean;renderArtifact?: () => React.ReactNode;+ /** Welcome message shown when thread is empty */+ welcomeMessage?: WelcomeMessageConfig;+ /** Conversation starters shown when thread is empty */+ conversationStarters?: ConversationStartersConfig;}+/**+ * Internal component to render welcome message based on thread state+ */+const WelcomeMessageRenderer = ({ welcomeMessage }: { welcomeMessage?: WelcomeMessageConfig }) => {+ const { messages, isLoadingMessages } = useThreadState();++ if (!welcomeMessage || isChatEmpty({ isLoadingMessages, messages })) {+ return null;+ }++ if (isWelcomeComponent(welcomeMessage)) {+ const CustomWelcome = welcomeMessage;+ // Wrap custom component with WelcomeScreen for proper container styling+ return (+ <WelcomeScreen>+ <CustomWelcome />+ </WelcomeScreen>+ );+ }++ return (+ <WelcomeScreen+ title={welcomeMessage.title}+ description={welcomeMessage.description}+ image={welcomeMessage.image}+ />+ );+};++const ConversationStartersRenderer = ({+ conversationStarters,+}: {+ conversationStarters?: ConversationStartersConfig;+}) => {+ const { messages, isLoadingMessages } = useThreadState();++ if (!conversationStarters || isChatEmpty({ isLoadingMessages, messages })) {+ return null;+ }++ return (+ <ConversationStarter+ variant={conversationStarters.variant}+ starters={conversationStarters.options}+ />+ );+};export const ComposedCopilot = ({logoUrl = "https://crayonai.org/img/logo.png",agentName = "My Agent",@@ -24,14 +81,18 @@ export const ComposedCopilot = ({scrollVariant,isArtifactActive,renderArtifact,+ welcomeMessage,+ conversationStarters,}: ComposedCopilotProps) => {return (<Container logoUrl={logoUrl} agentName={agentName}><ThreadContainer isArtifactActive={isArtifactActive} renderArtifact={renderArtifact}><Header />+ <WelcomeMessageRenderer welcomeMessage={welcomeMessage} /><ScrollArea scrollVariant={scrollVariant}><Messages loader={<MessageLoadingComponent />} /></ScrollArea>+ <ConversationStartersRenderer conversationStarters={conversationStarters} /><Composer /></ThreadContainer></Container>diff --git a/js/packages/react-ui/src/components/CrayonChat/ComposedStandalone.tsx b/js/packages/react-ui/src/components/CrayonChat/ComposedStandalone.tsxindex 83293a30c..61e41b58a 100644--- a/js/packages/react-ui/src/components/CrayonChat/ComposedStandalone.tsx+++ b/js/packages/react-ui/src/components/CrayonChat/ComposedStandalone.tsx@@ -1,7 +1,9 @@+import { useThreadState } from "@crayonai/react-core";import { ScrollVariant } from "../../hooks/useScrollToBottom";import {Composer,Container,+ ConversationStarter,MessageLoading,Messages,MobileHeader,@@ -13,7 +15,11 @@ import {SidebarSeparator,ThreadContainer,ThreadList,+ WelcomeScreen,} from "../Shell";+import { ConversationStartersConfig, WelcomeMessageConfig } from "./types";+import { isChatEmpty, isWelcomeComponent } from "./utils";+interface ComposedStandaloneProps {logoUrl?: string;agentName?: string;@@ -21,8 +27,70 @@ interface ComposedStandaloneProps {scrollVariant: ScrollVariant;isArtifactActive?: boolean;renderArtifact?: () => React.ReactNode;+ /** Welcome message shown when thread is empty */+ welcomeMessage?: WelcomeMessageConfig;+ /** Conversation starters shown when thread is empty */+ conversationStarters?: ConversationStartersConfig;}+/**+ * Internal component to render welcome message based on thread state+ * For Shell, WelcomeScreen includes built-in starters on desktop+ */+const WelcomeMessageRenderer = ({+ welcomeMessage,+ conversationStarters,+}: {+ welcomeMessage?: WelcomeMessageConfig;+ conversationStarters?: ConversationStartersConfig;+}) => {+ const { messages, isLoadingMessages } = useThreadState();++ if (!welcomeMessage || isChatEmpty({ isLoadingMessages, messages })) {+ return null;+ }++ if (isWelcomeComponent(welcomeMessage)) {+ const CustomWelcome = welcomeMessage;+ // Wrap custom component with WelcomeScreen for proper container styling+ // Note: starters are rendered separately via ConversationStarter component+ return (+ <WelcomeScreen>+ <CustomWelcome />+ </WelcomeScreen>+ );+ }++ return (+ <WelcomeScreen+ title={welcomeMessage.title}+ description={welcomeMessage.description}+ image={welcomeMessage.image}+ starters={conversationStarters?.options}+ starterVariant={conversationStarters?.variant}+ />+ );+};++const ConversationStartersRenderer = ({+ conversationStarters,+}: {+ conversationStarters?: ConversationStartersConfig;+}) => {+ const { messages, isLoadingMessages } = useThreadState();++ if (!conversationStarters || isChatEmpty({ isLoadingMessages, messages })) {+ return null;+ }++ return (+ <ConversationStarter+ variant={conversationStarters.variant}+ starters={conversationStarters.options}+ />+ );+};+export const ComposedStandalone = ({logoUrl = "https://crayonai.org/img/logo.png",agentName = "My Agent",@@ -30,6 +98,8 @@ export const ComposedStandalone = ({scrollVariant,isArtifactActive,renderArtifact,+ welcomeMessage,+ conversationStarters,}: ComposedStandaloneProps) => {return (<Container logoUrl={logoUrl} agentName={agentName}>@@ -43,9 +113,14 @@ export const ComposedStandalone = ({</SidebarContainer><ThreadContainer isArtifactActive={isArtifactActive} renderArtifact={renderArtifact}><MobileHeader />+ <WelcomeMessageRenderer+ welcomeMessage={welcomeMessage}+ conversationStarters={conversationStarters}+ /><ScrollArea scrollVariant={scrollVariant}><Messages loader={<MessageLoadingComponent />} /></ScrollArea>+ <ConversationStartersRenderer conversationStarters={conversationStarters} /><Composer /></ThreadContainer></Container>diff --git a/js/packages/react-ui/src/components/CrayonChat/CrayonChat.tsx b/js/packages/react-ui/src/components/CrayonChat/CrayonChat.tsxindex 11be2be58..fd27dc0ce 100644--- a/js/packages/react-ui/src/components/CrayonChat/CrayonChat.tsx+++ b/js/packages/react-ui/src/components/CrayonChat/CrayonChat.tsx@@ -18,6 +18,7 @@ import { ThemeProps, ThemeProvider } from "../ThemeProvider";import { ComposedBottomTray } from "./ComposedBottomTray";import { ComposedCopilot } from "./ComposedCopilot";import { ComposedStandalone } from "./ComposedStandalone";+import { ConversationStartersConfig, WelcomeMessageConfig } from "./types";type BaseCrayonChatProps = {// options used when threadManager not provided@@ -47,6 +48,11 @@ type BaseCrayonChatProps = {isArtifactActive?: boolean;renderArtifact?: () => React.ReactNode;++ /** Welcome message shown when thread is empty */+ welcomeMessage?: WelcomeMessageConfig;+ /** Conversation starters shown when thread is empty */+ conversationStarters?: ConversationStartersConfig;};type BottomTrayProps = {@@ -87,6 +93,8 @@ export const CrayonChat = (props: CrayonChatProps) => {disableThemeProvider,isArtifactActive,renderArtifact,+ welcomeMessage,+ conversationStarters,} = props;// Extract bottom-tray specific props if type is bottom-tray@@ -179,6 +187,8 @@ export const CrayonChat = (props: CrayonChatProps) => {scrollVariant={scrollVariant}isArtifactActive={isArtifactActive}renderArtifact={renderArtifact}+ welcomeMessage={welcomeMessage}+ conversationStarters={conversationStarters}/>) : type === "bottom-tray" ? (<ComposedBottomTray@@ -191,6 +201,8 @@ export const CrayonChat = (props: CrayonChatProps) => {isOpen={isOpen}onOpenChange={onOpenChange}defaultOpen={defaultOpen}+ welcomeMessage={welcomeMessage}+ conversationStarters={conversationStarters}/>) : (<ComposedStandalone@@ -200,6 +212,8 @@ export const CrayonChat = (props: CrayonChatProps) => {scrollVariant={scrollVariant}isArtifactActive={isArtifactActive}renderArtifact={renderArtifact}+ welcomeMessage={welcomeMessage}+ conversationStarters={conversationStarters}/>)}</ChatProvider>diff --git a/js/packages/react-ui/src/components/CrayonChat/composedBottomTray.scss b/js/packages/react-ui/src/components/CrayonChat/composedBottomTray.scssnew file mode 100644index 000000000..4f2370cb5--- /dev/null+++ b/js/packages/react-ui/src/components/CrayonChat/composedBottomTray.scss@@ -0,0 +1,8 @@+@use "../../cssUtils" as cssUtils;++.crayon-bottom-tray-trigger-logo {+ width: "100%";+ height: "100%";+ object-fit: "cover";+ border-radius: cssUtils.$rounded-m;+}diff --git a/js/packages/react-ui/src/components/CrayonChat/crayonChat.scss b/js/packages/react-ui/src/components/CrayonChat/crayonChat.scssindex e69de29bb..adb45f588 100644--- a/js/packages/react-ui/src/components/CrayonChat/crayonChat.scss+++ b/js/packages/react-ui/src/components/CrayonChat/crayonChat.scss@@ -0,0 +1 @@+@forward "./composedBottomTray.scss";diff --git a/js/packages/react-ui/src/components/CrayonChat/index.ts b/js/packages/react-ui/src/components/CrayonChat/index.tsindex 2d05fedb6..710f82a99 100644--- a/js/packages/react-ui/src/components/CrayonChat/index.ts+++ b/js/packages/react-ui/src/components/CrayonChat/index.ts@@ -2,3 +2,5 @@ export * from "./ComposedBottomTray";export * from "./ComposedCopilot";export * from "./ComposedStandalone";export { CrayonChat } from "./CrayonChat";+export type { ConversationStartersConfig, WelcomeMessageConfig } from "./types";+export { isChatEmpty, isWelcomeComponent } from "./utils";diff --git a/js/packages/react-ui/src/components/CrayonChat/stories/CrayonChat.mdx b/js/packages/react-ui/src/components/CrayonChat/stories/CrayonChat.mdxnew file mode 100644index 000000000..051e5e74e--- /dev/null+++ b/js/packages/react-ui/src/components/CrayonChat/stories/CrayonChat.mdx@@ -0,0 +1,457 @@+import { Meta } from "@storybook/blocks";+import * as CrayonChatStories from "./CrayonChat.stories";++<Meta of={CrayonChatStories} />++# CrayonChat++CrayonChat is a **high-level, batteries-included chat component** that provides a complete chat experience with minimal configuration. It wraps all the complexity of the composable shell components (Shell, CopilotShell, BottomTray) into a single, easy-to-use component.++## When to Use CrayonChat++Use `CrayonChat` when you want:++- A quick, ready-to-use chat interface+- Minimal boilerplate code+- Automatic thread management+- Built-in welcome screens and conversation starters++Use the individual shell components (Shell, CopilotShell, BottomTray) when you need:++- Full control over the UI composition+- Custom layouts+- Advanced customization++## Types++CrayonChat supports three different layout types:++| Type | Description |+| ------------- | ----------------------------------------------------- |+| `standalone` | Full-page chat with sidebar for thread list (default) |+| `copilot` | Side panel chat without sidebar |+| `bottom-tray` | Floating chat panel in the bottom-right corner |++## Basic Usage++```tsx+import { CrayonChat } from "@crayonai/react-ui";++function App() {+ return (+ <CrayonChat+ processMessage={async ({ messages, threadId, abortController }) => {+ // Send messages to your AI backend+ const response = await fetch("/api/chat", {+ method: "POST",+ body: JSON.stringify({ messages, threadId }),+ signal: abortController.signal,+ });+ return response;+ }}+ type="standalone"+ logoUrl="/path/to/logo.png"+ agentName="AI Assistant"+ />+ );+}+```++## With Welcome Message and Conversation Starters++```tsx+import { CrayonChat } from "@crayonai/react-ui";+import { Sparkles, Zap } from "lucide-react";++function App() {+ return (+ <CrayonChat+ processMessage={...}+ type="standalone"+ logoUrl="/path/to/logo.png"+ agentName="AI Assistant"+ welcomeMessage={{+ title: "Hi, I'm AI Assistant",+ description: "I can help you with questions about your account, products, and more.",+ image: { url: "/path/to/logo.png" },+ }}+ conversationStarters={{+ variant: "short", // or "long"+ options: [+ {+ displayText: "Help me get started",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "What can you do?",+ prompt: "What can you do?",+ // No icon = default lightbulb+ },+ {+ displayText: "Tell me about features",+ prompt: "Tell me about your features",+ icon: <Zap size={16} />,+ },+ ],+ }}+ />+ );+}+```++## Bottom Tray Type++The bottom-tray type provides a floating chat interface with a built-in trigger button (bottom-right corner):++```tsx+import { CrayonChat } from "@crayonai/react-ui";++function App() {+ return (+ <CrayonChat+ processMessage={...}+ type="bottom-tray"+ logoUrl="/logo.png"+ agentName="AI Assistant"+ welcomeMessage={{+ title: "Need help?",+ description: "I'm here to assist you.",+ image: { url: "/logo.png" },+ }}+ conversationStarters={{+ variant: "short",+ options: [+ { displayText: "Get started", prompt: "Help me get started" },+ ],+ }}+ />+ );+}+```++**Note:** The bottom-tray includes a built-in floating trigger button that opens/closes the tray. You don't need to add your own toggle button.++### Controlled Mode (Optional)++If you need programmatic control over the tray's open state:++```tsx+import { useState } from "react";+import { CrayonChat } from "@crayonai/react-ui";++function App() {+ const [isOpen, setIsOpen] = useState(false);++ // Example: Open tray programmatically after some action+ const handleSomeAction = () => {+ setIsOpen(true);+ };++ return (+ <CrayonChat+ processMessage={...}+ type="bottom-tray"+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ logoUrl="/logo.png"+ agentName="AI Assistant"+ />+ );+}+```++## Copilot Type++The copilot type is ideal for side panel integrations:++```tsx+import { CrayonChat } from "@crayonai/react-ui";++function App() {+ return (+ <div style={{ display: "flex" }}>+ <main style={{ flex: 1 }}>+ {/* Your app content */}+ </main>+ <aside style={{ width: 400, borderLeft: "1px solid #eee" }}>+ <CrayonChat+ processMessage={...}+ type="copilot"+ logoUrl="/logo.png"+ agentName="Assistant"+ welcomeMessage={{+ title: "Hi, I'm your copilot",+ description: "Ask me anything about your work.",+ }}+ />+ </aside>+ </div>+ );+}+```++## Props++### Core Props++| Prop | Type | Description |+| ---------------- | -------------------------------------------- | ------------------------------------- |+| `type` | `"standalone" \| "copilot" \| "bottom-tray"` | Layout type (default: `"standalone"`) |+| `processMessage` | `(params) => Promise<Response>` | Handler for processing messages |+| `logoUrl` | `string` | URL for the logo image |+| `agentName` | `string` | Name displayed in the header |++### Welcome Message++| Prop | Type | Description |+| ---------------- | ---------------------- | ----------------------------- |+| `welcomeMessage` | `WelcomeMessageConfig` | Welcome message configuration |++`WelcomeMessageConfig` can be either:++**Props-based configuration:**++```typescript+{+ title?: string;+ description?: string;+ image?: { url: string } | ReactNode;+ // { url: string } - Renders with default 64x64 size, rounded corners+ // ReactNode - Full control over styling (e.g., <img />, <Sparkles />)+}+```++**Custom component:**++```typescript+React.ComponentType<any>;+// Note: Custom components are wrapped with WelcomeScreen for proper container styling+```++### Conversation Starters++| Prop | Type | Description |+| ---------------------- | ---------------------------- | ----------------------------------- |+| `conversationStarters` | `ConversationStartersConfig` | Conversation starters configuration |++```typescript+interface ConversationStartersConfig {+ variant?: "short" | "long";+ options: Array<{+ displayText: string;+ prompt: string;+ icon?: ReactNode; // undefined = default lightbulb, <></> = no icon+ }>;+}+```++**Icon options:**++- `undefined` (not provided) - Shows default lightbulb icon+- `<Sparkles size={16} />` - Custom icon+- `<></>` (empty fragment) - No icon++### Bottom Tray Props++These props only apply when `type="bottom-tray"`. The tray includes a built-in trigger button, so these are optional for controlled mode:++| Prop | Type | Description |+| -------------- | --------------------------- | ----------------------------------------------- |+| `isOpen` | `boolean` | Controlled open state (optional) |+| `onOpenChange` | `(isOpen: boolean) => void` | Callback when open state changes (optional) |+| `defaultOpen` | `boolean` | Initial open state, default: `false` (optional) |++### Advanced Props++| Prop | Type | Description |+| ------------------------- | ------------------------------ | ------------------------------- |+| `threadManager` | `ThreadManager` | Custom thread manager |+| `threadListManager` | `ThreadListManager` | Custom thread list manager |+| `responseTemplates` | `ResponseTemplate[]` | Response templates |+| `createThread` | `(message) => Promise<Thread>` | Custom thread creation |+| `onUpdateMessage` | `(props) => void` | Message update callback |+| `processStreamedMessage` | `function` | Custom stream processor |+| `theme` | `ThemeProps` | Theme configuration |+| `scrollVariant` | `ScrollVariant` | Scroll behavior variant |+| `disableThemeProvider` | `boolean` | Disable built-in theme provider |+| `messageLoadingComponent` | `() => ReactNode` | Custom loading component |+| `isArtifactActive` | `boolean` | Show artifact panel |+| `renderArtifact` | `() => ReactNode` | Artifact content renderer |++## Custom Welcome Component++You can provide a custom welcome component instead of the props-based configuration. The custom component will be wrapped with `WelcomeScreen` for proper container styling:++```tsx+import { CrayonChat } from "@crayonai/react-ui";+import { Sparkles } from "lucide-react";++const MyCustomWelcome = () => (+ <div style={{ textAlign: "center" }}>+ <div+ style={{+ width: 80,+ height: 80,+ borderRadius: 16,+ background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",+ display: "flex",+ alignItems: "center",+ justifyContent: "center",+ margin: "0 auto 16px",+ }}+ >+ <Sparkles size={40} color="white" />+ </div>+ <h2 style={{ margin: "0 0 8px", fontSize: 20, fontWeight: 600 }}>+ Welcome to My App+ </h2>+ <p style={{ margin: 0, color: "rgba(0,0,0,0.5)", fontSize: 14 }}>+ This is a custom welcome screen+ </p>+ </div>+);++<CrayonChat+ processMessage={...}+ welcomeMessage={MyCustomWelcome}+/>+```++**Note:** When using a custom component, conversation starters are rendered separately below the welcome screen.++## Conversation Starter Variants++### Short Variant (default)++Pill-style buttons that wrap horizontally:++```tsx+import { Sparkles } from "lucide-react";++// In your component:+conversationStarters={{+ variant: "short",+ options: [+ { displayText: "With custom icon", prompt: "Prompt 1", icon: <Sparkles size={16} /> },+ { displayText: "Default lightbulb", prompt: "Prompt 2" }, // icon undefined = lightbulb+ { displayText: "No icon", prompt: "Prompt 3", icon: <></> }, // empty fragment = no icon+ ],+}}+```++### Long Variant++Vertical list with separators and hover arrows:++```tsx+import { Sparkles } from "lucide-react";++// In your component:+conversationStarters={{+ variant: "long",+ options: [+ {+ displayText: "This is a longer prompt that explains more context",+ prompt: "Full prompt text",+ icon: <Sparkles size={16} />,+ },+ ],+}}+```++## Using Custom Thread Managers++For advanced use cases, you can provide your own thread managers:++```tsx+import { useThreadListManager, useThreadManager } from "@crayonai/react-core";++function App() {+ const threadListManager = useThreadListManager({+ createThread: async () => ({ ... }),+ fetchThreadList: async () => [...],+ deleteThread: async (id) => { ... },+ updateThread: async (thread) => thread,+ onSwitchToNew: () => {},+ onSelectThread: (threadId) => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async (threadId) => [...],+ onProcessMessage: async ({ message, threadManager }) => [...],+ responseTemplates: [],+ });++ return (+ <CrayonChat+ threadListManager={threadListManager}+ threadManager={threadManager}+ type="standalone"+ welcomeMessage={{ title: "Hello!" }}+ />+ );+}+```++## Theming++CrayonChat uses CSS custom properties for theming. You can customize colors, spacing, and typography:++```tsx+<CrayonChat+ theme={{+ primaryColor: "#6366f1",+ backgroundColor: "#f8fafc",+ // ... other theme options+ }}+ processMessage={...}+/>+```++Or disable the built-in theme provider to use your own:++```tsx+<CrayonChat+ disableThemeProvider+ processMessage={...}+/>+```++## Migration from Composed Components++If you're currently using the individual shell components and want to migrate to CrayonChat:++**Before (using Shell components):**++```tsx+<ChatProvider threadListManager={...} threadManager={...}>+ <Container logoUrl={logo} agentName="Assistant">+ <SidebarContainer>...</SidebarContainer>+ <ThreadContainer>+ <MobileHeader />+ <WelcomeScreen title="Hello" />+ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={[...]} />+ <Composer />+ </ThreadContainer>+ </Container>+</ChatProvider>+```++**After (using CrayonChat):**++```tsx+<CrayonChat+ threadListManager={...}+ threadManager={...}+ type="standalone"+ logoUrl={logo}+ agentName="Assistant"+ welcomeMessage={{ title: "Hello" }}+ conversationStarters={{ options: [...] }}+/>+```diff --git a/js/packages/react-ui/src/components/CrayonChat/stories/CrayonChat.stories.tsx b/js/packages/react-ui/src/components/CrayonChat/stories/CrayonChat.stories.tsxindex bb729e15b..885436cf9 100644--- a/js/packages/react-ui/src/components/CrayonChat/stories/CrayonChat.stories.tsx+++ b/js/packages/react-ui/src/components/CrayonChat/stories/CrayonChat.stories.tsx@@ -1,10 +1,13 @@import { Message, useThreadListManager, useThreadManager } from "@crayonai/react-core";+import { Sparkles, Zap } from "lucide-react";import { useState } from "react";+import logoUrl from "../../BottomTray/stories/thesysdev_logo.jpeg";import { CrayonChat } from "../CrayonChat";+import { ConversationStartersConfig, WelcomeMessageConfig } from "../types";export default {title: "Components/CrayonChat",- tags: ["dev", "!autodocs"],+ tags: ["dev"],argTypes: {type: {control: "select",@@ -18,13 +21,62 @@ export default {},};+// Sample welcome message config+const SAMPLE_WELCOME_MESSAGE: WelcomeMessageConfig = {+ title: "Hi, I'm Crayon Assistant",+ description: "I can help you with questions about your account, products, and more.",+ image: { url: logoUrl },+};++// Sample conversation starters+const SAMPLE_STARTERS: ConversationStartersConfig = {+ variant: "short",+ options: [+ {+ displayText: "Help me get started",+ prompt: "Help me get started with Crayon",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "What can you do?",+ prompt: "What can you do?",+ },+ {+ displayText: "Tell me about features",+ prompt: "Tell me about your features",+ icon: <Zap size={16} />,+ },+ ],+};++// Sample long variant starters+const LONG_STARTERS: ConversationStartersConfig = {+ variant: "long",+ options: [+ {+ displayText: "Help me get started with this application and guide me through the features",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "What can you do? I'd like to know all your capabilities",+ prompt: "What can you do?",+ },+ {+ displayText: "Tell me about your advanced features and how I can use them effectively",+ prompt: "Tell me about your features",+ icon: <Zap size={16} />,+ },+ ],+};+const CrayonChatStory = (args: any) => {const [isOpen, setIsOpen] = useState(args.defaultOpen ?? false);const threadListManager = useThreadListManager({createThread: async () => {return {threadId: crypto.randomUUID(),- title: "test",+ title: "New Chat",createdAt: new Date(),isRunning: false,};@@ -32,24 +84,9 @@ const CrayonChatStory = (args: any) => {fetchThreadList: async () => {await new Promise((resolve) => setTimeout(resolve, 1000));return [- {- threadId: "1",- title: "test",- createdAt: new Date(),- isRunning: false,- },- {- threadId: "2",- title: "test 2",- createdAt: new Date(),- isRunning: false,- },- {- threadId: "3",- title: "test 3",- createdAt: new Date(),- isRunning: false,- },+ { threadId: "1", title: "Previous Chat 1", createdAt: new Date(), isRunning: false },+ { threadId: "2", title: "Previous Chat 2", createdAt: new Date(), isRunning: false },+ { threadId: "3", title: "Previous Chat 3", createdAt: new Date(), isRunning: false },];},deleteThread: async () => {},@@ -60,26 +97,23 @@ const CrayonChatStory = (args: any) => {const threadManager = useThreadManager({threadId: threadListManager.selectedThreadId,- loadThread: async () => {+ shouldResetThreadState: threadListManager.shouldResetThreadState,+ loadThread: async (threadId) => {+ // Return empty to show welcome screen and conversation starters+ if (!threadId) return [];return [- {- id: crypto.randomUUID(),- role: "user",- type: "prompt",- message: "Hello",- },+ { id: crypto.randomUUID(), role: "user", type: "prompt", message: "Hello" },{id: crypto.randomUUID(),role: "assistant",type: "response",- message: [{ type: "text", text: "Hello" }],+ message: [{ type: "text", text: "Hello! How can I help you today?" }],},];+ // return [];},- onProcessMessage: async ({ message, threadManager, abortController }) => {- const newMessage = Object.assign({}, message, {- id: crypto.randomUUID(),- }) as Message;+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = Object.assign({}, message, { id: crypto.randomUUID() }) as Message;threadManager.appendMessages(newMessage);await new Promise((resolve) => setTimeout(resolve, 1000));return [@@ -87,7 +121,12 @@ const CrayonChatStory = (args: any) => {id: crypto.randomUUID(),role: "assistant",type: "response",- message: [{ type: "text", text: "sadfasdf" }],+ message: [+ {+ type: "text",+ text: `You said: "${message.message}". This is a response from the AI assistant.`,+ },+ ],},];},@@ -123,11 +162,16 @@ const CrayonChatStory = (args: any) => {isOpen={isOpen}onOpenChange={setIsOpen}defaultOpen={args.defaultOpen}+ welcomeMessage={args.welcomeMessage}+ conversationStarters={args.conversationStarters}+ logoUrl={logoUrl}+ agentName="Crayon Assistant"/></div>);};+// Default standalone without welcome/startersexport const Default = {args: {type: "standalone",@@ -135,6 +179,45 @@ export const Default = {render: CrayonChatStory,};+// Standalone with welcome message and conversation starters+export const StandaloneWithWelcome = {+ args: {+ type: "standalone",+ welcomeMessage: SAMPLE_WELCOME_MESSAGE,+ conversationStarters: SAMPLE_STARTERS,+ },+ render: CrayonChatStory,+};++// Standalone with long variant starters+export const StandaloneLongStarters = {+ args: {+ type: "standalone",+ welcomeMessage: SAMPLE_WELCOME_MESSAGE,+ conversationStarters: LONG_STARTERS,+ },+ render: CrayonChatStory,+};++// Copilot type+export const Copilot = {+ args: {+ type: "copilot",+ },+ render: CrayonChatStory,+};++// Copilot with welcome message and starters+export const CopilotWithWelcome = {+ args: {+ type: "copilot",+ welcomeMessage: SAMPLE_WELCOME_MESSAGE,+ conversationStarters: SAMPLE_STARTERS,+ },+ render: CrayonChatStory,+};++// Bottom Tray typeexport const BottomTray = {args: {type: "bottom-tray",@@ -143,6 +226,7 @@ export const BottomTray = {render: CrayonChatStory,};+// Bottom Tray open by defaultexport const BottomTrayOpen = {args: {type: "bottom-tray",@@ -150,3 +234,25 @@ export const BottomTrayOpen = {},render: CrayonChatStory,};++// Bottom Tray with welcome message and starters+export const BottomTrayWithWelcome = {+ args: {+ type: "bottom-tray",+ defaultOpen: true,+ welcomeMessage: SAMPLE_WELCOME_MESSAGE,+ conversationStarters: SAMPLE_STARTERS,+ },+ render: CrayonChatStory,+};++// Bottom Tray with long variant starters+export const BottomTrayLongStarters = {+ args: {+ type: "bottom-tray",+ defaultOpen: true,+ welcomeMessage: SAMPLE_WELCOME_MESSAGE,+ conversationStarters: LONG_STARTERS,+ },+ render: CrayonChatStory,+};diff --git a/js/packages/react-ui/src/components/CrayonChat/types.ts b/js/packages/react-ui/src/components/CrayonChat/types.tsnew file mode 100644index 000000000..0cdc8822a--- /dev/null+++ b/js/packages/react-ui/src/components/CrayonChat/types.ts@@ -0,0 +1,66 @@+import { ReactNode } from "react";+import { ConversationStarterProps } from "../../types/ConversationStarter";++/**+ * Welcome message configuration for CrayonChat.+ *+ * Can be either:+ * - A custom React component that will be wrapped with WelcomeScreen for styling+ * - An object with title, description, and optional image+ *+ * @example+ * // Props-based configuration+ * const welcomeMessage: WelcomeMessageConfig = {+ * title: "Hi, I'm AI Assistant",+ * description: "I can help you with your questions.",+ * image: { url: "/logo.png" }, // or a ReactNode for custom styling+ * };+ *+ * @example+ * // Custom component+ * const MyCustomWelcome = () => <div>Custom welcome content</div>;+ * const welcomeMessage: WelcomeMessageConfig = MyCustomWelcome;+ */+export type WelcomeMessageConfig =+ | React.ComponentType<any>+ | {+ /** Title text displayed in the welcome screen */+ title?: string;+ /** Description text displayed below the title */+ description?: string;+ /**+ * Image to display in the welcome screen.+ * - `{ url: string }` - Renders with default 64x64 size, rounded corners+ * - `ReactNode` - Full control over styling (e.g., `<img />`, `<Sparkles />`)+ */+ image?: { url: string } | ReactNode;+ };++/**+ * Configuration for conversation starters in CrayonChat.+ *+ * Conversation starters are clickable prompts shown when the thread is empty,+ * helping users begin a conversation with predefined options.+ *+ * @example+ * const starters: ConversationStartersConfig = {+ * variant: "short", // "short" for pill buttons, "long" for list items+ * options: [+ * { displayText: "Help me get started", prompt: "Help me get started" },+ * { displayText: "What can you do?", prompt: "What can you do?", icon: <Sparkles /> },+ * ],+ * };+ */+export interface ConversationStartersConfig {+ /**+ * Visual variant for the conversation starters.+ * - `"short"` - Pill-style buttons that wrap horizontally (default)+ * - `"long"` - Vertical list with separators and hover arrows+ */+ variant?: "short" | "long";+ /**+ * Array of conversation starter options.+ * Each option has displayText, prompt, and optional icon.+ */+ options: ConversationStarterProps[];+}diff --git a/js/packages/react-ui/src/components/CrayonChat/utils/index.ts b/js/packages/react-ui/src/components/CrayonChat/utils/index.tsnew file mode 100644index 000000000..c0bae27e1--- /dev/null+++ b/js/packages/react-ui/src/components/CrayonChat/utils/index.ts@@ -0,0 +1,37 @@+import { Message } from "@crayonai/react-core";+import { WelcomeMessageConfig } from "../types";++/**+ * Type guard to check if a WelcomeMessageConfig is a custom React component.+ *+ * Use this to differentiate between a custom component and a props-based+ * configuration when rendering the welcome message.+ *+ * @param config - The welcome message configuration to check+ * @returns `true` if config is a React component, `false` if it's a props object+ *+ * @example+ * if (isWelcomeComponent(welcomeMessage)) {+ * // welcomeMessage is a React.ComponentType+ * const CustomWelcome = welcomeMessage;+ * return <CustomWelcome />;+ * } else {+ * // welcomeMessage is { title?, description?, image? }+ * return <WelcomeScreen {...welcomeMessage} />;+ * }+ */+export const isWelcomeComponent = (+ config: WelcomeMessageConfig,+): config is React.ComponentType<any> => {+ return typeof config === "function";+};++export const isChatEmpty = ({+ isLoadingMessages,+ messages,+}: {+ isLoadingMessages: boolean | undefined;+ messages: Message[];+}) => {+ return isLoadingMessages || messages.length > 0;+};diff --git a/js/packages/react-ui/src/components/Shell/ConversationStarter.tsx b/js/packages/react-ui/src/components/Shell/ConversationStarter.tsxnew file mode 100644index 000000000..90b9baace--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/ConversationStarter.tsx@@ -0,0 +1,137 @@+import { useThreadActions, useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ArrowUp, Lightbulb } from "lucide-react";+import { Fragment, ReactNode } from "react";+import { ConversationStarterIcon, ConversationStarterProps } from "../../types/ConversationStarter";+import { Separator } from "../Separator";++export type ConversationStarterVariant = "short" | "long";++interface ConversationStarterItemProps extends ConversationStarterProps {+ onClick: (prompt: string) => void;+ variant: ConversationStarterVariant;+}++/**+ * Renders the appropriate icon based on the icon prop value+ * - undefined: Show default lightbulb icon+ * - ReactNode: Show the provided icon (use <></> or React.Fragment for no icon)+ */+const renderIcon = (icon: ConversationStarterIcon | undefined): ReactNode => {+ if (icon === undefined) {+ return <Lightbulb size={16} />;+ }+ return icon;+};++const ConversationStarterItem = ({+ displayText,+ prompt,+ onClick,+ variant,+ icon,+}: ConversationStarterItemProps) => {+ const renderedIcon = renderIcon(icon);++ if (variant === "short") {+ return (+ <button+ type="button"+ className="crayon-shell-conversation-starter-item-short"+ onClick={() => onClick(prompt)}+ >+ {renderedIcon && (+ <span className="crayon-shell-conversation-starter-item-short__icon">{renderedIcon}</span>+ )}+ <span className="crayon-shell-conversation-starter-item-short__text">{displayText}</span>+ </button>+ );+ }++ // Long variant (detailed list style)+ return (+ <button+ type="button"+ className="crayon-shell-conversation-starter-item-long"+ onClick={() => onClick(prompt)}+ >+ <div className="crayon-shell-conversation-starter-item-long__content">+ {renderedIcon && (+ <span className="crayon-shell-conversation-starter-item-long__icon">{renderedIcon}</span>+ )}+ <span className="crayon-shell-conversation-starter-item-long__text">{displayText}</span>+ </div>+ <span className="crayon-shell-conversation-starter-item-long__arrow">+ <ArrowUp size={16} />+ </span>+ </button>+ );+};++export interface ConversationStarterContainerProps {+ starters: ConversationStarterProps[];+ className?: string;+ /**+ * Variant of the conversation starter+ * - "short": Pill-style buttons that wrap (default)+ * - "long": Vertical list items with icons and hover arrow+ */+ variant?: ConversationStarterVariant;+}++export const ConversationStarter = ({+ starters,+ className,+ variant = "short",+}: ConversationStarterContainerProps) => {+ const { processMessage } = useThreadActions();+ const { isRunning, messages } = useThreadState();++ const handleClick = (prompt: string) => {+ if (isRunning) return;+ processMessage({+ type: "prompt",+ role: "user",+ message: prompt,+ });+ };++ // Only show when there are no messages+ if (messages.length > 0) {+ return null;+ }++ if (starters.length === 0) {+ return null;+ }++ return (+ <div+ className={clsx(+ "crayon-shell-conversation-starter",+ `crayon-shell-conversation-starter--${variant}`,+ className,+ )}+ >+ {starters.map((item, index) => (+ <Fragment key={`${item.displayText}-${index}`}>+ <ConversationStarterItem+ displayText={item.displayText}+ prompt={item.prompt}+ icon={item.icon}+ onClick={handleClick}+ variant={variant}+ />+ {/* Add separator between items in long variant */}+ {variant === "long" && index < starters.length - 1 && (+ <div className="crayon-shell-conversation-starter__separator">+ <Separator />+ </div>+ )}+ </Fragment>+ ))}+ </div>+ );+};++export default ConversationStarter;diff --git a/js/packages/react-ui/src/components/Shell/Thread.tsx b/js/packages/react-ui/src/components/Shell/Thread.tsxindex 486d73f09..a2eaa464a 100644--- a/js/packages/react-ui/src/components/Shell/Thread.tsx+++ b/js/packages/react-ui/src/components/Shell/Thread.tsx@@ -1,17 +1,13 @@import {Message,MessageProvider,- useThreadActions,useThreadManagerSelector,useThreadState,} from "@crayonai/react-core";import clsx from "clsx";-import { ArrowRight, Square } from "lucide-react";-import React, { memo, useEffect, useLayoutEffect, useRef } from "react";+import React, { memo, useEffect, useRef } from "react";import { useLayoutContext } from "../../context/LayoutContext";-import { useComposerState } from "../../hooks/useComposerState";import { ScrollVariant, useScrollToBottom } from "../../hooks/useScrollToBottom";-import { IconButton } from "../IconButton";import { MessageLoading as MessageLoadingComponent } from "../MessageLoading";import { ResizableSeparator } from "./ResizableSeparator";import { useShellStore } from "./store";@@ -43,6 +39,10 @@ export const ThreadContainer = ({setArtifactRenderer(renderArtifact);}, [isArtifactActive, renderArtifact, setIsArtifactActive, setArtifactRenderer]);+ const { isInitialized } = useThreadManagerSelector((store) => ({+ isInitialized: store.isInitialized,+ }));+// Desktop-only: Handle resize logic for artifact panelconst {containerRef,@@ -63,6 +63,9 @@ export const ThreadContainer = ({className={clsx("crayon-shell-thread-container", className, {"crayon-shell-thread-container--artifact-active": isArtifactActive,})}+ style={{+ visibility: isInitialized ? undefined : "hidden",+ }}><div className="crayon-shell-thread-wrapper" ref={containerRef}>{/* Chat panel - always visible */}@@ -282,57 +285,5 @@ export const Messages = ({);};-export const Composer = ({ className }: { className?: string }) => {- const { textContent, setTextContent } = useComposerState();- const { processMessage, onCancel } = useThreadActions();- const { isRunning, isLoadingMessages } = useThreadState();- const inputRef = useRef<HTMLTextAreaElement>(null);-- const handleSubmit = () => {- if (!textContent.trim() || isRunning || isLoadingMessages) {- return;- }-- processMessage({- type: "prompt",- role: "user",- message: textContent,- });-- setTextContent("");- };-- useLayoutEffect(() => {- const input = inputRef.current;- if (!input) {- return;- }-- input.style.height = "0px";- input.style.height = `${input.scrollHeight}px`;- }, [textContent]);-- return (- <div className={clsx("crayon-shell-thread-composer", className)}>- <div className="crayon-shell-thread-composer__input-wrapper">- <textarea- ref={inputRef}- value={textContent}- onChange={(e) => setTextContent(e.target.value)}- className="crayon-shell-thread-composer__input"- placeholder="Type your message..."- onKeyDown={(e) => {- if (e.key === "Enter" && !e.shiftKey) {- e.preventDefault();- handleSubmit();- }- }}- />- <IconButton- onClick={isRunning ? onCancel : handleSubmit}- icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowRight size="1em" />}- />- </div>- </div>- );-};+// Re-export Composer from components+export { Composer } from "./components";diff --git a/js/packages/react-ui/src/components/Shell/WelcomeScreen.tsx b/js/packages/react-ui/src/components/Shell/WelcomeScreen.tsxnew file mode 100644index 000000000..d02570878--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/WelcomeScreen.tsx@@ -0,0 +1,133 @@+import { useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ReactNode } from "react";+import { ConversationStarterProps } from "../../types/ConversationStarter";+import { DesktopWelcomeComposer } from "./components";+import { ConversationStarter, ConversationStarterVariant } from "./ConversationStarter";++interface WelcomeScreenBaseProps {+ /**+ * Additional CSS class name+ */+ className?: string;+}++interface WelcomeScreenWithContentProps extends WelcomeScreenBaseProps {+ /**+ * The greeting/title text to display+ */+ title?: string;+ /**+ * Optional description text to add more context+ */+ description?: string;+ /**+ * Image to display - can be a URL object or a ReactNode+ * - { url: string }: Renders an <img> tag with default styling (64x64, object-fit: cover, rounded)+ * - ReactNode: Renders the provided element directly (for custom icons, styled images, etc.)+ */+ image?: { url: string } | ReactNode;+ /**+ * Conversation starters to show below the composer+ */+ starters?: ConversationStarterProps[];+ /**+ * Variant of the conversation starters+ */+ starterVariant?: ConversationStarterVariant;+ /**+ * Children are not allowed when using props-based content+ */+ children?: never;+}++interface WelcomeScreenWithChildrenProps extends WelcomeScreenBaseProps {+ /**+ * Custom content to render inside the welcome screen+ * When children are provided, title, description, and image are ignored+ */+ children: ReactNode;+ title?: never;+ description?: never;+ image?: never;+ starters?: never;+ starterVariant?: never;+}++export type WelcomeScreenProps = WelcomeScreenWithContentProps | WelcomeScreenWithChildrenProps;++/**+ * Type guard to check if image is a URL object+ */+const isImageUrl = (image: { url: string } | ReactNode): image is { url: string } => {+ return typeof image === "object" && image !== null && "url" in image;+};++export const WelcomeScreen = (props: WelcomeScreenProps) => {+ const { className, starters = [], starterVariant = "long" } = props;++ const { messages } = useThreadState();++ // Only show when there are no messages+ if (messages.length > 0) {+ return null;+ }++ // Check if children are provided+ if ("children" in props && props.children) {+ return <div className={clsx("crayon-shell-welcome-screen", className)}>{props.children}</div>;+ }++ // Props-based content+ const { title, description, image } = props as WelcomeScreenWithContentProps;++ const renderImage = () => {+ if (!image) return null;++ if (isImageUrl(image)) {+ return (+ <img src={image.url} alt={title || ""} className="crayon-shell-welcome-screen__image" />+ );+ }++ return image;+ };++ return (+ <div+ className={clsx(+ "crayon-shell-welcome-screen",+ "crayon-shell-welcome-screen--with-composer",+ className,+ )}+ >+ <div className="crayon-shell-welcome-screen__header">+ {image && (+ <div className="crayon-shell-welcome-screen__image-container">{renderImage()}</div>+ )}+ {(title || description) && (+ <div className="crayon-shell-welcome-screen__content">+ {title && <h2 className="crayon-shell-welcome-screen__title">{title}</h2>}+ {description && (+ <p className="crayon-shell-welcome-screen__description">{description}</p>+ )}+ </div>+ )}+ </div>+ {/* Desktop-only welcome composer */}+ <div className="crayon-shell-welcome-screen__composer-starters-container">+ <div className="crayon-shell-welcome-screen__desktop-composer">+ <DesktopWelcomeComposer />+ </div>+ {/* Desktop-only conversation starters */}+ {starters.length > 0 && (+ <div className="crayon-shell-welcome-screen__desktop-starters">+ <ConversationStarter starters={starters} variant={starterVariant} />+ </div>+ )}+ </div>+ </div>+ );+};++export default WelcomeScreen;diff --git a/js/packages/react-ui/src/components/Shell/components/Composer.tsx b/js/packages/react-ui/src/components/Shell/components/Composer.tsxnew file mode 100644index 000000000..9d570ce85--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/components/Composer.tsx@@ -0,0 +1,68 @@+import { useThreadActions, useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ArrowUp, Square } from "lucide-react";+import { useLayoutEffect, useRef } from "react";+import { useComposerState } from "../../../hooks/useComposerState";+import { IconButton } from "../../IconButton";++export interface ComposerProps {+ className?: string;+ placeholder?: string;+}++export const Composer = ({ className, placeholder = "Type your message..." }: ComposerProps) => {+ const { textContent, setTextContent } = useComposerState();+ const { processMessage, onCancel } = useThreadActions();+ const { isRunning, isLoadingMessages } = useThreadState();+ const inputRef = useRef<HTMLTextAreaElement>(null);++ const handleSubmit = () => {+ if (!textContent.trim() || isRunning || isLoadingMessages) {+ return;+ }++ processMessage({+ type: "prompt",+ role: "user",+ message: textContent,+ });++ setTextContent("");+ };++ useLayoutEffect(() => {+ const input = inputRef.current;+ if (!input) {+ return;+ }++ input.style.height = "0px";+ input.style.height = `${input.scrollHeight}px`;+ }, [textContent]);++ return (+ <div className={clsx("crayon-shell-thread-composer", className)}>+ <div className="crayon-shell-thread-composer__input-wrapper">+ <textarea+ ref={inputRef}+ value={textContent}+ onChange={(e) => setTextContent(e.target.value)}+ className="crayon-shell-thread-composer__input"+ placeholder={placeholder}+ onKeyDown={(e) => {+ if (e.key === "Enter" && !e.shiftKey) {+ e.preventDefault();+ handleSubmit();+ }+ }}+ />+ <IconButton+ onClick={isRunning ? onCancel : handleSubmit}+ icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowUp size="1em" />}+ />+ </div>+ </div>+ );+};++export default Composer;diff --git a/js/packages/react-ui/src/components/Shell/components/DesktopWelcomeComposer.tsx b/js/packages/react-ui/src/components/Shell/components/DesktopWelcomeComposer.tsxnew file mode 100644index 000000000..5d0afe8a9--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/components/DesktopWelcomeComposer.tsx@@ -0,0 +1,74 @@+import { useThreadActions, useThreadState } from "@crayonai/react-core";+import clsx from "clsx";+import { ArrowUp, Square } from "lucide-react";+import { useLayoutEffect, useRef } from "react";+import { useComposerState } from "../../../hooks/useComposerState";+import { IconButton } from "../../IconButton";++export interface DesktopWelcomeComposerProps {+ className?: string;+ placeholder?: string;+}++export const DesktopWelcomeComposer = ({+ className,+ placeholder = "Type your message...",+}: DesktopWelcomeComposerProps) => {+ const { textContent, setTextContent } = useComposerState();+ const { processMessage, onCancel } = useThreadActions();+ const { isRunning, isLoadingMessages } = useThreadState();+ const inputRef = useRef<HTMLTextAreaElement>(null);++ const handleSubmit = () => {+ if (!textContent.trim() || isRunning || isLoadingMessages) {+ return;+ }++ processMessage({+ type: "prompt",+ role: "user",+ message: textContent,+ });++ setTextContent("");+ };++ useLayoutEffect(() => {+ const input = inputRef.current;+ if (!input) {+ return;+ }++ input.style.height = "0px";+ input.style.height = `${input.scrollHeight}px`;+ }, [textContent]);++ return (+ <div className={clsx("crayon-shell-desktop-welcome-composer", className)}>+ <div className="crayon-shell-desktop-welcome-composer__input-container">+ <textarea+ ref={inputRef}+ value={textContent}+ onChange={(e) => setTextContent(e.target.value)}+ className="crayon-shell-desktop-welcome-composer__input"+ placeholder={placeholder}+ onKeyDown={(e) => {+ if (e.key === "Enter" && !e.shiftKey) {+ e.preventDefault();+ handleSubmit();+ }+ }}+ />+ </div>+ <div className="crayon-shell-desktop-welcome-composer__actions">+ <IconButton+ onClick={isRunning ? onCancel : handleSubmit}+ disabled={!textContent.trim() && !isRunning}+ icon={isRunning ? <Square size="1em" fill="currentColor" /> : <ArrowUp size="1em" />}+ />+ </div>+ </div>+ );+};++export default DesktopWelcomeComposer;diff --git a/js/packages/react-ui/src/components/Shell/components/composer.scss b/js/packages/react-ui/src/components/Shell/components/composer.scssnew file mode 100644index 000000000..18b5f2b1b--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/components/composer.scss@@ -0,0 +1,48 @@+@use "../../../cssUtils" as cssUtils;++$center-align-spacing: calc(32px + cssUtils.$spacing-s);++.crayon-shell-thread-composer {+ max-width: 880px;+ width: 100%;+ margin: 0 auto cssUtils.$spacing-m;+ padding: 0 $center-align-spacing;++ .crayon-shell-container--mobile & {+ margin: 0;+ padding: cssUtils.$spacing-m 14px;+ background-color: cssUtils.$bg-container;+ }++ .crayon-shell-thread-container--artifact-active & {+ padding-left: 0;+ padding-right: cssUtils.$spacing-m;+ }++ &__input-wrapper {+ border: 1.256px solid cssUtils.$stroke-default;+ border-radius: cssUtils.$rounded-xl;+ display: flex;+ align-items: flex-end;+ gap: cssUtils.$spacing-s;+ padding: cssUtils.$spacing-m;+ }++ &__input {+ flex-grow: 1;+ padding: 0;+ resize: none;+ margin: auto 0px;+ max-height: 154px;+ outline: none;+ border: none;+ background: transparent;+ overflow: hidden;+ @include cssUtils.typography(body, default);+ color: cssUtils.$primary-text;++ &::placeholder {+ color: cssUtils.$disabled-text;+ }+ }+}diff --git a/js/packages/react-ui/src/components/Shell/components/desktopWelcomeComposer.scss b/js/packages/react-ui/src/components/Shell/components/desktopWelcomeComposer.scssnew file mode 100644index 000000000..96fca862c--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/components/desktopWelcomeComposer.scss@@ -0,0 +1,60 @@+@use "../../../cssUtils" as cssUtils;++.crayon-shell-desktop-welcome-composer {+ display: flex;+ flex-direction: column;+ gap: cssUtils.$spacing-m;+ padding: cssUtils.$spacing-m;+ background-color: cssUtils.$bg-container;+ border: 1px solid cssUtils.$stroke-interactive-el;+ border-radius: cssUtils.$rounded-2xl;+ box-shadow: cssUtils.$shadow-s;+ width: 100%;+ max-width: 800px;++ // Input container+ &__input-container {+ display: flex;+ padding-left: cssUtils.$spacing-3xs;+ }++ // Textarea input+ &__input {+ flex: 1;+ padding: 0;+ resize: none;+ max-height: 200px;+ min-height: 24px;+ outline: none;+ border: none;+ background: transparent;+ overflow: hidden;+ @include cssUtils.typography(body, default);+ color: cssUtils.$primary-text;++ &::placeholder {+ color: cssUtils.$secondary-text;+ }+ }++ // Actions row (attachment + submit)+ &__actions {+ display: flex;+ flex-direction: row-reverse;+ align-items: center;+ justify-content: space-between;+ }++ // Action buttons base+ &__action-button {+ display: flex;+ align-items: center;+ justify-content: center;+ width: 32px;+ height: 32px;+ border-radius: cssUtils.$rounded-m;+ cursor: pointer;+ transition: all 0.15s ease;+ flex-shrink: 0;+ }+}diff --git a/js/packages/react-ui/src/components/Shell/components/index.ts b/js/packages/react-ui/src/components/Shell/components/index.tsnew file mode 100644index 000000000..b3792db6d--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/components/index.ts@@ -0,0 +1,2 @@+export * from "./Composer";+export * from "./DesktopWelcomeComposer";diff --git a/js/packages/react-ui/src/components/Shell/conversationStarter.scss b/js/packages/react-ui/src/components/Shell/conversationStarter.scssnew file mode 100644index 000000000..9d30f9d09--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/conversationStarter.scss@@ -0,0 +1,156 @@+@use "../../cssUtils" as cssUtils;++$center-align-spacing: calc(32px + cssUtils.$spacing-s);++// Container styles+.crayon-shell-conversation-starter {+ width: 100%;+ max-width: 880px;+ margin: 0 auto;+ padding: 0 $center-align-spacing cssUtils.$spacing-m;++ // Short variant - horizontal wrapping buttons+ &--short {+ display: flex;+ flex-wrap: wrap;+ gap: cssUtils.$spacing-s;+ }++ // Long variant - vertical stacked list with separators+ &--long {+ display: flex;+ flex-direction: column;+ gap: cssUtils.$spacing-2xs;+ }++ // Separator wrapper for long variant+ &__separator {+ padding: cssUtils.$spacing-3xs cssUtils.$spacing-xs;+ }++ // Mobile adjustments+ .crayon-shell-container--mobile & {+ padding: 0 cssUtils.$spacing-l;+ }++ // Artifact active adjustments+ .crayon-shell-thread-container--artifact-active & {+ padding-left: 0;+ padding-right: cssUtils.$spacing-m;+ }+}++// Short variant item (pill-style buttons that wrap)+.crayon-shell-conversation-starter-item-short {+ display: flex;+ align-items: center;+ gap: cssUtils.$spacing-xs;+ width: fit-content;+ padding: cssUtils.$spacing-s cssUtils.$spacing-m;+ background-color: cssUtils.$bg-container;+ border: 1px solid cssUtils.$stroke-default;+ border-radius: cssUtils.$rounded-m;+ cursor: pointer;+ transition: all 0.15s ease;+ @include cssUtils.typography(body, default);+ color: cssUtils.$primary-text;+ text-align: left;++ // Icon container+ &__icon {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ color: cssUtils.$primary-text;+ }++ // Text+ &__text {+ flex: 1;+ white-space: nowrap;+ }++ &:not(:disabled):hover {+ background-color: cssUtils.$interactive-hover;+ border-color: cssUtils.$stroke-emphasis;+ }++ &:not(:disabled):active {+ background-color: cssUtils.$interactive-pressed;+ }++ @media (max-width: 480px) {+ padding: cssUtils.$spacing-s cssUtils.$spacing-m;+ }+}++// Long variant item (list-style with icon and arrow)+.crayon-shell-conversation-starter-item-long {+ display: flex;+ align-items: center;+ gap: cssUtils.$spacing-0;+ width: 100%;+ padding: cssUtils.$spacing-xs cssUtils.$spacing-m;+ background-color: transparent;+ border: none;+ border-radius: cssUtils.$rounded-m;+ cursor: pointer;+ transition: background-color 0.15s ease;+ @include cssUtils.typography(body, default);+ color: cssUtils.$primary-text;+ text-align: left;+ overflow: hidden;++ // Content wrapper (icon + text)+ &__content {+ display: flex;+ align-items: flex-start;+ gap: cssUtils.$spacing-s;+ flex: 1;+ min-width: 0;+ }++ // Icon container - aligned to top with padding to align with first line of text+ &__icon {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ padding-top: cssUtils.$spacing-2xs;+ color: cssUtils.$primary-text;+ }++ // Text - allows wrapping for long content+ &__text {+ flex: 1;+ min-width: 0;+ line-height: 1.5;+ // Text wraps naturally, no truncation+ }++ // Arrow icon (shown on hover)+ &__arrow {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ opacity: 0;+ transition: opacity 0.15s ease;+ color: cssUtils.$primary-text;+ }++ // Hover state+ &:not(:disabled):hover {+ background-color: cssUtils.$bg-sunk;++ .crayon-shell-conversation-starter-item-long__arrow {+ opacity: 1;+ }+ }++ // Active/pressed state+ &:not(:disabled):active {+ background-color: cssUtils.$interactive-pressed;+ }+}diff --git a/js/packages/react-ui/src/components/Shell/index.ts b/js/packages/react-ui/src/components/Shell/index.tsindex 6df8637f3..5d9e046e4 100644--- a/js/packages/react-ui/src/components/Shell/index.ts+++ b/js/packages/react-ui/src/components/Shell/index.ts@@ -1,7 +1,10 @@+export * from "./components";export * from "./Container";+export * from "./ConversationStarter";export * from "./MobileHeader";export * from "./NewChatButton";export * from "./Sidebar";export * from "./store";export * from "./Thread";export * from "./ThreadList";+export * from "./WelcomeScreen";diff --git a/js/packages/react-ui/src/components/Shell/shell.scss b/js/packages/react-ui/src/components/Shell/shell.scssindex 6fa3ced8c..1b25e3aa2 100644--- a/js/packages/react-ui/src/components/Shell/shell.scss+++ b/js/packages/react-ui/src/components/Shell/shell.scss@@ -4,6 +4,10 @@@use "./thread.scss";@use "./mobileHeader.scss";@use "./resizableSeparator.scss";+@use "./conversationStarter.scss";+@use "./welcomeScreen.scss";+@use "./components/desktopWelcomeComposer.scss";+@use "./components/composer.scss";.crayon-shell-container {display: flex;diff --git a/js/packages/react-ui/src/components/Shell/stories/Shell.mdx b/js/packages/react-ui/src/components/Shell/stories/Shell.mdxnew file mode 100644index 000000000..1eb6cef9c--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/stories/Shell.mdx@@ -0,0 +1,357 @@+import { Meta } from "@storybook/blocks";+import * as ShellStories from "./Shell.stories";++<Meta of={ShellStories} />++# Shell++The Shell is a **full-page composable chat interface** with a sidebar for thread management. It's designed for applications where chat is the primary interface, providing a complete desktop and mobile experience.++## Component Structure++```+ChatProvider+└── Container (full-page wrapper)+ ├── SidebarContainer (collapsible sidebar)+ │ ├── SidebarHeader (logo, agent name, collapse button)+ │ └── SidebarContent+ │ ├── NewChatButton+ │ ├── SidebarSeparator+ │ └── ThreadList+ └── ThreadContainer (main chat area)+ ├── MobileHeader (mobile-only header)+ ├── ScrollArea (scrollable message area)+ │ └── Messages+ ├── ConversationStarter (optional, shown when empty)+ └── Composer (text input)+```++## Basic Usage++```tsx+import { ChatProvider, useThreadListManager, useThreadManager } from "@crayonai/react-core";+import {+ Composer,+ Container,+ ConversationStarter,+ MessageLoading,+ Messages,+ MobileHeader,+ NewChatButton,+ ScrollArea,+ SidebarContainer,+ SidebarContent,+ SidebarHeader,+ SidebarSeparator,+ ThreadContainer,+ ThreadList,+} from "@crayonai/react-ui/Shell";++function MyShell() {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async (threadId) => {+ if (!threadId) return [];+ // Load messages for thread+ return [];+ },+ onProcessMessage: async ({ message, threadManager }) => {+ threadManager.appendMessages({ ...message, id: crypto.randomUUID() });+ // Send message to your AI backend+ // Return assistant response+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: "Response from AI" }],+ },+ ];+ },+ responseTemplates: [],+ });++ return (+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl="/path/to/logo.png" agentName="AI Assistant">+ <SidebarContainer>+ <SidebarHeader />+ <SidebarContent>+ <NewChatButton />+ <SidebarSeparator />+ <ThreadList />+ </SidebarContent>+ </SidebarContainer>+ <ThreadContainer>+ <MobileHeader />+ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter+ starters={[+ { displayText: "Help me get started", prompt: "Help me get started" },+ { displayText: "What can you do?", prompt: "What can you do?" },+ ]}+ />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ );+}+```++## Individual Components++### Container++The main full-page wrapper for the Shell.++```tsx+<Container+ logoUrl="/logo.png" // Logo shown in sidebar header+ agentName="AI Assistant" // Name shown in sidebar header+ className="custom-class" // Optional custom styling+>+ {children}+</Container>+```++### Sidebar Components++The sidebar provides thread management and navigation.++```tsx+<SidebarContainer>+ <SidebarHeader /> {/* Logo, name, collapse button */}+ <SidebarContent>+ <NewChatButton /> {/* Creates new thread */}+ <SidebarSeparator /> {/* Visual separator */}+ <ThreadList /> {/* List of existing threads */}+ </SidebarContent>+</SidebarContainer>+```++### ThreadContainer++Wrapper for the main chat area with optional artifact panel support.++```tsx+<ThreadContainer+ isArtifactActive={false} // Show artifact panel (desktop: side-by-side, mobile: overlay)+ renderArtifact={() => <div />} // Artifact content+>+ {children}+</ThreadContainer>+```++### MobileHeader++Header shown only on mobile devices with sidebar toggle.++```tsx+<MobileHeader />+```++### ScrollArea++Scrollable container for messages with smart scroll behavior.++```tsx+<ScrollArea+ scrollVariant="user-message-anchor" // Scroll behavior+ userMessageSelector=".crayon-shell-thread-message-user" // CSS selector for user messages+>+ <Messages loader={<MessageLoading />} />+</ScrollArea>+```++### ConversationStarter++Full-width clickable buttons shown when the thread is empty. Automatically submits the prompt as a message when clicked.++```tsx+<ConversationStarter+ variant="short" // "short" (pill buttons) or "long" (list items)+ starters={[+ {+ displayText: "Help me get started",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ { displayText: "What can you do?", prompt: "What can you do?" }, // Default lightbulb icon+ { displayText: "No icon example", prompt: "No icon", icon: <></> }, // No icon (use empty fragment)+ ]}+ className="custom-class" // Optional custom styling+/>+```++**Props:**++- `variant` - `"short"` (pill-style buttons) or `"long"` (list items with separators)+- `starters` - Array of objects with:+ - `displayText` - Text shown on the button+ - `prompt` - Message sent when clicked+ - `icon` - Optional: `ReactNode` for custom icon, `undefined` for default lightbulb, `<></>` (empty fragment) for no icon+- `className` - Optional additional CSS class++**Behavior:**++- Only visible when there are no messages in the thread+- Clicking a button submits the `prompt` as a user message+- Clicks are ignored when a response is being generated+- Respects Shell layout (centered with max-width, mobile padding)++### WelcomeScreen++A centered welcome message shown when the thread is empty. On desktop, includes a built-in composer and optional conversation starters.++**Props-based usage with URL:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={{ url: "/path/to/logo.png" }}+ starters={[+ { displayText: "Help me get started", prompt: "Help me get started" },+ { displayText: "What can you do?", prompt: "What can you do?" },+ ]}+ starterVariant="long" // "short" or "long" (default: "long")+ />+ );+}+```++**Props-based usage with styled image:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen+ title="Hi, I'm AI Assistant"+ description="I can help you with your questions."+ image={+ <img+ src="/path/to/logo.png"+ alt="AI Assistant"+ style={{ width: 64, height: 64, borderRadius: 16, objectFit: "cover" }}+ />+ }+ starters={[{ displayText: "Help me get started", prompt: "Help me get started" }]}+ />+ );+}+```++**Custom children usage:**++```tsx+{+ !hasMessages && (+ <WelcomeScreen>+ <div style={{ textAlign: "center" }}>+ <MyCustomLogo />+ <h2>Welcome!</h2>+ <p>Custom welcome content</p>+ </div>+ </WelcomeScreen>+ );+}+```++**Props:**++- `title` - Greeting/title text (optional)+- `description` - Description text (optional)+- `image` - Image to display: `{ url: string }` for simple URL (renders with default 64x64 size, rounded corners), or `ReactNode` for custom styled elements (optional)+- `starters` - Conversation starters to show below the composer (desktop only)+- `starterVariant` - `"short"` or `"long"` for starter style (default: `"long"`)+- `children` - Custom content (mutually exclusive with title/description/image)+- `className` - Additional CSS class (optional)++**Desktop behavior:**++- Includes a built-in composer centered in the welcome screen+- Conversation starters appear below the composer+- The regular Composer component is hidden when WelcomeScreen is present++**Note:** You must conditionally render WelcomeScreen based on `hasMessages` state.++### Composer++Text input for sending messages.++```tsx+<Composer className="custom-class" />+```++## Desktop vs Mobile++The Shell automatically adapts to screen size:++| Feature | Desktop | Mobile |+| --------------------- | ----------------------- | ------------------------------------- |+| Sidebar | Collapsible side panel | Hidden, accessible via hamburger menu |+| Header | In sidebar | MobileHeader at top of thread |+| Artifact panel | Resizable side-by-side | Full-screen overlay |+| Conversation starters | Centered with max-width | Full-width with padding |++## Artifact Panel++The Shell supports a resizable artifact panel on desktop:++```tsx+<ThreadContainer+ isArtifactActive={true}+ renderArtifact={() => <div>{/* Your artifact content (code preview, document, etc.) */}</div>}+>+ {/* Chat content */}+</ThreadContainer>+```++On desktop, the artifact panel appears to the right of the chat and can be resized by dragging the separator. On mobile, it appears as a full-screen overlay.++## Comparison with Other Components++| Feature | Shell | CopilotShell | BottomTray |+| -------------- | ----------------- | ------------------ | ---------------------- |+| Layout | Full page | Sidebar panel | Floating panel |+| Sidebar | Yes (collapsible) | No | No |+| Thread list | Yes | No | Yes (in header) |+| Artifact panel | Yes (resizable) | Yes (overlay) | No |+| Mobile | Responsive | Responsive | Fullscreen |+| Use case | Primary chat app | Side panel copilot | Secondary/support chat |++## CSS Classes++All Shell components use the `crayon-shell-` prefix:++- `.crayon-shell-container`+- `.crayon-shell-thread-container`+- `.crayon-shell-thread-scroll-area`+- `.crayon-shell-thread-messages`+- `.crayon-shell-thread-message-user`+- `.crayon-shell-thread-message-assistant`+- `.crayon-shell-thread-composer`+- `.crayon-shell-conversation-starter`+- `.crayon-shell-conversation-starter-item`+- `.crayon-shell-sidebar-container`+- `.crayon-shell-sidebar-header`+- `.crayon-shell-sidebar-content`diff --git a/js/packages/react-ui/src/components/Shell/stories/Shell.stories.tsx b/js/packages/react-ui/src/components/Shell/stories/Shell.stories.tsxindex eb51f4a67..16db125e3 100644--- a/js/packages/react-ui/src/components/Shell/stories/Shell.stories.tsx+++ b/js/packages/react-ui/src/components/Shell/stories/Shell.stories.tsx@@ -4,21 +4,75 @@ import {useThreadListManager,useThreadManager,} from "@crayonai/react-core";+import { MessageSquare, Sparkles, Zap } from "lucide-react";import { Container } from "../Container";+import { ConversationStarter } from "../ConversationStarter";import { MobileHeader } from "../MobileHeader";import { NewChatButton } from "../NewChatButton";import { SidebarContainer, SidebarContent, SidebarHeader, SidebarSeparator } from "../Sidebar";import { Composer, MessageLoading, Messages, ScrollArea, ThreadContainer } from "../Thread";import { ThreadList } from "../ThreadList";+import { WelcomeScreen } from "../WelcomeScreen";import logoUrl from "./thesysdev_logo.jpeg";export default {- title: "Shell",- tags: ["!dev", "!autodocs"],+ title: "Components/Shell",+ tags: ["dev"],+ argTypes: {+ variant: {+ control: "select",+ options: ["short", "long"],+ description: "Conversation starter variant",+ },+ },};+const SAMPLE_STARTERS = [+ {+ displayText: "Help me get started",+ prompt: "Help me get started",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "What can you do?",+ prompt: "What can you do?",+ // icon undefined = shows default lightbulb+ },+ {+ displayText: "Tell me about your features",+ prompt: "Tell me about your features",+ icon: <MessageSquare size={16} />,+ },+ {+ displayText: "Show me some examples (no icon)",+ prompt: "Show me some examples",+ icon: <></>, // Empty fragment = no icon+ },+];++const LONG_STARTERS = [+ {+ displayText: "Help me get started with this application and guide me through the features",+ prompt: "Help me get started with this application",+ icon: <Sparkles size={16} />,+ },+ {+ displayText: "What can you do? I'd like to know all your capabilities and how you can help me",+ prompt: "What can you do?",+ icon: <Zap size={16} />,+ },+ {+ displayText: "Tell me about your advanced features and how I can use them effectively",+ prompt: "Tell me about your features",+ // Default lightbulb icon+ },+];+export const Default = {- render: (args: any) => {+ args: {+ variant: "short",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {const threadListManager = useThreadListManager({createThread: async () => {return {@@ -59,7 +113,8 @@ export const Default = {const threadManager = useThreadManager({threadId: threadListManager.selectedThreadId,- loadThread: async () => {+ loadThread: async (threadId) => {+ if (!threadId) return [];return [{id: crypto.randomUUID(),@@ -71,14 +126,75 @@ export const Default = {id: crypto.randomUUID(),role: "assistant",type: "response",- message: [{ type: "text", text: "Hello" }],+ message: [{ type: "text", text: "Hello! How can I help you today?" }],+ },+ ];+ },+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = { ...message, id: crypto.randomUUID() } as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: "This is a response from the AI assistant." }],},];},- onProcessMessage: async ({ message, threadManager, abortController }) => {- const newMessage = Object.assign({}, message, {- id: crypto.randomUUID(),- }) as Message;+ responseTemplates: [],+ });++ return (+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl={logoUrl} agentName="Crayon">+ <SidebarContainer>+ <SidebarHeader />+ <SidebarContent>+ <NewChatButton />+ <SidebarSeparator />+ <ThreadList />+ </SidebarContent>+ </SidebarContainer>+ <ThreadContainer>+ <MobileHeader />+ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ );+ },+};++export const WithConversationStarter = {+ args: {+ variant: "short",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [], // Start with empty thread to show starters+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = { ...message, id: crypto.randomUUID() } as Message;threadManager.appendMessages(newMessage);await new Promise((resolve) => setTimeout(resolve, 1000));return [@@ -86,7 +202,7 @@ export const Default = {id: crypto.randomUUID(),role: "assistant",type: "response",- message: [{ type: "text", text: "sadfasdf" }],+ message: [{ type: "text", text: `You asked: "${message.message}"` }],},];},@@ -109,6 +225,241 @@ export const Default = {<ScrollArea><Messages loader={<MessageLoading />} /></ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ );+ },+};++export const LongVariant = {+ args: {+ variant: "long",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [], // Start with empty thread to show starters+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = { ...message, id: crypto.randomUUID() } as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ return (+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl={logoUrl} agentName="Crayon">+ <SidebarContainer>+ <SidebarHeader />+ <SidebarContent>+ <NewChatButton />+ <SidebarSeparator />+ <ThreadList />+ </SidebarContent>+ </SidebarContainer>+ <ThreadContainer>+ <MobileHeader />+ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={LONG_STARTERS} variant={variant} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ );+ },+};++// WelcomeScreen with props-based content+export const WithWelcomeScreen = {+ args: {+ variant: "short",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [], // Start with empty thread to show welcome screen+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = { ...message, id: crypto.randomUUID() } as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ const hasMessages = threadManager.messages.length > 0;++ return (+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl={logoUrl} agentName="Crayon Assistant">+ <SidebarContainer>+ <SidebarHeader />+ <SidebarContent>+ <NewChatButton />+ <SidebarSeparator />+ <ThreadList />+ </SidebarContent>+ </SidebarContainer>+ <ThreadContainer>+ <MobileHeader />++ {!hasMessages && (+ <WelcomeScreen+ title="Hi, I'm Crayon Assistant"+ description="I can help you with questions about your account, products, and more."+ image={{ url: logoUrl }}+ starters={SAMPLE_STARTERS}+ starterVariant={variant}+ />+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} />+ <Composer />+ </ThreadContainer>+ </Container>+ </ChatProvider>+ );+ },+};++// WelcomeScreen with custom children+export const WithCustomWelcomeScreen = {+ args: {+ variant: "short",+ },+ render: ({ variant }: { variant: "short" | "long" }) => {+ const threadListManager = useThreadListManager({+ createThread: async () => ({+ threadId: crypto.randomUUID(),+ title: "New Chat",+ createdAt: new Date(),+ isRunning: false,+ }),+ fetchThreadList: async () => [],+ deleteThread: async () => {},+ updateThread: async (t) => t,+ onSwitchToNew: () => {},+ onSelectThread: () => {},+ });++ const threadManager = useThreadManager({+ threadId: threadListManager.selectedThreadId,+ loadThread: async () => [],+ onProcessMessage: async ({ message, threadManager }) => {+ const newMessage = { ...message, id: crypto.randomUUID() } as Message;+ threadManager.appendMessages(newMessage);+ await new Promise((resolve) => setTimeout(resolve, 1000));+ return [+ {+ id: crypto.randomUUID(),+ role: "assistant",+ type: "response",+ message: [{ type: "text", text: `You asked: "${message.message}"` }],+ },+ ];+ },+ responseTemplates: [],+ });++ const hasMessages = threadManager.messages.length > 0;++ return (+ <ChatProvider threadListManager={threadListManager} threadManager={threadManager}>+ <Container logoUrl={logoUrl} agentName="Crayon Assistant">+ <SidebarContainer>+ <SidebarHeader />+ <SidebarContent>+ <NewChatButton />+ <SidebarSeparator />+ <ThreadList />+ </SidebarContent>+ </SidebarContainer>+ <ThreadContainer>+ <MobileHeader />++ {!hasMessages && (+ <WelcomeScreen>+ <div style={{ textAlign: "center" }}>+ <div+ style={{+ width: 80,+ height: 80,+ borderRadius: 16,+ background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",+ display: "flex",+ alignItems: "center",+ justifyContent: "center",+ margin: "0 auto 16px",+ }}+ >+ <Sparkles size={40} color="white" />+ </div>+ <h2 style={{ margin: "0 0 8px", fontSize: 24, fontWeight: 600 }}>+ Welcome to AI Assistant+ </h2>+ <p style={{ margin: 0, color: "rgba(0,0,0,0.5)", fontSize: 16 }}>+ Your personal AI helper for all your questions+ </p>+ </div>+ </WelcomeScreen>+ )}++ <ScrollArea>+ <Messages loader={<MessageLoading />} />+ </ScrollArea>+ <ConversationStarter starters={SAMPLE_STARTERS} variant={variant} /><Composer /></ThreadContainer></Container>diff --git a/js/packages/react-ui/src/components/Shell/thread.scss b/js/packages/react-ui/src/components/Shell/thread.scssindex 9a991d3b4..f6a1a655a 100644--- a/js/packages/react-ui/src/components/Shell/thread.scss+++ b/js/packages/react-ui/src/components/Shell/thread.scss@@ -99,9 +99,14 @@ $center-align-spacing: calc(32px + cssUtils.$spacing-s);.crayon-shell-thread-scroll-container {display: flex;width: 100%;- flex: 1;+ flex-grow: 1;position: relative;overflow: hidden;++ // When WelcomeScreen is present, don't grow so WelcomeScreen can take the space+ .crayon-shell-thread-container:has(.crayon-shell-welcome-screen) & {+ flex-grow: 0;+ }}.crayon-shell-thread-scroll-area {@@ -110,6 +115,11 @@ $center-align-spacing: calc(32px + cssUtils.$spacing-s);overflow: auto;padding: cssUtils.$spacing-m $center-align-spacing cssUtils.$spacing-xl;+ // When WelcomeScreen is present, lets remove the padding temporarily+ .crayon-shell-thread-container:has(.crayon-shell-welcome-screen) & {+ padding: 0;+ }+.crayon-shell-container--mobile & {padding: cssUtils.$spacing-l;}@@ -219,54 +229,6 @@ $center-align-spacing: calc(32px + cssUtils.$spacing-s);}}-// =============================================================================-// Composer-// =============================================================================--.crayon-shell-thread-composer {- max-width: 880px;- width: 100%;- margin: 0 auto cssUtils.$spacing-m;- padding: 0 $center-align-spacing;-- .crayon-shell-container--mobile & {- margin: 0;- padding: cssUtils.$spacing-m 14px;- background-color: cssUtils.$bg-container;- }-- .crayon-shell-thread-container--artifact-active & {- padding-left: 0;- padding-right: cssUtils.$spacing-m;- }-- &__input-wrapper {- border: 1.256px solid cssUtils.$stroke-default;- border-radius: cssUtils.$rounded-xl;- display: flex;- align-items: flex-end;- gap: cssUtils.$spacing-s;- padding: cssUtils.$spacing-m;- }-- &__input {- flex-grow: 1;- padding: 0;- resize: none;- margin: auto 0px;- max-height: 154px;- outline: none;- border: none;- background: transparent;- overflow: hidden;- @include cssUtils.typography(primary, default);- color: cssUtils.$primary-text;- &::placeholder {- color: cssUtils.$disabled-text;- }- }-}-.crayon-shell-thread-message-loading {display: flex;padding: 0 $center-align-spacing;diff --git a/js/packages/react-ui/src/components/Shell/welcomeScreen.scss b/js/packages/react-ui/src/components/Shell/welcomeScreen.scssnew file mode 100644index 000000000..4339eaca5--- /dev/null+++ b/js/packages/react-ui/src/components/Shell/welcomeScreen.scss@@ -0,0 +1,158 @@+@use "../../cssUtils" as cssUtils;++$center-align-spacing: calc(32px + cssUtils.$spacing-s);++.crayon-shell-welcome-screen {+ display: flex;+ flex-direction: column;+ gap: cssUtils.$spacing-l;+ flex: 1;+ justify-content: center;+ align-items: center;+ width: 100%;+ height: 100%;+ max-width: 880px;+ margin: 0 auto;+ padding: cssUtils.$spacing-2xl $center-align-spacing;++ // Mobile adjustments+ .crayon-shell-container--mobile & {+ padding: cssUtils.$spacing-2xl cssUtils.$spacing-l;+ }++ // Artifact active adjustments+ .crayon-shell-thread-container--artifact-active & {+ padding-left: 0;+ padding-right: cssUtils.$spacing-m;+ }++ // Header section (icon + title/description)+ &__header {+ display: flex;+ flex-direction: column;+ align-items: center;+ gap: cssUtils.$spacing-l;+ }++ // Image container - minimal wrapper, styling handled by consumer+ &__image-container {+ display: flex;+ align-items: center;+ justify-content: center;+ flex-shrink: 0;+ }++ // Default image styles when using { url: string }+ &__image {+ width: 64px;+ height: 64px;+ object-fit: cover;+ border-radius: cssUtils.$rounded-xl;+ }++ // Content container (title + description)+ &__content {+ display: flex;+ flex-direction: column;+ align-items: center;+ gap: cssUtils.$spacing-xs;+ text-align: center;+ }++ // Title/greeting text+ &__title {+ @include cssUtils.typography(heading, small);+ color: cssUtils.$primary-text;+ margin: 0;+ }++ // Description text+ &__description {+ @include cssUtils.typography(body, small);+ color: cssUtils.$secondary-text;+ margin: 0;+ max-width: 400px;+ }++ &__composer-starters-container {+ display: flex;+ flex-direction: column;+ gap: cssUtils.$spacing-l;+ width: 100%;+ }++ // Desktop welcome composer container+ &__desktop-composer {+ display: flex;+ justify-content: center;+ width: 100%;++ // Hide on mobile - keep the regular Composer on mobile+ .crayon-shell-container--mobile & {+ display: none;+ }+ }++ // Desktop conversation starters container+ &__desktop-starters {+ width: 100%;++ // Hide on mobile - keep the external ConversationStarter on mobile+ .crayon-shell-container--mobile & {+ display: none;+ }++ // Reset padding since welcome screen already has padding+ .crayon-shell-conversation-starter {+ padding: 0;+ }++ // Center align short variant buttons+ .crayon-shell-conversation-starter--short {+ justify-content: center;+ }+ }++ // When welcome screen has the desktop composer variant+ &--with-composer {+ // Adjust gap for desktop layout+ gap: cssUtils.$spacing-2xl;++ // On mobile, use normal gap+ .crayon-shell-container--mobile & {+ gap: cssUtils.$spacing-l;+ }+ }+}++// Hide the regular Composer when welcome screen with desktop composer is present (desktop only)+// This uses CSS :has() to detect the welcome screen and hide the default composer+.crayon-shell-thread-container:has(.crayon-shell-welcome-screen--with-composer) {+ .crayon-shell-thread-composer {+ display: none;+ }++ // But show it on mobile+ .crayon-shell-container--mobile & .crayon-shell-thread-composer {+ display: block;+ }+}++// Alternative approach using parent mobile class for better specificity+.crayon-shell-container:not(.crayon-shell-container--mobile) {+ .crayon-shell-thread-container:has(.crayon-shell-welcome-screen--with-composer) {+ .crayon-shell-thread-composer {+ display: none;+ }+ }++ // Hide the external ConversationStarter when desktop starters exist+ // Use :not() to exclude the one inside the welcome screen+ .crayon-shell-thread-container:has(.crayon-shell-welcome-screen__desktop-starters) {+ .crayon-shell-conversation-starter:not(+ .crayon-shell-welcome-screen__desktop-starters .crayon-shell-conversation-starter+ ) {+ display: none;+ }+ }+}diff --git a/js/packages/react-ui/src/components/index.scss b/js/packages/react-ui/src/components/index.scssindex deba20ad1..d72c76beb 100644--- a/js/packages/react-ui/src/components/index.scss+++ b/js/packages/react-ui/src/components/index.scss@@ -44,3 +44,4 @@@forward "./TextCallout/textCallout.scss";@forward "./Charts/charts.scss";@forward "./Separator/separator.scss";+@forward "./CrayonChat/crayonChat.scss";diff --git a/js/packages/react-ui/src/index.ts b/js/packages/react-ui/src/index.tsindex 62411aeda..c854d5a2a 100644--- a/js/packages/react-ui/src/index.ts+++ b/js/packages/react-ui/src/index.ts@@ -52,3 +52,10 @@ export {export * from "./context/LayoutContext";export * from "./context/PrintContext";++// Types Export+export type { ConversationStarterVariant } from "./components/BottomTray/ConversationStarter";+export type {+ ConversationStarterIcon,+ ConversationStarterProps,+} from "./types/ConversationStarter";diff --git a/js/packages/react-ui/src/types/ConversationStarter.ts b/js/packages/react-ui/src/types/ConversationStarter.tsnew file mode 100644index 000000000..c1a58e5d8--- /dev/null+++ b/js/packages/react-ui/src/types/ConversationStarter.ts@@ -0,0 +1,22 @@+import { ReactNode } from "react";++/**+ * Icon type for conversation starters+ * - undefined: Show default lightbulb icon+ * - ReactNode: Show the provided icon (use <></> or React.Fragment for no icon)+ */+export type ConversationStarterIcon = ReactNode;++interface ConversationStarterProps {+ displayText: string;+ prompt: string;+ /**+ * Optional icon to display+ * - If not provided (undefined): shows default lightbulb icon+ * - If provided: shows the provided React element+ * - For no icon: pass an empty fragment (<></> or React.Fragment)+ */+ icon?: ConversationStarterIcon;+}++export type { ConversationStarterProps };