@alia.onl/sdk 13.1.0 → 15.2.1

package/src/components/AliaComposer.tsx

@@ -0,0 +1,382 @@
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  type ReactNode,
+  type RefObject,
+} from 'react';
+import {
+  View,
+  type NativeSyntheticEvent,
+  type TextInput,
+  type TextInputKeyPressEventData,
+} from 'react-native';
+import {
+  ComposerPanel,
+  type ComposerPanelAddMenuGroup,
+  type ComposerPanelAttachment,
+  type ComposerPanelPermissionOption,
+} from '@oxy.so/bloom/composer-panel';
+import { toast } from '@oxy.so/bloom/toast';
+import { Text } from '@oxy.so/bloom/typography';
+import { useAttachmentIntake } from '../hooks/useAttachmentIntake';
+import { useDictation } from '../hooks/useDictation';
+import type { Completion } from '../lib/suggestions';
+import { composerTiles, intakeError } from '../lib/attachment-tiles';
+import type { IntakeKind } from '../lib/attachment-intake';
+import { KeyboardAvoidingView } from '../lib/keyboard';
+import { type AliaChatLabels, AliaChatLabelsProvider, useLabels } from '../lib/labels';
+import type { AskedQuestion } from '../lib/questions';
+import type { VoiceErrorCode } from '../lib/speech-messages';
+import type { AliaAttachment, AliaSuggestion } from '../types';
+import {
+  ComposerDropOverlay,
+  useComposerDropTarget,
+  useComposerPasteTarget,
+} from './ComposerDropZone';
+import { ComposerSuggestions } from './ComposerSuggestions';
+import { QuestionCard } from './QuestionCard';
+
+/**
+ * Alia's composer: the ONE composer of the sheet, the screen and the Alia app, Bloom's
+ * `ComposerPanel` plus everything Alia puts around it.
+ *
+ * Everything the panel draws is Bloom's: the prompt, the add menu, the mode selector (the
+ * panel's permission pill, which is the host's power-level selector), the mic, send / stop, the
+ * attachment tiles and the status tab. What this adds is what every Alia surface needs the same
+ * way: files arriving by paste and drop (read with real progress, retried, refused with a
+ * sentence), dictation, the suggestions over the field, and the questions Alia asked docked
+ * above it. What differs per surface is a prop: the add menu and the modes are the host's,
+ * and a host that offers no way to attach files gets no paste or drop either.
+ *
+ * A running turn is the stop control and the container's thinking line; the panel takes no
+ * loader (Bloom's loader traces the pill, and would light the status tab too).
+ */
+const EMPTY_ADD_MENU: readonly ComposerPanelAddMenuGroup[] = [];
+/** `[]` hides the selector; Bloom's own four modes are not Alia's. */
+const NO_MODES: readonly ComposerPanelPermissionOption[] = [];
+const NO_ATTACHMENTS: readonly AliaAttachment[] = [];
+
+/** The rows over the field, as `useComposerSuggestions` hands them back. */
+export interface AliaComposerSuggestions<T extends AliaSuggestion = AliaSuggestion> {
+  completions: readonly Completion<T>[];
+  /** The row the keyboard is on, or -1. */
+  selected: number;
+  onPick: (suggestion: T) => void;
+}
+
+/** The questions Alia asked and the person has not answered (`usePendingQuestions`). */
+export interface AliaComposerQuestions {
+  items: AskedQuestion[];
+  /** Sends the answers as the next message. */
+  onSubmit: (message: string) => void;
+  onDismiss: () => void;
+}
+
+export interface AliaComposerProps<T extends AliaSuggestion = AliaSuggestion> {
+  value: string;
+  onValueChange: (value: string) => void;
+  /** Sends the draft. */
+  onSubmit: () => void;
+  /** A turn is streaming: send becomes stop. */
+  busy?: boolean;
+  /** The composer is closed (usage limit). Never reaches stop. */
+  disabled?: boolean;
+  onStop?: () => void;
+  placeholder?: string;
+  /** The mode selector (the power levels). Omit to hide it. */
+  modes?: readonly ComposerPanelPermissionOption[];
+  mode?: string;
+  onModeChange?: (mode: string) => void;
+  addMenu?: readonly ComposerPanelAddMenuGroup[];
+  onAddMenuSelect?: (rowId: string) => void;
+  /**
+   * The draft's files. A composer given no `onAddAttachment` takes none: its surface sends
+   * nothing but the text, so no paste, drop or tile may say otherwise.
+   */
+  attachments?: readonly AliaAttachment[];
+  onAddAttachment?: (attachment: AliaAttachment) => void;
+  onRemoveAttachment?: (id: string) => void;
+  /** The kinds of file the host's send carries; others are refused with a sentence. Default both. */
+  attachmentKinds?: readonly IntakeKind[];
+  /** The suggestions drawn over the field. Their keys are the host's `onKeyPress`. */
+  suggestions?: AliaComposerSuggestions<T>;
+  /** What Alia is waiting on, docked above the composer. */
+  questions?: AliaComposerQuestions;
+  /** The tab on the card's top edge (`ComposerPanelStatusTab`). */
+  status?: ReactNode;
+  /** Drawn where send would be while there is nothing to send (voice mode). */
+  emptyAction?: ReactNode;
+  /**
+   * Drawn over the conversation at the composer's top-right corner, and so pinned with it —
+   * the jump to the newest turn.
+   */
+  accessory?: ReactNode;
+  /** The field's keys, before the panel's own Enter rule (suggestions over it). */
+  onKeyPress?: (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => void;
+  /** The host already avoids the keyboard. */
+  disableKeyboardAvoidance?: boolean;
+  /** The field itself, for a host that moves focus into it. */
+  inputRef?: RefObject<TextInput | null>;
+  /** Dictation's language, a BCP-47 tag; omitted, the platform's own. */
+  speechLanguage?: string;
+  /** Alia's API, which transcribes dictation; omitted, `EXPO_PUBLIC_ALIA_API_URL` or production. */
+  apiUrl?: string;
+  /** Where a refused file or a failed dictation is said; omitted, Bloom's toast. */
+  onError?: (message: string) => void;
+  /** The composer's copy, over whatever labels are already in reach. */
+  labels?: Partial<AliaChatLabels>;
+}
+
+function AliaComposerBody<T extends AliaSuggestion>({
+  value,
+  onValueChange,
+  onSubmit,
+  busy = false,
+  disabled = false,
+  onStop,
+  placeholder,
+  modes,
+  mode,
+  onModeChange,
+  addMenu,
+  onAddMenuSelect,
+  attachments = NO_ATTACHMENTS,
+  onAddAttachment,
+  onRemoveAttachment,
+  attachmentKinds,
+  suggestions,
+  questions,
+  status,
+  emptyAction,
+  accessory,
+  onKeyPress,
+  disableKeyboardAvoidance = false,
+  inputRef,
+  speechLanguage,
+  apiUrl,
+  onError,
+}: Omit<AliaComposerProps<T>, 'labels'>) {
+  const labels = useLabels();
+  const report = useCallback(
+    (message: string) => (onError ? onError(message) : toast.error(message)),
+    [onError],
+  );
+  // Paste is a DOM gesture on a DOM node; the panel publishes no ref to one.
+  const hostId = `composer-${useId().replace(/[^a-zA-Z0-9]/g, '')}`;
+
+  // The list's owner releases what a removed tile held (the draft store does).
+  const takesFiles = onAddAttachment !== undefined;
+  const addAttachment = useCallback(
+    (attachment: AliaAttachment) => onAddAttachment?.(attachment),
+    [onAddAttachment],
+  );
+  const removeAttachment = useCallback(
+    (id: string) => onRemoveAttachment?.(id),
+    [onRemoveAttachment],
+  );
+  const intake = useAttachmentIntake({ addAttachment, kinds: attachmentKinds });
+  // A surface that takes no files still catches a drop or a pasted file, so
+  // the browser does not open it in place of the page — and then does nothing.
+  const acceptsFiles = takesFiles && !disabled && !busy;
+  useComposerPasteTarget({ elementId: hostId, enabled: acceptsFiles, onFiles: intake.accept });
+  // Web only; on native there is no drag, and the hook attaches nothing.
+  const isDragOver = useComposerDropTarget({
+    elementId: hostId,
+    enabled: acceptsFiles,
+    onFiles: intake.accept,
+  });
+
+  /**
+   * A refused file — too large, or empty — is said once, in a toast, and
+   * leaves the queue.
+   *
+   * It is not a tile because Bloom's retry is the PANEL's: with
+   * `onAttachmentRetry` set, every error tile draws a retry button, and a
+   * refusal has nothing to retry — the same file reaches the same verdict.
+   * A tile whose button does nothing is worse than a sentence.
+   * A failed READ stays, as an error tile whose retry re-reads its file.
+   */
+  useEffect(() => {
+    for (const item of intake.items) {
+      if (item.status !== 'refused') continue;
+      const error = intakeError(item, labels);
+      if (error !== undefined) report(error);
+      intake.dismiss(item.id);
+    }
+  }, [intake, labels, report]);
+
+  // Landed files, then the ones being read with their real progress, then the
+  // ones whose read failed, with why.
+  const tiles = useMemo<ComposerPanelAttachment[]>(
+    () =>
+      composerTiles(attachments, intake.items, labels)
+        .filter((tile) => tile.error === undefined || tile.retryable === true)
+        .map(({ retryable: _retryable, ...tile }) => tile),
+    [attachments, intake.items, labels],
+  );
+  const removeTile = useCallback(
+    (id: string) => {
+      if (intake.items.some((item) => item.id === id)) intake.cancel(id);
+      else removeAttachment(id);
+    },
+    [intake, removeAttachment],
+  );
+
+  // The draft at the moment the transcription lands, not when the mic was pressed.
+  const draftRef = useRef(value);
+  draftRef.current = value;
+  const insertDictation = useCallback(
+    (text: string) => {
+      const draft = draftRef.current;
+      onValueChange(draft === '' ? text : `${draft} ${text}`);
+    },
+    [onValueChange],
+  );
+  const dictation = useDictation({
+    lang: speechLanguage,
+    ...(apiUrl === undefined ? {} : { apiUrl }),
+    onText: insertDictation,
+  });
+  // Said once per failure: a host re-rendering with new labels is not a new failure.
+  const sayVoiceError = useRef<(code: VoiceErrorCode, retry: (() => void) | null) => void>(
+    () => undefined,
+  );
+  sayVoiceError.current = (code, retry) => {
+    const message = labels.voiceError(code);
+    if (onError || retry === null) report(message);
+    else toast.error(message, { action: { label: labels.composerRetry, onClick: retry } });
+  };
+  const {
+    errorCode: dictationError,
+    canRetry: dictationCanRetry,
+    retry: retryDictation,
+  } = dictation;
+  useEffect(() => {
+    if (dictationError !== null)
+      sayVoiceError.current(dictationError, dictationCanRetry ? () => void retryDictation() : null);
+  }, [dictationError, dictationCanRetry, retryDictation]);
+
+  const handleListeningChange = useCallback(
+    async (next: boolean) => {
+      if (next) {
+        if (!disabled && !busy && !dictation.isTranscribing) void dictation.start();
+        return;
+      }
+      await dictation.stop();
+    },
+    [disabled, busy, dictation],
+  );
+  const remainingSeconds =
+    dictation.remainingMs === null ? null : Math.ceil(dictation.remainingMs / 1000);
+
+  const hasContent = value.trim() !== '' || attachments.length > 0;
+  const panelLabels = useMemo(
+    () => ({
+      message: labels.composerMessage,
+      addMenu: labels.composerAddMenu,
+      permissions: labels.composerModes,
+      permissionMode: labels.composerModes,
+      voice: labels.composerVoice,
+      send: labels.composerSend,
+      stop: labels.composerStop,
+      remove: labels.composerRemove,
+      // Bloom names the button "<retry> <file name>".
+      retry: labels.composerRetry,
+    }),
+    [labels],
+  );
+
+  const host = (
+    // The transcript's column (Bloom's `AgentChat`: 768 at most, centred), so
+    // the composer and the conversation share one edge.
+    <View id={hostId} className="w-full max-w-[768px] self-center">
+      {remainingSeconds !== null ? (
+        <Text
+          className="mb-1 self-center text-sm text-text-secondary"
+          accessibilityLiveRegion="polite"
+          aria-live="polite"
+        >
+          {labels.dictationRemaining(remainingSeconds)}
+        </Text>
+      ) : null}
+      <ComposerPanel
+        value={value}
+        onValueChange={onValueChange}
+        onSubmit={() => onSubmit()}
+        inputRef={inputRef}
+        busy={busy}
+        onStop={onStop}
+        disabled={disabled || intake.isBusy || !hasContent}
+        placeholder={placeholder ?? labels.placeholder}
+        addMenu={addMenu ?? EMPTY_ADD_MENU}
+        onAddMenuSelect={onAddMenuSelect}
+        permissions={modes ?? NO_MODES}
+        permission={mode}
+        onPermissionChange={onModeChange}
+        voiceState={
+          dictation.isTranscribing
+            ? 'transcribing'
+            : dictation.isRecording || dictation.state === 'requesting-permission'
+              ? 'recording'
+              : 'idle'
+        }
+        onVoiceStateChange={(next) => void handleListeningChange(next === 'recording')}
+        attachments={tiles}
+        onRemoveAttachment={removeTile}
+        // Clears the tile's error and starts its progress again: `intake.retry`
+        // puts the item back to `reading` over the same `File`.
+        onAttachmentRetry={intake.retry}
+        question={
+          questions && questions.items.length > 0 ? (
+            <QuestionCard
+              questions={questions.items}
+              onSubmit={questions.onSubmit}
+              onDismiss={questions.onDismiss}
+            />
+          ) : undefined
+        }
+        status={status}
+        emptyAction={emptyAction}
+        onKeyPress={onKeyPress}
+        labels={panelLabels}
+      />
+      <ComposerDropOverlay visible={takesFiles && isDragOver} enabled={acceptsFiles} />
+      {accessory ? (
+        <View pointerEvents="box-none" className="absolute bottom-full right-0 mb-2">
+          {accessory}
+        </View>
+      ) : null}
+    </View>
+  );
+
+  return (
+    <>
+      {suggestions ? (
+        <ComposerSuggestions
+          completions={suggestions.completions}
+          selected={suggestions.selected}
+          onPick={suggestions.onPick}
+        />
+      ) : null}
+      {disableKeyboardAvoidance ? (
+        host
+      ) : (
+        <KeyboardAvoidingView behavior="padding">{host}</KeyboardAvoidingView>
+      )}
+    </>
+  );
+}
+
+export function AliaComposer<T extends AliaSuggestion = AliaSuggestion>({
+  labels,
+  ...props
+}: AliaComposerProps<T>) {
+  return (
+    <AliaChatLabelsProvider labels={labels}>
+      <AliaComposerBody {...props} />
+    </AliaChatLabelsProvider>
+  );
+}

package/src/components/ComposerDropZone.tsx

@@ -0,0 +1,235 @@
+import { dragCarriesFiles, nextDragDepth } from '../lib/attachment-intake';
+import { useLabels } from '../lib/labels';
+import { Text } from '@oxy.so/bloom/typography';
+import React from 'react';
+import { Platform, View } from 'react-native';
+/**
+ * Dropping files onto the composer, on web, where such a gesture exists.
+ *
+ * Alia had no drag-and-drop at all — no `onDrop`, no `dataTransfer`, nothing —
+ * which on web means the browser's own default ran instead: dropping a file
+ * anywhere on the page NAVIGATED THE TAB TO IT, losing the draft, the
+ * conversation scroll position and any stream in flight. So the first thing
+ * this does is not "accept files"; it is `preventDefault`, and it happens even
+ * when the composer is closed, because the least a locked composer owes a
+ * dropped file is not to throw the page away over it.
+ *
+ * ## Why the listeners are attached by hand
+ *
+ * `View` has no `onDragEnter`. react-native-web forwards a fixed set of
+ * handlers and the drag family is not in it, and NativeWind's wrapper means a
+ * ref here does not resolve to the DOM node either — the fullscreen grow in
+ * old composer ran into the same wall and solved it the same way, by giving
+ * the bar an `id` and looking it up. This hook takes that id, and the id now
+ * belongs to the `View` the composer wraps Bloom's pill in — Bloom's own pill
+ * takes a `style` and a `testID` and no DOM handle at all, which is the right
+ * shape for a UI kit and leaves the drop target to its host.
+ */
+export interface ComposerDropTargetOptions {
+  /** The DOM id of the element the drop lands on — the composer bar itself. */
+  elementId: string;
+  /** False while the composer is closed or a turn is streaming. */
+  enabled: boolean;
+  onFiles: (files: File[]) => void;
+  /**
+   * Changing this re-attaches the listeners. Fullscreen re-parents the bar
+   * through a portal, which destroys the node the listeners were on; without a
+   * rebind the composer silently stops taking drops the first time it is
+   * expanded.
+   */
+  rebindKey?: string | number;
+}
+
+/** Whether a file drag is currently over the composer. */
+export function useComposerDropTarget({
+  elementId,
+  enabled,
+  onFiles,
+  rebindKey,
+}: ComposerDropTargetOptions): boolean {
+  const [isOver, setIsOver] = React.useState(false);
+
+  /**
+   * How many of the bar's elements the pointer is inside.
+   *
+   * A ref, and read in the same tick it is written: `dragenter` on a child
+   * arrives immediately before `dragleave` on its parent, so the two have to
+   * be counted against each other synchronously. State would be one render
+   * stale for the pair that matters, which is every pair.
+   */
+  const depth = React.useRef(0);
+
+  // Held in a ref so the effect does not re-attach — and re-attaching matters:
+  // a listener swapped out mid-drag loses the depth count with it, and the
+  // overlay never clears.
+  const latest = React.useRef({ enabled, onFiles });
+  latest.current = { enabled, onFiles };
+
+  React.useEffect(() => {
+    if (Platform.OS !== 'web' || typeof document === 'undefined') return;
+    const element = document.getElementById(elementId);
+    if (element === null) return;
+
+    const step = (kind: 'enter' | 'leave' | 'drop') => {
+      depth.current = nextDragDepth(depth.current, kind);
+      setIsOver(depth.current > 0);
+    };
+
+    const onDragEnter = (event: globalThis.DragEvent) => {
+      if (!dragCarriesFiles(event.dataTransfer?.types)) return;
+      event.preventDefault();
+      step('enter');
+    };
+
+    const onDragOver = (event: globalThis.DragEvent) => {
+      if (!dragCarriesFiles(event.dataTransfer?.types)) return;
+      // Both halves are required. Without `preventDefault` on dragOVER
+      // specifically — not just on enter — the element is not a drop target at
+      // all and `drop` never fires, which is the single most common way a
+      // hand-written drop zone appears to work and then does nothing.
+      event.preventDefault();
+      if (event.dataTransfer !== null)
+        event.dataTransfer.dropEffect = latest.current.enabled ? 'copy' : 'none';
+    };
+
+    const onDragLeave = (event: globalThis.DragEvent) => {
+      if (!dragCarriesFiles(event.dataTransfer?.types)) return;
+      step('leave');
+    };
+
+    const onDrop = (event: globalThis.DragEvent) => {
+      if (!dragCarriesFiles(event.dataTransfer?.types)) return;
+      event.preventDefault();
+      // Reset rather than decrement: no `dragleave` follows a drop, so a
+      // decrement leaves the count at one and the overlay stuck over the bar.
+      step('drop');
+      if (!latest.current.enabled) return;
+      const files = Array.from(event.dataTransfer?.files ?? []);
+      if (files.length > 0) latest.current.onFiles(files);
+    };
+
+    element.addEventListener('dragenter', onDragEnter);
+    element.addEventListener('dragover', onDragOver);
+    element.addEventListener('dragleave', onDragLeave);
+    element.addEventListener('drop', onDrop);
+    return () => {
+      element.removeEventListener('dragenter', onDragEnter);
+      element.removeEventListener('dragover', onDragOver);
+      element.removeEventListener('dragleave', onDragLeave);
+      element.removeEventListener('drop', onDrop);
+      // A drag that was over the bar when it was torn down would otherwise
+      // leave the count — and the overlay — set for the next mount.
+      depth.current = 0;
+      setIsOver(false);
+    };
+  }, [elementId, rebindKey]);
+
+  return isOver;
+}
+
+/**
+ * What a file drag looks like over the composer.
+ *
+ * `pointerEvents="none"` is load-bearing rather than tidy: an overlay that
+ * takes pointer events is an element the drag ENTERS, so it would fire its own
+ * `dragenter`/`dragleave` pair against the same counter it is drawn from, and
+ * the affordance would oscillate against itself.
+ *
+ * It is announced as well as drawn. A drop target that exists only as a
+ * dashed outline is a target only for the people who can see it, and while a
+ * drag is not a gesture a screen-reader user performs, the composer is shared
+ * with people who do both.
+ */
+export function ComposerDropOverlay({ visible, enabled }: { visible: boolean; enabled: boolean }) {
+  const labels = useLabels();
+  if (!visible) return null;
+  return (
+    <View
+      pointerEvents="none"
+      accessibilityRole="alert"
+      accessibilityLiveRegion="polite"
+      // 26: the corner Bloom's composer pill wears at one line and past it.
+      className="absolute inset-0 z-20 items-center justify-center rounded-[26px] border-2 border-dashed border-primary bg-background/90"
+    >
+      <Text className="text-sm font-medium text-foreground">
+        {enabled ? labels.dropHint : labels.dropUnavailable}
+      </Text>
+    </View>
+  );
+}
+
+/**
+ * Files PASTED into the composer, on web, where such a gesture exists.
+ *
+ * It lives beside the drop target rather than with the field because it is the
+ * same question asked with a different gesture: bytes have arrived, they were
+ * not typed, and the composer has to decide whether to take them. Both are
+ * hand-attached DOM listeners for the same reason — react-native-web forwards
+ * neither the drag family nor `onPaste` through `View`, and NativeWind's
+ * wrapper means a ref does not resolve to the node either — so both are keyed
+ * off the composer's own DOM id.
+ *
+ * ## Why it is on the composer and not on the field
+ *
+ * `ChatTextInput` used to own this, listening on `document` and checking that
+ * the focused element was inside ITS wrapper. Bloom's pill owns the field now
+ * and exposes no DOM handle for it, so the containment test moves out one ring,
+ * to the element the pill is mounted inside. That is the same test with a
+ * larger box: a paste belongs to this composer when the thing being pasted
+ * into is somewhere in this composer.
+ *
+ * ## Why it takes every file and not only images
+ *
+ * The old handler filtered `item.type.indexOf('image')`, so pasting a PDF
+ * pasted its NAME. The intake queue classifies and refuses on its own terms
+ * (`lib/attachment-intake.ts`) and says so in the strip, which is a better
+ * answer than a silent drop — and it is the same answer a dropped PDF already
+ * got, which is the point: one queue, one set of rules, whichever gesture the
+ * file arrived by.
+ */
+export function useComposerPasteTarget({
+  elementId,
+  enabled,
+  onFiles,
+}: Omit<ComposerDropTargetOptions, 'rebindKey'>): void {
+  // Held in a ref for the same reason the drop target holds its own: a
+  // listener swapped out mid-gesture is a gesture with no handler.
+  const latest = React.useRef({ enabled, onFiles });
+  latest.current = { enabled, onFiles };
+
+  React.useEffect(() => {
+    if (Platform.OS !== 'web' || typeof document === 'undefined') return;
+
+    const onPaste = (event: globalThis.ClipboardEvent) => {
+      // Resolved per EVENT rather than once per mount, which is also why this
+      // hook needs no `rebindKey`: the pill re-renders its own subtree as the
+      // draft grows, and a node captured at mount is a node the composer may
+      // since have replaced.
+      const host = document.getElementById(elementId);
+      if (!(host instanceof HTMLElement)) return;
+      if (!host.contains(document.activeElement)) return;
+
+      const items = event.clipboardData?.items;
+      if (items === undefined) return;
+      const files: File[] = [];
+      for (const item of Array.from(items)) {
+        if (item.kind !== 'file') continue;
+        const file = item.getAsFile();
+        if (file !== null) files.push(file);
+      }
+      // Nothing was pasted that this is about. A paste carrying text as well
+      // as a picture — which is what copying from a web page produces — must
+      // still put its text in the field, so the default is left alone.
+      if (files.length === 0) return;
+
+      // Swallowed even when the composer is closed: the alternative is the
+      // browser's own default, which writes the file's bytes into the draft.
+      event.preventDefault();
+      if (!latest.current.enabled) return;
+      latest.current.onFiles(files);
+    };
+
+    document.addEventListener('paste', onPaste);
+    return () => document.removeEventListener('paste', onPaste);
+  }, [elementId]);
+}