@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/Chat/composer/ComposerButton.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ComposerAction, ComposerSize } from './types';
+
+/** Per-size geometry for action-bar buttons + their icons.
+ *  ChatGPT/Gemini-style — fully round, slightly larger glyphs. */
+export const BUTTON_SIZE: Record<ComposerSize, { button: string; icon: string }> = {
+  sm: { button: 'h-7 w-7 rounded-full', icon: '[&_svg]:size-4' },
+  md: { button: 'h-9 w-9 rounded-full', icon: '[&_svg]:size-[1.125rem]' },
+  lg: { button: 'h-11 w-11 rounded-full', icon: '[&_svg]:size-5' },
+};
+
+const VARIANT_CLASSES: Record<NonNullable<ComposerAction['variant']>, string> = {
+  ghost: 'text-muted-foreground hover:bg-accent hover:text-accent-foreground',
+  secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+  primary: 'bg-primary text-primary-foreground hover:bg-primary/90',
+  // The send button is the composer's primary CTA — brand `primary`
+  // token, cohesive with accent surfaces (e.g. the user bubble).
+  // Disabled stays a dimmed `primary` (not neutral grey) so the button
+  // is still recognisable as send against the composer surface.
+  send: 'bg-primary text-primary-foreground hover:bg-primary/90 disabled:bg-primary/30 disabled:text-primary-foreground/60',
+};
+
+export interface ComposerButtonProps {
+  action: ComposerAction;
+  size: ComposerSize;
+}
+
+/**
+ * Renders a single declarative `ComposerAction` as an icon button.
+ * Centralises size, variant, aria-label, and `aria-pressed` so hosts
+ * cannot misalign or under-label an action.
+ */
+export function ComposerButton({ action, size }: ComposerButtonProps) {
+  const variant = action.variant ?? 'ghost';
+  const sz = BUTTON_SIZE[size];
+  const isToggle = action.pressed !== undefined;
+  return (
+    <button
+      type="button"
+      onClick={action.onClick}
+      disabled={action.disabled}
+      aria-label={action.label}
+      title={action.label}
+      aria-pressed={isToggle ? action.pressed : undefined}
+      className={cn(
+        'inline-flex shrink-0 cursor-pointer items-center justify-center',
+        'transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        'disabled:pointer-events-none [&_svg]:shrink-0',
+        // The send variant carries its own muted disabled fill, so it
+        // skips the generic opacity dim that the other variants use.
+        variant === 'send' ? 'disabled:cursor-default' : 'disabled:opacity-50',
+        sz.button,
+        sz.icon,
+        VARIANT_CLASSES[variant],
+        isToggle && action.pressed && variant === 'ghost' && 'bg-accent text-accent-foreground',
+      )}
+    >
+      {action.icon}
+    </button>
+  );
+}

package/src/tools/Chat/composer/ComposerFooter.tsx

