@djangocfg/ui-tools 2.1.411 → 2.1.412

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.411",
+  "version": "2.1.412",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -154,8 +154,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.411",
-    "@djangocfg/ui-core": "^2.1.411",
+    "@djangocfg/i18n": "^2.1.412",
+    "@djangocfg/ui-core": "^2.1.412",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -210,9 +210,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.411",
-    "@djangocfg/typescript-config": "^2.1.411",
-    "@djangocfg/ui-core": "^2.1.411",
+    "@djangocfg/i18n": "^2.1.412",
+    "@djangocfg/typescript-config": "^2.1.412",
+    "@djangocfg/ui-core": "^2.1.412",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+import type { ComposerAttachHandle } from './types';
+
+/**
+ * Exposes the composer's attach pipeline to descendants — chiefly
+ * `ComposerMenuButton`, so a `+`-menu "Attach" item reaches the same
+ * `openPicker` as the paperclip button without a prop drill.
+ *
+ * `null` when no attach pipeline is mounted (composer without
+ * `showAttachmentButton` / `attach` config).
+ */
+const AttachContext = createContext<ComposerAttachHandle | null>(null);
+
+export const AttachProvider = AttachContext.Provider;
+
+/** Read the attach pipeline. Returns `null` outside an attach-enabled composer. */
+export function useComposerAttachContext(): ComposerAttachHandle | null {
+  return useContext(AttachContext);
+}

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { forwardRef, useEffect, useRef } from 'react';
+import { forwardRef, useEffect, useRef, useState } from 'react';
 
 import { Textarea } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
@@ -8,13 +8,16 @@ import { cn } from '@djangocfg/ui-core/lib';
 import { useChatContextOptional } from '../context';
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
 import { Attachments } from '../messages/Attachments';
+import { AttachProvider } from './AttachContext';
 import { ComposerActionBar } from './ComposerActionBar';
 import { ComposerButton } from './ComposerButton';
 import { ComposerFooter } from './ComposerFooter';
 import { ComposerSizeProvider } from './size-context';
 import { useComposerActions } from './useComposerActions';
