@refraction-ui/astro 0.15.2 → 0.16.0

package/dist/composer/types.ts

@@ -0,0 +1,337 @@
+/**
+ * Public types for the headless chat composer core.
+ *
+ * The composer models a single growing message buffer (flat string + selection)
+ * with inline triggers (@mention, /command, :emoji:, #tag, custom), committed
+ * atomic tokens, staged attachments, and one optimistic submit. Framework
+ * adapters (React/Astro/Flutter) wrap this contract without re-implementing
+ * any behavior.
+ */
+
+import type { MessageAttachment } from '../conversation/index.ts'
+
+// ---------------------------------------------------------------------------
+// Triggers & suggestions
+// ---------------------------------------------------------------------------
+
+/** Where a trigger symbol is allowed to arm. */
+export type ComposerTriggerScope = 'anywhere' | 'startOfLine' | 'startOfMessage'
+
+/** A candidate shown in the suggestion menu for an armed trigger. */
+export interface ComposerCandidate {
+  id: string
+  display: string
+  subtitle?: string
+  metadata?: Record<string, unknown>
+}
+
+export type ComposerTriggerResolver = (
+  query: string,
+) => ComposerCandidate[] | Promise<ComposerCandidate[]>
+
+/**
+ * A trigger is configuration, not code — the engine is symbol-agnostic and
+ * never special-cases '@' / '/' / ':' in control flow.
+ */
+export interface ComposerTrigger {
+  id: string
+  /** Trigger symbol; any length ('@', '/', '#', '!!'). */
+  symbol: string
+  /** Default 'anywhere'. Slash-style commands use 'startOfMessage'. */
+  scope?: ComposerTriggerScope
+  /** Extra validation for the query; a violating query closes the trigger. */
+  queryPattern?: RegExp
+  /** Queries longer than this silently cancel the trigger. Default 40. */
+  maxQueryLength?: number
+  /** Default true. '#'-style triggers set false so '#weekend trip' stays armed. */
+  closeOnSpace?: boolean
+  /** Default false. Trades away email/URL protection — must be justified. */
+  allowMidWord?: boolean
+  /** Additional boundary characters allowed before the symbol (e.g. '(' or '"'). */
+  extraBoundaryChars?: string[]
+  /** Resolver debounce in ms. Default 0 (sync/local resolvers). */
+  debounceMs?: number
+  /** Visible slice size for the adapter's menu. Default 6. */
+  maxVisibleResults?: number
+  /** Whether ArrowUp/Down wrap around the ends. Default true. */
+  wrapNavigation?: boolean
+  /**
+   * Builds the committed token's display text. Defaults to `symbol + display`
+   * ('@Jordan Lee'); the emoji recipe returns the unicode itself.
+   */
+  toDisplay?: (candidate: ComposerCandidate) => string
+  resolve: ComposerTriggerResolver
+}
+
+/** A committed, atomic inline unit (identity + frozen display). */
+export interface ComposerToken {
+  triggerId: string
+  symbol: string
+  id: string
+  label: string
+  display: string
+  metadata?: Record<string, unknown>
+}
+
+/** A token placed in the value, with its live UTF-16 range. */
+export interface PlacedToken extends ComposerToken {
+  start: number
+  end: number
+}
+
+/** Structured output token with derived UTF-16 offsets into plainText. */
+export interface ResolvedToken {
+  type: string
+  id: string
+  display: string
+  start: number
+  end: number
+}
+
+// ---------------------------------------------------------------------------
+// Attachments
+// ---------------------------------------------------------------------------
+
+export type ComposerAttachmentKind = 'text' | 'image' | 'video' | 'audio' | 'file'
+export type ComposerAttachmentStatus = 'pending' | 'uploading' | 'ready' | 'error'
+
+export interface ComposerAttachment {
+  id: string
+  kind: ComposerAttachmentKind
+  name: string
+  mimeType?: string
+  sizeBytes?: number
+  previewUrl?: string
+  status: ComposerAttachmentStatus
+  /** 0..1 while uploading. */
+  progress?: number
+  errorMessage?: string
+  metadata?: Record<string, unknown>
+}
+
+/** Input to `addAttachment` — id/status are core-owned defaults. */
+export type ComposerAttachmentDraft = Omit<ComposerAttachment, 'id' | 'status'> & {
+  id?: string
+  status?: ComposerAttachmentStatus
+}
+
+// ---------------------------------------------------------------------------
+// Submission & serialization
+// ---------------------------------------------------------------------------
+
+export interface ComposerSubmission {
+  /** Trimmed message text with token displays inlined. */
+  plainText: string
+  tokens: ResolvedToken[]
+  attachments: ComposerAttachment[]
+  replyToMessageId?: string
+  /** Present when submitting from edit mode. */
+  editingMessageId?: string
+}
+
+export interface ComposerOutput {
+  plainText: string
+  tokens: ResolvedToken[]
+}
+
+// ---------------------------------------------------------------------------
+// State
+// ---------------------------------------------------------------------------
+
+export interface ComposerSelection {
+  start: number
+  end: number
+}
+
+export interface ActiveTriggerState {
+  triggerId: string
+  symbol: string
+  symbolStart: number
+  caret: number
+  query: string
+}
+
+export interface SuggestionState {
+  isOpen: boolean
+  /** Full result list (overflow intact). */
+  items: ComposerCandidate[]
+  /** `items` sliced to the trigger's maxVisibleResults for the adapter. */
+  visibleItems: ComposerCandidate[]
+  activeIndex: number
+  loading: boolean
+  error: string | null
+  /** Monotonic id of the latest resolve request (staleness guard). */
+  requestToken: number
+}
+
+export interface CounterState {
+  /** Visible once remaining budget is within 20% of maxLength. */
+  visible: boolean
+  /** Remaining grapheme budget; null without a maxLength. */
+  remaining: number | null
+  overLimit: boolean
+}
+
+export type ComposerMode = 'compose' | 'edit'
+
+export interface ComposerState {
+  value: string
+  selection: ComposerSelection
+  isComposing: boolean
+  isBusy: boolean
+  disabled: boolean
+  readOnly: boolean
+  isEmpty: boolean
+  canSend: boolean
+  error: string | null
+  attachments: ComposerAttachment[]
+  tokens: PlacedToken[]
+  activeTrigger: ActiveTriggerState | null
+  suggestion: SuggestionState
+  counter: CounterState
+  mode: ComposerMode
+  editingMessageId?: string
+}
+
+// ---------------------------------------------------------------------------
+// Validation, drafts, events, config
+// ---------------------------------------------------------------------------
+
+export interface ComposerValidationResult {
+  isValid: boolean
+  reason?: string
+}
+
+export type ComposerValidator = (
+  plainText: string,
+  tokens: ResolvedToken[],
+) => ComposerValidationResult
+
+/** Persisted draft snapshot (attachments by id only — blobs are host-owned). */
+export interface ComposerDraft {
+  value: string
+  tokens: PlacedToken[]
+  attachmentIds: string[]
+  updatedAt: number
+}
+
+/** Injected persistence seam; the core ships only an in-memory default. */
+export interface ComposerDraftStore {
+  read(key: string): ComposerDraft | null
+  write(key: string, draft: ComposerDraft): void
+  clear(key: string): void
+}
+
+export type ComposerEvent =
+  | { type: 'paste-trimmed' }
+  | { type: 'insert-rejected'; reason: 'max-length' | 'composing' | 'disabled' | 'read-only' }
+  | { type: 'edit-rejected'; reason: 'inside-token' }
+  | { type: 'attachment-rejected'; reason: 'max-attachments' | 'max-size' | 'not-accepted'; name: string; detail?: string }
+  | { type: 'typing' }
+
+export interface ComposerConfig {
+  initialValue?: string
+  /** Tokens present in initialValue (e.g. when re-opening a draft the host owns). */
+  initialTokens?: PlacedToken[]
+  /** Grapheme-cluster budget (not UTF-16 units). */
+  maxLength?: number
+  maxAttachments?: number
+  /** Per-attachment size gate; larger drafts are rejected with an event. */
+  maxAttachmentSizeBytes?: number
+  /** Predicate gate; return false or a reason string to reject a draft. */
+  acceptAttachment?: (draft: ComposerAttachmentDraft) => boolean | string
+  minLines?: number
+  maxLines?: number
+  triggers?: ComposerTrigger[]
+  validator?: ComposerValidator
+  draftStore?: ComposerDraftStore
+  draftKey?: string
+  /** Draft autosave debounce. Default 400ms. */
+  draftDebounceMs?: number
+  /** Leading-edge throttle for the 'typing' event. Default 3000ms. */
+  typingSignalIntervalMs?: number
+  replyToMessageId?: string
+  /** Injected clock — the core never calls Date.now() in logic paths. */
+  now?: () => number
+  /** Injected id factory — the core never calls Math.random(). */
+  generateId?: (prefix?: string) => string
+  /** Notice channel ('paste-trimmed', 'attachment-rejected', 'typing', …). */
+  onEvent?: (event: ComposerEvent) => void
+}
+
+// ---------------------------------------------------------------------------
+// API
+// ---------------------------------------------------------------------------
+
+/** Outcome of a physical Enter press routed through the core. */
+export type EnterResult = 'submitted' | 'newline' | 'committed-suggestion' | 'noop'
+
+export interface ComposerAPI {
+  getState(): ComposerState
+  subscribe(listener: (state: ComposerState) => void): () => void
+
+  /**
+   * The adapter's input path: full new text + selection after a user edit.
+   * Pass `{ programmatic: true }` for host-driven writes (suppresses the
+   * typing signal).
+   */
+  setValue(text: string, selection?: ComposerSelection, opts?: { programmatic?: boolean }): void
+  /** Caret/selection move without a text change (allowed while readOnly). */
+  setSelection(selection: ComposerSelection): void
+  insertTextAtCursor(text: string): void
+  setComposing(isComposing: boolean): void
+
+  /** Routes a physical Enter; the return value tells the adapter whether to preventDefault. */
+  applyEnter(opts: { shiftPressed: boolean }): EnterResult
+
+  moveSuggestionNext(): void
+  moveSuggestionPrevious(): void
+  /** Pointer hover — last-input-wins with the keyboard. */
+  setSuggestionActiveIndex(index: number): void
+  applySuggestion(index?: number): void
+  /** Escape-style dismissal: closes now and marks the occurrence dismissed. */
+  dismissSuggestion(): void
+  /** Blur-style dismissal: closes after a short grace so a click can land. */
+  dismissSuggestionDeferred(): void
+  retrySuggestions(): void
+
+  addAttachment(draft: ComposerAttachmentDraft): string | null
+  updateAttachment(id: string, patch: Partial<Omit<ComposerAttachment, 'id'>>): void
+  removeAttachment(id: string): void
+
+  setBusy(busy: boolean): void
+  setError(error: string | null): void
+  setDisabled(disabled: boolean): void
+  setReadOnly(readOnly: boolean): void
+
+  beginEdit(args: { value: string; tokens?: PlacedToken[]; messageId: string }): void
+  cancelEdit(): void
+
+  /** Clipboard seam: returns the selected display text. */
+  copySelection(): string
+  /** Clipboard seam: removes the selection, retaining token identity for same-instance paste. */
+  cutSelection(): string
+  /** Clipboard seam: plain-text insert at caret (clamped); restores tokens only for a same-instance cut. */
+  pasteText(text: string): void
+
+  submit(): ComposerSubmission | null
+  reset(): void
+  serialize(): ComposerOutput
+  destroy(): void
+}
+
+/**
+ * Bridge to the conversation layer: a ready composer attachment mapped onto
+ * `@refraction-ui/conversation`'s wire shape.
+ */
+export function toMessageAttachment(attachment: ComposerAttachment): MessageAttachment {
+  return {
+    id: attachment.id,
+    name: attachment.name,
+    url: attachment.previewUrl ?? '',
+    type: attachment.mimeType ?? attachment.kind,
+    size: attachment.sizeBytes,
+  }
+}
+
+export type { MessageAttachment }