@@ -0,0 +1,90 @@
+'use client';
+
+import { isValidElement } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ComposerFooterProps } from './types';
+
+/** Counter starts announcing once the draft passes this fraction of the cap. */
+const COUNTER_THRESHOLD = 0.8;
+
+const TEXT_SIZE = {
+  sm: 'text-[11px]',
+  md: 'text-xs',
+  lg: 'text-xs',
+} as const;
+
+function shortcutHint(submitOn: 'enter' | 'cmd+enter'): string {
+  return submitOn === 'cmd+enter'
+    ? '⌘⏎ to send'
+    : '⏎ to send · ⇧⏎ for newline';
+}
+
+/**
+ * The quiet strip below the input surface. Three zones: start (auto
+ * shortcut hint), center (host extras), end (auto char counter). Renders
+ * as a plain `div` unless it carries interactive controls.
+ */
+export function ComposerFooter({
+  start,
+  center,
+  end,
+  showCounter = true,
+  // Off by default — ChatGPT / Gemini don't surface a keyboard hint.
+  // Hosts can opt back in with `showHint`.
+  showHint = false,
+  value = '',
+  maxLength,
+  submitOn = 'enter',
+  size = 'md',
+  className,
+}: ComposerFooterProps) {
+  const nearLimit =
+    maxLength !== undefined && value.length >= maxLength * COUNTER_THRESHOLD;
+  const counterNode =
+    showCounter && maxLength !== undefined && nearLimit ? (
+      <span
+        aria-live="polite"
+        className={cn(
+          'tabular-nums',
+          value.length >= maxLength ? 'text-destructive' : 'text-muted-foreground',
+        )}
+      >
+        {value.length} / {maxLength}
+      </span>
+    ) : null;
+
+  const hintNode =
+    showHint && !start ? (
+      <span aria-hidden className="text-muted-foreground/70">
+        {shortcutHint(submitOn)}
+      </span>
+    ) : null;
+
+  const startNode = start ?? hintNode;
+  const endNode = end ?? counterNode;
+
+  // Nothing to show — render nothing rather than an empty strip.
+  if (!startNode && !center && !endNode) return null;
+
+  // A toolbar role is only correct when the strip carries host-provided
+  // interactive controls. The auto hint/counter alone stay a plain div.
+  const hasInteractive = isValidElement(center) || isValidElement(start) || isValidElement(end);
+
+  return (
+    <div
+      role={hasInteractive ? 'toolbar' : undefined}
+      aria-label={hasInteractive ? 'Composer options' : undefined}
+      className={cn(
+        'flex min-h-7 items-center justify-between gap-2 px-1 pt-1',
+        TEXT_SIZE[size],
+        className,
+      )}
+    >
+      <div className="flex min-w-0 items-center gap-2">{startNode}</div>
+      {center ? <div className="flex items-center gap-2">{center}</div> : null}
+      <div className="flex items-center gap-2">{endNode}</div>
+    </div>
+  );
+}

package/src/tools/Chat/composer/ComposerMenuButton.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { Plus } from 'lucide-react';
+
+import { MenuBuilder, type MenuItem } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { BUTTON_SIZE } from './ComposerButton';
+import { useResolvedComposerSize } from './size-context';
+import type { ComposerSize } from './types';
+
+export interface ComposerMenuButtonProps {
+  /** Declarative menu tree (see `MenuBuilder`). */
+  items: MenuItem[];
+  /** Omit to inherit the composer's size. */
+  size?: ComposerSize;
+  disabled?: boolean;
+  /** Accessible label for the trigger. */
+  label?: string;
+  /** Trigger icon. Defaults to a `+`. */
+  icon?: React.ReactNode;
+}
+
+/**
+ * The composer's leading menu button — a `+` trigger that opens a
+ * declarative `MenuBuilder` (ChatGPT-style: attach, tools, more).
+ *
+ * Drop it into `composerSlots.inlineStart` so it sits at the start of
+ * the action bar. Size inherits from the composer unless set explicitly.
+ */
+export function ComposerMenuButton({
+  items,
+  size,
+  disabled,
+  label = 'Add files and more',
+  icon,
+}: ComposerMenuButtonProps) {
+  const sz = BUTTON_SIZE[useResolvedComposerSize(size)];
+
+  return (
+    <MenuBuilder items={items} side="top" align="start">
+      <button
+        type="button"
+        disabled={disabled}
+        aria-label={label}
+        title={label}
+        className={cn(
+          'inline-flex shrink-0 cursor-pointer items-center justify-center',
+          'text-muted-foreground transition-colors',
+          'hover:bg-accent hover:text-accent-foreground',
+          'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+          'disabled:pointer-events-none disabled:opacity-50 [&_svg]:shrink-0',
+          'data-[state=open]:bg-accent data-[state=open]:text-accent-foreground',
+          sz.button,
+          sz.icon,
+        )}
+      >
+        {icon ?? <Plus aria-hidden />}
+      </button>
+    </MenuBuilder>
+  );
+}

package/src/tools/Chat/composer/ComposerModelPicker.tsx