+import { useComposerAttach } from './useComposerAttach';
 import type {
   ComposerAppearance,
+  ComposerAttachConfig,
   ComposerFooterProps,
   ComposerLayout,
   ComposerSize,
@@ -29,7 +32,16 @@ export interface ComposerProps {
   composer: UseChatComposerReturn;
   placeholder?: string;
   disabled?: boolean;
+  /** Render the paperclip attach button. The composer ships a built-in
+   *  file picker — paperclip, `+` menu, drag-drop and Ctrl+V paste all
+   *  funnel through one validated pipeline. */
   showAttachmentButton?: boolean;
+  /** Tune the built-in attach pipeline — accepted types, size / count
+   *  caps, paste, and the optional upload transport. */
+  attach?: ComposerAttachConfig;
+  /** Override the built-in file picker. When set, the paperclip and the
+   *  `+`-menu attach item call this instead of opening the native picker
+   *  — for hosts that drive their own (e.g. a Wails native dialog). */
   onPickFiles?: () => void;
   className?: string;
   textareaClassName?: string;
@@ -130,6 +142,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     placeholder = 'Type a message...',
     disabled,
     showAttachmentButton = false,
+    attach,
     onPickFiles,
     className,
     textareaClassName,
@@ -220,13 +233,60 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     editable.focus();
   };
 
+  // ── Attach pipeline ────────────────────────────────────────────────────
+  // The built-in file picker is mounted whenever the host renders the
+  // paperclip OR passes an `attach` config. `onPickFiles` (if given)
+  // overrides it — a host driving its own picker (e.g. a Wails dialog).
+  const attachEnabled = showAttachmentButton || attach != null;
+  const attachHandle = useComposerAttach({
+    composer,
+    config: attach ?? {},
+    disabled: isDisabled,
+    pasteScopeRef: surfaceRef,
+  });
+  // The resolved click handler: host override wins, else the built-in
+  // picker. `undefined` when attaching is not enabled at all.
+  const pickFiles = !attachEnabled
+    ? undefined
+    : (onPickFiles ?? attachHandle.openPicker);
+
+  // Drag-drop onto the input surface — same validated path as the picker.
+  const [isDragging, setIsDragging] = useState(false);
+  const dragDepth = useRef(0);
+  const handleDragEnter = (e: React.DragEvent) => {
+    if (!attachEnabled || isDisabled) return;
+    if (!e.dataTransfer.types.includes('Files')) return;
+    e.preventDefault();
+    dragDepth.current += 1;
+    setIsDragging(true);
+  };
+  const handleDragOver = (e: React.DragEvent) => {
+    if (attachEnabled && !isDisabled && e.dataTransfer.types.includes('Files')) {
+      e.preventDefault();
+    }
+  };
+  const handleDragLeave = (e: React.DragEvent) => {
+    if (!attachEnabled || isDisabled) return;
+    e.preventDefault();
+    dragDepth.current = Math.max(0, dragDepth.current - 1);
+    if (dragDepth.current === 0) setIsDragging(false);
+  };
+  const handleDrop = (e: React.DragEvent) => {
+    if (!attachEnabled || isDisabled) return;
+    e.preventDefault();
+    dragDepth.current = 0;
+    setIsDragging(false);
+    const dropped = Array.from(e.dataTransfer.files ?? []);
+    if (dropped.length > 0) attachHandle.attachFiles(dropped);
+  };
+
   // Merge built-in send/stop/attach descriptors with host arrays.
   const { actionsStart, actionsEnd } = useComposerActions({
     composer,
     isStreaming,
     isDisabled,
     showAttachmentButton,
-    onPickFiles,
+    onPickFiles: pickFiles,
     actionsStart: composerSlots?.actionsStart,
     actionsEnd: composerSlots?.actionsEnd,
     onSend: () => void composer.submit(),
@@ -311,11 +371,19 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       <AttachSlot
         disabled={isDisabled}
         size={size}
-        onClick={() => onPickFiles?.()}
+        onClick={() => pickFiles?.()}
         {...slotProps?.attach}
       />
     ) : null;
 
+  // Hidden native file input — the picker the paperclip + `+` menu open.
+  // Rendered once per composer; only present when the pipeline is active
+  // and no host override is in play (an override owns its own picker).
+  const hiddenFileInput =
+    attachEnabled && !onPickFiles ? (
+      <input {...attachHandle.inputProps} />
+    ) : null;
+
   // ── Footer ─────────────────────────────────────────────────────────────
   const footerNode =
     footer === false ? null : (
@@ -331,25 +399,53 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
     (composer.attachments.length > 0 ? (
       <Attachments
         attachments={composer.attachments}
-        onRemove={(a) => composer.removeAttachment(a.id)}
+        // Route through the attach pipeline so a removed attachment's
+        // object-URL is revoked; falls back to a plain remove when the
+        // pipeline is not mounted (host-managed attachments).
+        onRemove={(a) =>
+          attachEnabled
+            ? attachHandle.removeAttachment(a.id)
+            : composer.removeAttachment(a.id)
+        }
       />
     ) : null);
 
   // ── Inline (compact single-row) layout ─────────────────────────────────
+  // Drag-drop handlers shared by both layouts. No-op when attaching is
+  // disabled — the handlers themselves early-return.
+  const dragProps = {
+    onDragEnter: handleDragEnter,
+    onDragOver: handleDragOver,
+    onDragLeave: handleDragLeave,
+    onDrop: handleDrop,
+  };
+  // A faint accent wash + ring while a file is dragged over the composer.
+  const dragOverlay =
+    isDragging ? (
+      <div
+        aria-hidden
+        className="pointer-events-none absolute inset-0 z-10 rounded-[inherit] bg-primary/5 ring-2 ring-inset ring-primary/40"
+      />
+    ) : null;
+
   // Start cluster sits left of the textarea, end cluster right of it —
   // `[📎][actionsStart] [textarea] [actionsEnd][🎙][▶]` (§3.6).
   if (layout === 'inline') {
     return (
       <ComposerSizeProvider value={size}>
+       <AttachProvider value={attachHandle}>
         <div
           ref={ref}
+          {...dragProps}
           className={cn(
-            'border-t border-border bg-background/95',
+            'relative border-t border-border bg-background/95',
             sz.containerPadding,
             ap.containerPadding,
             className,
           )}
         >
+          {hiddenFileInput}
+          {dragOverlay}
           {trayNode ? <div className="mb-1.5">{trayNode}</div> : null}
           <div
             className={cn(
@@ -385,6 +481,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
           </div>
           {footerNode}
         </div>
+       </AttachProvider>
       </ComposerSizeProvider>
     );
   }
@@ -453,19 +550,24 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
 
   return (
     <ComposerSizeProvider value={size}>
+     <AttachProvider value={attachHandle}>
       <div
         ref={ref}
+        {...dragProps}
         className={cn(
-          'border-t border-border bg-background/95',
+          'relative border-t border-border bg-background/95',
           sz.containerPadding,
           ap.containerPadding,
           className,
         )}
       >
+        {hiddenFileInput}
+        {dragOverlay}
         {trayNode ? <div className="mb-2">{trayNode}</div> : null}
         {surfaceWrapper}
         {footerNode}
       </div>
+     </AttachProvider>
     </ComposerSizeProvider>
   );
 });

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

@@ -1,17 +1,32 @@
 'use client';
 
-import { Plus } from 'lucide-react';
+import { Paperclip, Plus } from 'lucide-react';
 
 import { MenuBuilder, type MenuItem } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
+import { useComposerAttachContext } from './AttachContext';
 import { BUTTON_SIZE } from './ComposerButton';
 import { useResolvedComposerSize } from './size-context';
 import type { ComposerSize } from './types';
 
+/**
+ * Built-in "Attach" menu item config. When `attachItem` is set, the
+ * menu button prepends a row wired to the composer's attach pipeline —
+ * the SAME `openPicker` the paperclip button uses. Pass `true` for
+ * defaults, or an object to override the label / icon.
+ */
+export type ComposerMenuAttachItem =
+  | boolean
+  | { label?: string };
+
 export interface ComposerMenuButtonProps {
   /** Declarative menu tree (see `MenuBuilder`). */
   items: MenuItem[];
+  /** Prepend a built-in "Attach" row wired to the composer's attach
+   *  pipeline. Requires an attach-enabled `<Composer>` ancestor;
+   *  silently omitted otherwise. */
+  attachItem?: ComposerMenuAttachItem;
   /** Omit to inherit the composer's size. */
   size?: ComposerSize;
   disabled?: boolean;
@@ -30,15 +45,37 @@ export interface ComposerMenuButtonProps {
  */
 export function ComposerMenuButton({
   items,
+  attachItem,
   size,
   disabled,
   label = 'Add files and more',
   icon,
 }: ComposerMenuButtonProps) {
   const sz = BUTTON_SIZE[useResolvedComposerSize(size)];
+  const attach = useComposerAttachContext();
+
+  // Prepend the built-in "Attach" row when requested AND an attach
+  // pipeline is in scope — it reuses the exact same `openPicker` as the
+  // paperclip button, so both inputs are one unified path.
+  const attachLabel =
+    typeof attachItem === 'object' ? (attachItem.label ?? 'Attach files') : 'Attach files';
+  const resolvedItems: MenuItem[] =
+    attachItem && attach
+      ? [
+          {
+            kind: 'item',
+            id: '__composer_attach',
+            label: attachLabel,
+            icon: Paperclip,
+            disabled: attach.disabled,
+            onSelect: () => attach.openPicker(),
+          },
+          ...items,
+        ]
+      : items;
 
   return (
-    <MenuBuilder items={items} side="top" align="start">
+    <MenuBuilder items={resolvedItems} side="top" align="start">
       <button
         type="button"
         disabled={disabled}

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

@@ -0,0 +1,53 @@
+/**
+ * `File → ChatAttachment` — the engine-side producer that was missing.
+ *
+ * Before this, every host re-implemented the conversion (see the fake
+ * stub in `apps/storybook/.../SpeechAndAttachments`). It lives here so
+ * the picker, drag-drop and paste paths all mint identical attachments.
+ */
+
+import { createId } from '../core/ids';
+import { getAssetTypeFromMime } from '../../Uploader';
+import type { ChatAttachment } from '../types';
+
+/** Map a MIME type to the `ChatAttachment.type` discriminant. */
+function attachmentTypeFromMime(mime: string): ChatAttachment['type'] {
+  if (mime.startsWith('image/')) return 'image';
+  if (mime.startsWith('audio/')) return 'audio';
+  if (mime.startsWith('video/')) return 'video';
+  // getAssetTypeFromMime returns 'document' for everything else; the
+  // ChatAttachment union has no 'document' member — collapse to 'file'.
+  const asset = getAssetTypeFromMime(mime);
+  return asset === 'document' ? 'file' : asset;
+}
+
+/**
+ * Convert a picked/dropped/pasted `File` into a `ChatAttachment`.
+ *
+ * The `url` is an object-URL (`URL.createObjectURL`) — instantly usable
+ * for previews. When a host uploads the file via `uploadFn`, it replaces
+ * `url` with the remote URL and flips `status` to `'ready'`.
+ *
+ * `status` defaults to `'ready'`: with no `uploadFn` the attachment is
+ * immediately usable (current behaviour). The attach pipeline overrides
+ * it to `'uploading'` when an upload is in flight.
+ */
+export function fileToAttachment(file: File): ChatAttachment {
+  const mime = file.type || 'application/octet-stream';
+  return {
+    id: createId('att'),
+    type: attachmentTypeFromMime(mime),
+    url: URL.createObjectURL(file),
+    name: file.name,
+    mimeType: mime,
+    sizeBytes: file.size,
+    status: 'ready',
+  };
+}
+
+/** Revoke an attachment's object-URL, if it holds one. Call on remove. */
+export function revokeAttachmentUrl(attachment: Pick<ChatAttachment, 'url'>): void {
+  if (attachment.url.startsWith('blob:')) {
+    URL.revokeObjectURL(attachment.url);
+  }
+}

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

@@ -9,7 +9,11 @@ export {
   type ComposerAppearance,
 } from './Composer';
 export { ComposerButton, BUTTON_SIZE, type ComposerButtonProps } from './ComposerButton';
-export { ComposerMenuButton, type ComposerMenuButtonProps } from './ComposerMenuButton';
+export {
+  ComposerMenuButton,
+  type ComposerMenuButtonProps,
+  type ComposerMenuAttachItem,
+} from './ComposerMenuButton';
 export { ComposerRichTextarea, type ComposerRichTextareaProps } from './ComposerRichTextarea';
 export { ComposerActionBar } from './ComposerActionBar';
 export { ComposerToolPill, type ComposerToolPillProps } from './ComposerToolPill';
@@ -30,6 +34,12 @@ export {
   type UseComposerActionsParams,
   type ComposerActionClusters,
 } from './useComposerActions';
+export {
+  useComposerAttach,
+  type UseComposerAttachParams,
+} from './useComposerAttach';
+export { useComposerAttachContext } from './AttachContext';
+export { fileToAttachment, revokeAttachmentUrl } from './fileToAttachment';
 export type {
   ComposerAction,
   ComposerActionVisibility,
@@ -42,4 +52,9 @@ export type {
   AttachButtonProps,
   ComposerTextareaProps,
   ActionBarProps,
+  ComposerAcceptType,
+  ComposerAttachConfig,
+  ComposerAttachHandle,
+  ComposerUploadFn,
+  ComposerUploadResult,
 } from './types';

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

@@ -3,6 +3,7 @@
 import type { ComponentType, ReactNode } from 'react';
 
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
+import type { ChatAttachment } from '../types';
 
 /** Composer visual size — shared across the `<Composer>` API. */
 export type ComposerSize = 'sm' | 'md' | 'lg';
@@ -141,3 +142,73 @@ export interface ComposerFooterProps {
   size?: ComposerSize;
   className?: string;
 }
+
+// ── Attach pipeline ─────────────────────────────────────────────────────────
+
+/** Asset categories the picker accepts. Maps to MIME prefixes / extensions. */
+export type ComposerAcceptType = 'image' | 'audio' | 'video' | 'document';
+
+/**
+ * Result a host's `uploadFn` resolves to — the remote location the
+ * attachment's `url` is rewritten to once the upload completes.
+ */
+export interface ComposerUploadResult {
+  url: string;
+  thumbnailUrl?: string;
+}
+
+/**
+ * Optional upload transport. The single environment-specific seam:
+ * - omitted  → attachments stay local (`blob:` object-URL, `status:'ready'`).
+ * - web      → multipart POST to a CDN.
+ * - Wails    → a Wails-bound upload method.
+ *
+ * `onProgress` receives 0..1; call it to drive the staging-tray progress.
+ */
+export type ComposerUploadFn = (
+  file: File,
+  onProgress: (fraction: number) => void,
+) => Promise<ComposerUploadResult>;
+
+/**
+ * Declarative config for the built-in attach pipeline. When present (or
+ * when `showAttachmentButton` is set), the composer mounts its own file
+ * picker — paperclip, `+` menu, drag-drop and paste all funnel through it.
+ */
+export interface ComposerAttachConfig {
+  /** Accepted asset categories. Default: all four. */
+  accept?: ComposerAcceptType[];
+  /** Max files per message. Falls back to the composer's `maxAttachments`. */
+  maxFiles?: number;
+  /** Per-file size cap in bytes. Default: unlimited. */
+  maxSizeBytes?: number;
+  /** Allow selecting more than one file at once. Default `true`. */
+  multiple?: boolean;
+  /** Upload transport — see {@link ComposerUploadFn}. */
+  uploadFn?: ComposerUploadFn;
+  /** Enable Ctrl+V / Cmd+V paste-to-attach. Default `true`. */
+  pasteEnabled?: boolean;
+  /** Called when a file is rejected (size / type / count). */
+  onReject?: (file: File, reason: 'size' | 'type' | 'count') => void;
+}
+
+/** Imperative handle the attach pipeline exposes to the composer + menu. */
+export interface ComposerAttachHandle {
+  /** Open the native file picker. */
+  openPicker: () => void;
+  /** Funnel already-resolved files (drop / paste) through validation. */
+  attachFiles: (files: File[]) => void;
+  /** Remove a staged attachment, revoking its object-URL first. */
+  removeAttachment: (id: string) => void;
+  /** True when attaching is unavailable (disabled / at file cap). */
+  disabled: boolean;
+  /** Hidden `<input type=file>` props — the composer renders this node. */
+  inputProps: {
+    ref: React.RefObject<HTMLInputElement | null>;
+    type: 'file';
+    accept: string;
+    multiple: boolean;
+    hidden: true;
+    onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
+  };
+}