package/dist/index.ts

@@ -30,6 +30,7 @@ export * from './astro-code-editor/index.ts';
 export * from './astro-collapsible/index.ts';
 export * from './astro-command/index.ts';
 export * from './astro-command-input/index.ts';
+export * from './astro-composer/index.ts';
 export * from './astro-content-protection/index.ts';
 export * from './astro-conversation/index.ts';
 export * from './astro-cookie-consent/index.ts';

package/dist/rich-editor/index.ts

@@ -83,6 +83,10 @@ export {
 // Markdown shortcuts
 export { processMarkdownShortcut } from './markdown-shortcuts.js'
 
+// Trigger detection (generalized — mentions/slash delegate to this)
+export type { TriggerHit } from './trigger.js'
+export { detectTriggerInText } from './trigger.js'
+
 // Slash commands
 export type { SlashCommand, SlashCommandMenu } from './slash-commands.js'
 export { BUILT_IN_COMMANDS, createSlashCommandMenu, detectSlashTrigger } from './slash-commands.js'

package/dist/rich-editor/mentions.ts

@@ -6,6 +6,7 @@ import type { Document } from './model.js'
 import type { Selection } from './selection.js'
 import type { MentionSegment } from './model.js'
 import { findBlockById, getBlockText, createMentionSegment } from './model.js'
+import { detectTriggerInText } from './trigger.js'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -142,21 +143,6 @@ export function detectMentionTrigger(
   const block = findBlockById(doc, sel.anchor.blockId)
   if (!block) return { triggered: false, query: '' }
 
-  const text = getBlockText(block)
-  const textBeforeCursor = text.slice(0, sel.anchor.offset)
-
-  // Look for "@" preceded by start-of-text or a space
-  const atIdx = textBeforeCursor.lastIndexOf('@')
-  if (atIdx === -1) return { triggered: false, query: '' }
-
-  // The @ must be at position 0 or preceded by a space
-  if (atIdx > 0 && textBeforeCursor[atIdx - 1] !== ' ') {
-    return { triggered: false, query: '' }
-  }
-
-  const query = textBeforeCursor.slice(atIdx + 1)
-  // If query contains spaces, the mention trigger is no longer active
-  if (query.includes(' ')) return { triggered: false, query: '' }
-
-  return { triggered: true, query }
+  const hit = detectTriggerInText(getBlockText(block), sel.anchor.offset, '@')
+  return hit ? { triggered: true, query: hit.query } : { triggered: false, query: '' }
 }

package/dist/rich-editor/slash-commands.ts

@@ -10,6 +10,7 @@ import type { EditorState } from './operations.js'
 import { changeBlockType, insertBlock, deleteSelection } from './operations.js'
 import { createCollapsedSelection, createSelection, createPosition } from './selection.js'
 import { findBlockById, getBlockText, cloneDocument, createTextSegment } from './model.js'
+import { detectTriggerInText } from './trigger.js'
 
 // ---------------------------------------------------------------------------
 // Types
@@ -192,21 +193,6 @@ export function detectSlashTrigger(
   const block = findBlockById(doc, sel.anchor.blockId)
   if (!block) return { triggered: false, query: '' }
 
-  const text = getBlockText(block)
-  const textBeforeCursor = text.slice(0, sel.anchor.offset)
-
-  // Look for "/" preceded by start-of-text or a space
-  const slashIdx = textBeforeCursor.lastIndexOf('/')
-  if (slashIdx === -1) return { triggered: false, query: '' }
-
-  // The slash must be at position 0 or preceded by a space
-  if (slashIdx > 0 && textBeforeCursor[slashIdx - 1] !== ' ') {
-    return { triggered: false, query: '' }
-  }
-
-  const query = textBeforeCursor.slice(slashIdx + 1)
-  // If query contains spaces, the slash command is no longer active
-  if (query.includes(' ')) return { triggered: false, query: '' }
-
-  return { triggered: true, query }
+  const hit = detectTriggerInText(getBlockText(block), sel.anchor.offset, '/')
+  return hit ? { triggered: true, query: hit.query } : { triggered: false, query: '' }
 }

package/dist/rich-editor/trigger.ts

@@ -0,0 +1,40 @@
+/**
+ * Generalized trigger detection shared by mentions, slash commands, and any
+ * symbol-prefixed autocomplete (e.g. the composer's trigger engine).
+ *
+ * One implementation exists so the boundary rules ("alice@example.com" never
+ * triggers, a query never spans whitespace) cannot drift between features.
+ */
+
+export interface TriggerHit {
+  triggered: boolean
+  query: string
+  /** Index of the trigger symbol's first character in `text`. */
+  start: number
+}
+
+/**
+ * Scan backward from `caret` for the nearest occurrence of `triggerChar` that
+ * is preceded by start-of-text or whitespace and followed by a whitespace-free
+ * query running up to the caret. Returns `null` when no live trigger exists.
+ *
+ * `triggerChar` may be longer than one character (e.g. `!!`); the boundary is
+ * checked against the character before its first character.
+ */
+export function detectTriggerInText(
+  text: string,
+  caret: number,
+  triggerChar: string,
+): TriggerHit | null {
+  if (triggerChar.length === 0) return null
+  const before = text.slice(0, caret)
+  const idx = before.lastIndexOf(triggerChar)
+  if (idx === -1) return null
+  // Boundary rule: only start-of-text or whitespace may precede the symbol,
+  // so mid-word occurrences (emails, "and/or") never arm.
+  if (idx > 0 && !/\s/.test(before[idx - 1])) return null
+  const query = before.slice(idx + triggerChar.length)
+  // A query never spans whitespace — a space closes the trigger.
+  if (/\s/.test(query)) return null
+  return { triggered: true, query, start: idx }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@refraction-ui/astro",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "All Refraction UI Astro components in one package",
   "type": "module",
   "exports": {
@@ -50,6 +50,7 @@
     "@refraction-ui/astro-collapsible": "workspace:*",
     "@refraction-ui/astro-command": "workspace:*",
     "@refraction-ui/astro-command-input": "workspace:*",
+    "@refraction-ui/astro-composer": "workspace:*",
     "@refraction-ui/astro-content-protection": "workspace:*",
     "@refraction-ui/astro-conversation": "workspace:*",
     "@refraction-ui/astro-cookie-consent": "workspace:*",