@@ -0,0 +1,104 @@
+'use client';
+
+import { useMemo } from 'react';
+import { ChevronDown } from 'lucide-react';
+
+import { MenuBuilder, type MenuItem } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useResolvedComposerSize } from './size-context';
+import type { ComposerSize } from './types';
+
+/** One selectable model. */
+export interface ComposerModelOption {
+  /** Stable id — also the radio value. */
+  id: string;
+  /** Pill text + menu row label. */
+  label: string;
+  /** Secondary muted line in the menu. */
+  description?: string;
+  disabled?: boolean;
+}
+
+export interface ComposerModelPickerProps {
+  /** Selected model id. */
+  value: string;
+  options: ComposerModelOption[];
+  onChange: (id: string) => void;
+  /** Omit to inherit the composer's size. */
+  size?: ComposerSize;
+  disabled?: boolean;
+  /** Accessible label for the trigger. */
+  label?: string;
+  className?: string;
+}
+
+/** Per-size geometry for the trigger pill. */
+const PILL_SIZE: Record<ComposerSize, { pill: string; text: string }> = {
+  sm: { pill: 'h-7 gap-1 px-2', text: 'text-xs' },
+  md: { pill: 'h-9 gap-1 px-2.5', text: 'text-sm' },
+  lg: { pill: 'h-11 gap-1.5 px-3', text: 'text-sm' },
+};
+
+/**
+ * A "Flash-Lite ▾" pill that opens a radio-group model picker — Gemini's
+ * model switcher. Drop it into `composerSlots.inlineEnd` (trailing
+ * cluster, before mic/send).
+ */
+export function ComposerModelPicker({
+  value,
+  options,
+  onChange,
+  size,
+  disabled,
+  label = 'Select model',
+  className,
+}: ComposerModelPickerProps) {
+  const sz = PILL_SIZE[useResolvedComposerSize(size)];
+  const current = options.find((o) => o.id === value);
+
+  const items: MenuItem[] = useMemo(
+    () => [
+      {
+        kind: 'radio-group',
+        id: 'model',
+        value,
+        onValueChange: onChange,
+        options: options.map((o) => ({
+          id: o.id,
+          value: o.id,
+          label: o.label,
+          description: o.description,
+          disabled: o.disabled,
+        })),
+      },
+    ],
+    [value, options, onChange],
+  );
+
+  return (
+    <MenuBuilder items={items} side="top" align="end">
+      <button
+        type="button"
+        disabled={disabled}
+        aria-label={label}
+        title={label}
+        className={cn(
+          'inline-flex shrink-0 cursor-pointer items-center rounded-full',
+          'text-muted-foreground transition-colors',
+          'hover:bg-accent hover:text-accent-foreground',
+          'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+          'disabled:pointer-events-none disabled:opacity-50',
+          'data-[state=open]:bg-accent data-[state=open]:text-accent-foreground',
+          '[&_svg]:size-4 [&_svg]:shrink-0',
+          sz.pill,
+          sz.text,
+          className,
+        )}
+      >
+        <span className="font-medium">{current?.label ?? value}</span>
+        <ChevronDown aria-hidden className="opacity-70" />
+      </button>
+    </MenuBuilder>
+  );
+}

package/src/tools/Chat/composer/ComposerRichTextarea.tsx

