composeai 0.1.7 → 0.1.8

package/dist/index.d.cts

@@ -531,6 +531,20 @@ interface GhostedAutoCompleteConfig {
      */
     minLength?: number;
 }
+/**
+ * Object form of {@link ComposerProps.animatedPlaceholder}. Use it when you
+ * need to opt into looping; the bare `string[]` form is equivalent to
+ * `{ phrases, loop: false }`.
+ */
+interface AnimatedPlaceholderConfig {
+    /** Phrases the empty editor types out, in order. */
+    phrases: string[];
+    /**
+     * Cycle the list forever. Defaults to `false` — the list plays through once
+     * and then settles (see {@link ComposerProps.animatedPlaceholder}).
+     */
+    loop?: boolean;
+}
 /**
  * Editor helpers handed to a {@link CustomAction} when it's clicked, so a
  * custom toolbar button can mutate the composer the same way a slash command
@@ -748,6 +762,46 @@ interface ComposerProps {
      */
     focusShortcut?: string | false | null;
     placeholder?: string;
+    /**
+     * Animated placeholder: a list of phrases the empty editor cycles through
+     * with a typewriter effect — each phrase is revealed one character at a
+     * time, held, erased, and the next begins. The animation takes precedence
+     * over the static {@link placeholder} while the editor is empty and pauses
+     * the moment the user starts typing.
+     *
+     * Pass a `string[]` for the default behaviour, or an
+     * {@link AnimatedPlaceholderConfig} to enable looping.
+     *
+     * **Looping** (`loop`, default `false`):
+     * - `loop: false` — play through the list once, then settle: on the
+     *   {@link placeholder} prop if one was given, otherwise on the last phrase
+     *   (left on screen).
+     * - `loop: true` — cycle the list forever.
+     *
+     * Honours `prefers-reduced-motion` by showing the first phrase statically.
+     *
+     * @example
+     * // Play once, then rest on the last phrase (no `placeholder` given):
+     * <Composer
+     *   animatedPlaceholder={[
+     *     "Ask me anything…",
+     *     "Summarize this thread",
+     *     "Draft a reply to Alex",
+     *   ]}
+     *   onSend={...}
+     * />
+     *
+     * @example
+     * // Loop forever:
+     * <Composer
+     *   animatedPlaceholder={{
+     *     phrases: ["Ask me anything…", "Summarize this thread"],
+     *     loop: true,
+     *   }}
+     *   onSend={...}
+     * />
+     */
+    animatedPlaceholder?: string[] | AnimatedPlaceholderConfig;
     /**
      * Shorthand for `classNames.root`. Kept for back-compat; if both are set,
      * the two are merged (`className` first, then `classNames.root`).
@@ -1016,4 +1070,4 @@ interface SuggestionRowProps {
 }
 declare function SuggestionRow({ items, onSelect, className }: SuggestionRowProps): react.JSX.Element;
 
-export { type Attachment, type AttachmentKind, type AttachmentOptions, type AttachmentStatus, type AttachmentTypeOption, type AttachmentsConfig, Composer, type ComposerFeatures, type ComposerHandle, type ComposerIcons, type ComposerPromptBehavior, type ComposerPromptsConfig, type ComposerProps, type ComposerSlot, type ComposerSlotClassNames, type ComposerSlots, type ComposerSubmitPayload, type ComposerSxMap, type ComposerSxValue, type ComposerTokens, type CustomAction, type CustomActionContext, type DiagramRenderer, type GhostedAutoCompleteConfig, type IconComponent, type IconProps, type MarkdownConfig, type MarkdownMode, type MentionConfig, type MentionItem, type MentionRef, type MermaidConfig, type SendButtonRenderProps, type SlashCommand, type SlashCommandContext, type SlashConfig, type StopButtonRenderProps, SuggestionRow, type SuggestionRowProps };
+export { type AnimatedPlaceholderConfig, type Attachment, type AttachmentKind, type AttachmentOptions, type AttachmentStatus, type AttachmentTypeOption, type AttachmentsConfig, Composer, type ComposerFeatures, type ComposerHandle, type ComposerIcons, type ComposerPromptBehavior, type ComposerPromptsConfig, type ComposerProps, type ComposerSlot, type ComposerSlotClassNames, type ComposerSlots, type ComposerSubmitPayload, type ComposerSxMap, type ComposerSxValue, type ComposerTokens, type CustomAction, type CustomActionContext, type DiagramRenderer, type GhostedAutoCompleteConfig, type IconComponent, type IconProps, type MarkdownConfig, type MarkdownMode, type MentionConfig, type MentionItem, type MentionRef, type MermaidConfig, type SendButtonRenderProps, type SlashCommand, type SlashCommandContext, type SlashConfig, type StopButtonRenderProps, SuggestionRow, type SuggestionRowProps };

package/dist/index.d.ts

@@ -531,6 +531,20 @@ interface GhostedAutoCompleteConfig {
      */
     minLength?: number;
 }