@@ -0,0 +1,88 @@
+'use client';
+
+import { useCallback, useMemo, useRef } from 'react';
+
+import {
+  LazyMarkdownEditor as MarkdownEditor,
+  type MarkdownEditorHandle,
+  type MentionConfig,
+} from '@djangocfg/ui-tools/markdown-editor';
+
+import { useRegisterComposer } from '../hooks/useAutoFocusOnStreamEnd';
+import type { ComposerSize, ComposerTextareaProps } from './types';
+
+/** Single-row baseline height per composer size (px). */
+const MIN_HEIGHT: Record<ComposerSize, number> = {
+  sm: 20,
+  md: 24,
+  lg: 28,
+};
+
+export interface ComposerRichTextareaProps extends ComposerTextareaProps {
+  /** `@`-mention autocomplete config. Omit for a plain rich textarea. */
+  mentions?: MentionConfig;
+}
+
+/**
+ * Drop-in TipTap-backed textarea for the composer's Tier B `Textarea`
+ * slot. Pre-wired with chat defaults — `unstyled` (the composer surface
+ * draws the frame), no toolbar, size-matched single-row height, and
+ * Enter-to-send. The host passes only `mentions` if it needs `@`
+ * autocomplete; everything else flows from `ComposerTextareaProps`.
+ *
+ * @example
+ * <Composer
+ *   slots={{ Textarea: (p) => <ComposerRichTextarea {...p} mentions={cfg} /> }}
+ * />
+ */
+export function ComposerRichTextarea({
+  composer,
+  placeholder,
+  disabled,
+  size,
+  className,
+  mentions,
+}: ComposerRichTextareaProps) {
+  // Tiptap captures the mentions object once on first render — keep its
+  // identity stable so the suggestion plugin stays wired.
+  const stableMentions = useMemo(() => mentions, [mentions]);
+
+  // The TipTap editor has no `<textarea>`, so the composer's default
+  // `focus` handle (which targets `textareaRef`) is a no-op here.
+  // Register the editor's real imperative handle with the chat context
+  // so `useAutoFocusOnStreamEnd` (refocus after the assistant reply)
+  // and the voice slot actually drive *this* editor.
+  const editorRef = useRef<MarkdownEditorHandle>(null);
+  const focus = useCallback(() => editorRef.current?.focus(), []);
+  const moveCursorToEnd = useCallback(
+    () => editorRef.current?.moveCursorToEnd(),
+    [],
+  );
+  const getValue = useCallback(() => composer.value, [composer.value]);
+  useRegisterComposer({
+    focus,
+    moveCursorToEnd,
+    getValue,
+    setValue: composer.setValue,
+  });
+
+  return (
+    <div className={className ?? 'min-w-0 flex-1'}>
+      <MarkdownEditor
+        ref={editorRef}
+        value={composer.value}
+        onChange={composer.setValue}
+        mentions={stableMentions}
+        placeholder={placeholder}
+        minHeight={MIN_HEIGHT[size]}
+        showToolbar={false}
+        unstyled
+        disabled={disabled}
+        onSubmit={() => {
+          if (composer.canSubmit) void composer.submit();
+          return true;
+        }}
+      />
+    </div>
+  );
+}

package/src/tools/Chat/composer/ComposerToolPill.tsx

@@ -0,0 +1,95 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { X } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useResolvedComposerSize } from './size-context';
+import type { ComposerSize } from './types';
+
+export interface ComposerToolPillProps {
+  /** Leading icon — a lucide-react element. */
+  icon?: ReactNode;
+  /** Pill text. */
+  label: ReactNode;
+  /** Accent fill when the tool/mode is active. */
+  active?: boolean;
+  /** Clicking the pill body (toggles the tool). */
+  onClick?: () => void;
+  /** When set, renders a trailing `×` that calls this instead. */
+  onRemove?: () => void;
+  disabled?: boolean;
+  /** Omit to inherit the composer's size. */
+  size?: ComposerSize;
+  className?: string;
+}
+
+/** Per-size geometry — round capsule heights matching the action bar. */
+const PILL_SIZE: Record<ComposerSize, { pill: string; text: string; icon: string }> = {
+  sm: { pill: 'h-7 gap-1 px-2', text: 'text-xs', icon: '[&_svg]:size-3.5' },
+  md: { pill: 'h-9 gap-1.5 px-3', text: 'text-sm', icon: '[&_svg]:size-4' },
+  lg: { pill: 'h-11 gap-2 px-3.5', text: 'text-sm', icon: '[&_svg]:size-[1.125rem]' },
+};
+
+/**
+ * A rounded action-bar capsule for a selected tool or mode — Gemini's
+ * "🎨 Images" pill. Drop it into `composerSlots.inlineStart` (leading
+ * cluster). When `onRemove` is set the pill shows a trailing `×`.
+ */
+export function ComposerToolPill({
+  icon,
+  label,
+  active = false,
+  onClick,
+  onRemove,
+  disabled,
+  size,
+  className,
+}: ComposerToolPillProps) {
+  const sz = PILL_SIZE[useResolvedComposerSize(size)];
+  return (
+    <div
+      className={cn(
+        'inline-flex shrink-0 items-center rounded-full border transition-colors',
+        sz.pill,
+        sz.text,
+        sz.icon,
+        active
+          ? 'border-transparent bg-accent text-accent-foreground'
+          : 'border-border bg-transparent text-muted-foreground',
+        disabled && 'pointer-events-none opacity-50',
+        className,
+      )}
+    >
+      <button
+        type="button"
+        onClick={onClick}
+        disabled={disabled}
+        aria-pressed={onClick ? active : undefined}
+        className={cn(
+          'inline-flex items-center gap-1.5 outline-none',
+          onClick && !disabled && 'cursor-pointer hover:text-foreground',
+        )}
+      >
+        {icon ? <span className="flex shrink-0 [&_svg]:shrink-0">{icon}</span> : null}
+        <span className="font-medium">{label}</span>
+      </button>
+      {onRemove ? (
+        <button
+          type="button"
+          onClick={onRemove}
+          disabled={disabled}
+          aria-label="Remove"
+          title="Remove"
+          className={cn(
+            '-mr-1 ml-0.5 inline-flex size-5 cursor-pointer items-center justify-center',
+            'rounded-full transition-colors hover:bg-foreground/10 [&_svg]:size-3.5',
+          )}
+        >
+          <X aria-hidden />
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/tools/Chat/composer/index.ts

@@ -0,0 +1,45 @@
+'use client';
+
+/** Composer — the `<Composer>` shell + its slot kit. */
+
+export {
+  Composer,
+  type ComposerProps,
+  type ComposerSize,
+  type ComposerAppearance,
+} from './Composer';
+export { ComposerButton, BUTTON_SIZE, type ComposerButtonProps } from './ComposerButton';
+export { ComposerMenuButton, type ComposerMenuButtonProps } from './ComposerMenuButton';
+export { ComposerRichTextarea, type ComposerRichTextareaProps } from './ComposerRichTextarea';
+export { ComposerActionBar } from './ComposerActionBar';
+export { ComposerToolPill, type ComposerToolPillProps } from './ComposerToolPill';
+export {
+  ComposerModelPicker,
+  type ComposerModelPickerProps,
+  type ComposerModelOption,
+} from './ComposerModelPicker';
+export {
+  ComposerBanner,
+  type ComposerBannerProps,
+  type ComposerBannerAction,
+} from './ComposerBanner';
+export { ComposerFooter } from './ComposerFooter';
+export { useResolvedComposerSize } from './size-context';
+export {
+  useComposerActions,
+  type UseComposerActionsParams,
+  type ComposerActionClusters,
+} from './useComposerActions';
+export type {
+  ComposerAction,
+  ComposerActionVisibility,
+  ComposerLayout,
+  ComposerSlots,
+  ComposerSlotComponents,
+  ComposerSlotProps,
+  ComposerFooterProps,
+  SendButtonProps,
+  AttachButtonProps,
+  ComposerTextareaProps,
+  ActionBarProps,
+} from './types';

package/src/tools/Chat/composer/size-context.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+import type { ComposerSize } from './types';
+
+/**
+ * Propagates the composer's `size` to slot components placed in
+ * `composerSlots.inlineStart` / `inlineEnd` (`ComposerMenuButton`,
+ * `ComposerModelPicker`, `ComposerToolPill`). Without this a host has
+ * to repeat `size` on every slotted control to keep the action bar
+ * visually aligned; with it, an explicit `size` prop on the slot
+ * component still wins, but omitting it inherits the composer's size.
+ */
+const ComposerSizeContext = createContext<ComposerSize | null>(null);
+
+export const ComposerSizeProvider = ComposerSizeContext.Provider;
+
+/**
+ * Resolve the effective size for a slotted control: an explicit prop
+ * always wins; otherwise inherit from the composer; final fallback `md`.
+ */
+export function useResolvedComposerSize(explicit?: ComposerSize): ComposerSize {
+  const inherited = useContext(ComposerSizeContext);
+  return explicit ?? inherited ?? 'md';
+}