+/**
+ * Object form of {@link ComposerProps.animatedPlaceholder}. Use it when you
+ * need to opt into looping; the bare `string[]` form is equivalent to
+ * `{ phrases, loop: false }`.
+ */
+interface AnimatedPlaceholderConfig {
+    /** Phrases the empty editor types out, in order. */
+    phrases: string[];
+    /**
+     * Cycle the list forever. Defaults to `false` — the list plays through once
+     * and then settles (see {@link ComposerProps.animatedPlaceholder}).
+     */
+    loop?: boolean;
+}
 /**
  * Editor helpers handed to a {@link CustomAction} when it's clicked, so a
  * custom toolbar button can mutate the composer the same way a slash command
@@ -748,6 +762,46 @@ interface ComposerProps {
      */
     focusShortcut?: string | false | null;
     placeholder?: string;
+    /**
+     * Animated placeholder: a list of phrases the empty editor cycles through
+     * with a typewriter effect — each phrase is revealed one character at a
+     * time, held, erased, and the next begins. The animation takes precedence
+     * over the static {@link placeholder} while the editor is empty and pauses
+     * the moment the user starts typing.
+     *
+     * Pass a `string[]` for the default behaviour, or an
+     * {@link AnimatedPlaceholderConfig} to enable looping.
+     *
+     * **Looping** (`loop`, default `false`):
+     * - `loop: false` — play through the list once, then settle: on the
+     *   {@link placeholder} prop if one was given, otherwise on the last phrase
+     *   (left on screen).
+     * - `loop: true` — cycle the list forever.
+     *
+     * Honours `prefers-reduced-motion` by showing the first phrase statically.
+     *
+     * @example
+     * // Play once, then rest on the last phrase (no `placeholder` given):
+     * <Composer
+     *   animatedPlaceholder={[
+     *     "Ask me anything…",
+     *     "Summarize this thread",
+     *     "Draft a reply to Alex",
+     *   ]}
+     *   onSend={...}
+     * />
+     *
+     * @example
+     * // Loop forever:
+     * <Composer
+     *   animatedPlaceholder={{
+     *     phrases: ["Ask me anything…", "Summarize this thread"],
+     *     loop: true,
+     *   }}
+     *   onSend={...}
+     * />
+     */
+    animatedPlaceholder?: string[] | AnimatedPlaceholderConfig;
     /**
      * Shorthand for `classNames.root`. Kept for back-compat; if both are set,
      * the two are merged (`className` first, then `classNames.root`).
@@ -1016,4 +1070,4 @@ interface SuggestionRowProps {
 }
 declare function SuggestionRow({ items, onSelect, className }: SuggestionRowProps): react.JSX.Element;
 
-export { type Attachment, type AttachmentKind, type AttachmentOptions, type AttachmentStatus, type AttachmentTypeOption, type AttachmentsConfig, Composer, type ComposerFeatures, type ComposerHandle, type ComposerIcons, type ComposerPromptBehavior, type ComposerPromptsConfig, type ComposerProps, type ComposerSlot, type ComposerSlotClassNames, type ComposerSlots, type ComposerSubmitPayload, type ComposerSxMap, type ComposerSxValue, type ComposerTokens, type CustomAction, type CustomActionContext, type DiagramRenderer, type GhostedAutoCompleteConfig, type IconComponent, type IconProps, type MarkdownConfig, type MarkdownMode, type MentionConfig, type MentionItem, type MentionRef, type MermaidConfig, type SendButtonRenderProps, type SlashCommand, type SlashCommandContext, type SlashConfig, type StopButtonRenderProps, SuggestionRow, type SuggestionRowProps };
+export { type AnimatedPlaceholderConfig, type Attachment, type AttachmentKind, type AttachmentOptions, type AttachmentStatus, type AttachmentTypeOption, type AttachmentsConfig, Composer, type ComposerFeatures, type ComposerHandle, type ComposerIcons, type ComposerPromptBehavior, type ComposerPromptsConfig, type ComposerProps, type ComposerSlot, type ComposerSlotClassNames, type ComposerSlots, type ComposerSubmitPayload, type ComposerSxMap, type ComposerSxValue, type ComposerTokens, type CustomAction, type CustomActionContext, type DiagramRenderer, type GhostedAutoCompleteConfig, type IconComponent, type IconProps, type MarkdownConfig, type MarkdownMode, type MentionConfig, type MentionItem, type MentionRef, type MermaidConfig, type SendButtonRenderProps, type SlashCommand, type SlashCommandContext, type SlashConfig, type StopButtonRenderProps, SuggestionRow, type SuggestionRowProps };

package/dist/index.js

@@ -800,6 +800,7 @@ function useComposerContext() {
 }
 function EditorShell({
   placeholder,
+  animated,
   mode,
   variant,
   multiline,
@@ -818,7 +819,11 @@ function EditorShell({
   const editor = slotProps("editor", editorClass, classNames, sx);
   const editorResolved = resolveSx(sx?.editor);
   const placeholderBase = mirrorEditorPadding(editorResolved);
-  const placeholderClass = isCompact ? "composer-placeholder composer-placeholder--compact" : multiline ? "composer-placeholder composer-placeholder--multiline" : "composer-placeholder composer-placeholder--inline";
+  const placeholderClass = cn(
+    isCompact ? "composer-placeholder composer-placeholder--compact" : multiline ? "composer-placeholder composer-placeholder--multiline" : "composer-placeholder composer-placeholder--inline",
+    // Adds the blinking caret after the typewriter text.
+    animated && "composer-placeholder--animated"
+  );
   const placeholderProps = slotProps(
     "placeholder",
     placeholderClass,
@@ -4927,6 +4932,107 @@ function useComposerHandle(ref, onSubmit) {
     };
   }, [editor, ref, onSubmit, addFiles]);
 }
+var DEFAULT_TIMING = {
+  typeSpeed: 55,
+  deleteSpeed: 28,
+  holdDuration: 1800,
+  pauseDuration: 450
+};
+function useAnimatedPlaceholder(phrases, enabled, options) {
+  const [state, setState] = useState({
+    text: "",
+    active: true
+  });
+  const optsRef = useRef({});
+  optsRef.current = options ?? {};
+  const active = enabled && Array.isArray(phrases) && phrases.length > 0;
+  const key = active ? phrases.join("\u241F") : "";
+  const loop = !!options?.loop;
+  const phrasesRef = useRef(phrases);
+  phrasesRef.current = phrases;
+  useEffect(() => {
+    if (!active) {
+      setState({ text: "", active: true });
+      return;
+    }
+    const list = phrasesRef.current;
+    const lastIdx = list.length - 1;
+    const reduceMotion = typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    if (reduceMotion) {
+      setState({ text: list[0], active: false });
+      return;
+    }
+    let timer;
+    let phraseIdx = 0;
+    let charIdx = 0;
+    let phase = "typing";
+    const tick = () => {
+      const timing = { ...DEFAULT_TIMING, ...optsRef.current };
+      const { typeSpeed, deleteSpeed, holdDuration, pauseDuration } = timing;
+      const settleTo = optsRef.current.settleTo;
+      const current = list[phraseIdx];
+      const isLast = phraseIdx === lastIdx;
+      switch (phase) {
+        case "typing": {
+          charIdx += 1;
+          setState({ text: current.slice(0, charIdx), active: true });
+          if (charIdx >= current.length) {
+            phase = "holding";
+            timer = setTimeout(tick, holdDuration);
+          } else {
+            timer = setTimeout(tick, typeSpeed);
+          }
+          break;
+        }
+        case "holding": {
+          if (!loop && isLast) {
+            if (settleTo !== void 0) {
+              phase = "settling";
+              timer = setTimeout(tick, deleteSpeed);
+            } else {
+              setState({ text: current, active: false });
+            }
+          } else {
+            phase = "deleting";
+            timer = setTimeout(tick, deleteSpeed);
+          }
+          break;
+        }
+        case "deleting": {
+          charIdx -= 1;
+          setState({ text: current.slice(0, Math.max(0, charIdx)), active: true });
+          if (charIdx <= 0) {
+            phase = "pausing";
+            timer = setTimeout(tick, pauseDuration);
+          } else {
+            timer = setTimeout(tick, deleteSpeed);
+          }
+          break;
+        }
+        case "pausing": {
+          phraseIdx = phraseIdx >= lastIdx ? 0 : phraseIdx + 1;
+          charIdx = 0;
+          phase = "typing";
+          timer = setTimeout(tick, typeSpeed);
+          break;
+        }
+        case "settling": {
+          charIdx -= 1;
+          if (charIdx <= 0) {
+            setState({ text: settleTo ?? "", active: false });
+          } else {
+            setState({ text: current.slice(0, charIdx), active: true });
+            timer = setTimeout(tick, deleteSpeed);
+          }
+          break;
+        }
+      }
+    };
+    timer = setTimeout(tick, DEFAULT_TIMING.typeSpeed);
+    return () => clearTimeout(timer);
+  }, [active, key, loop]);
+  return active ? state : null;
+}
 
 // src/internal/shortcut.ts
 var MODIFIERS = /* @__PURE__ */ new Set([
@@ -5004,6 +5110,7 @@ function matchesShortcut(parsed, event) {
 var Composer = forwardRef(function Composer2(props, ref) {
   const {
     placeholder = "Send a message\u2026",
+    animatedPlaceholder,
     onSend,
     onStop,
     isStreaming,
@@ -5033,6 +5140,7 @@ var Composer = forwardRef(function Composer2(props, ref) {
     attachmentOptions,
     dir
   } = props;
+  const hasPlaceholder = props.placeholder != null;
   const tokenStyle = useMemo(() => {
     const derived = color ? deriveColorTokens(color) : null;
     if (!derived && !tokens) return void 0;
@@ -5076,6 +5184,8 @@ var Composer = forwardRef(function Composer2(props, ref) {
               ComposerCard,
               {
                 placeholder,
+                animatedPlaceholder,
+                hasPlaceholder,
                 initialValue,
                 handleRef: ref,
                 onSend,
@@ -5113,6 +5223,8 @@ var RICH_NODES = [
 var PLAIN_NODES = [MentionNode];
 function ComposerCard({
   placeholder,
+  animatedPlaceholder,
+  hasPlaceholder,
   initialValue,
   handleRef,
   onSend,
@@ -5174,6 +5286,8 @@ function ComposerCard({
           ComposerInner,
           {
             placeholder,
+            animatedPlaceholder,
+            hasPlaceholder,
             mode,
             variant,
             multiline,
@@ -5194,6 +5308,8 @@ function ComposerCard({
 }
 function ComposerInner({
   placeholder,
+  animatedPlaceholder,
+  hasPlaceholder,
   mode,
   variant,
   multiline,
@@ -5324,6 +5440,13 @@ function ComposerInner({
     });
   }, [editor, registerRunPrompt, submit]);
   const isCompact = variant === "compact";
+  const animatedPhrases = Array.isArray(animatedPlaceholder) ? animatedPlaceholder : animatedPlaceholder?.phrases;
+  const animatedLoop = Array.isArray(animatedPlaceholder) ? false : !!animatedPlaceholder?.loop;
+  const animatedFrame = useAnimatedPlaceholder(animatedPhrases, !hasText, {
+    loop: animatedLoop,
+    settleTo: hasPlaceholder ? placeholder : void 0
+  });
+  const effectivePlaceholder = animatedFrame?.text ?? placeholder;
   const mermaidActive = multiline && mode === "markdown" && !!features.mermaid;
   const toolbarSlot = /* @__PURE__ */ jsx(Toolbar, { extras: toolbarExtras, variant, submit });
   const sendButton = /* @__PURE__ */ jsx(
@@ -5347,7 +5470,8 @@ function ComposerInner({
     /* @__PURE__ */ jsx(
       EditorShell,
       {
-        placeholder,
+        placeholder: effectivePlaceholder,
+        animated: animatedFrame?.active ?? false,
         mode,
         variant,
         multiline,