@refraction-ui/astro 0.15.2 → 0.16.0

package/dist/composer/graphemes.ts

@@ -0,0 +1,92 @@
+/**
+ * Grapheme-cluster utilities.
+ *
+ * Length limits and clamping must never bisect a user-perceived character —
+ * a 👨‍👩‍👧‍👦 ZWJ family emoji is 11 UTF-16 units but one cluster. We use
+ * `Intl.Segmenter` when available; the fallback treats each code point as a
+ * cluster (coarser, but it never splits a surrogate pair).
+ */
+
+type GraphemeSegmenter = { segment(input: string): Iterable<{ segment: string; index: number }> }
+
+let cachedSegmenter: GraphemeSegmenter | null | undefined
+
+function getSegmenter(): GraphemeSegmenter | null {
+  if (cachedSegmenter === undefined) {
+    // Feature-detect once; Intl is the only global the module touches.
+    const IntlAny = typeof Intl !== 'undefined' ? (Intl as unknown as Record<string, unknown>) : undefined
+    const Segmenter = IntlAny?.Segmenter as
+      | (new (locale: undefined, opts: { granularity: 'grapheme' }) => GraphemeSegmenter)
+      | undefined
+    cachedSegmenter = Segmenter ? new Segmenter(undefined, { granularity: 'grapheme' }) : null
+  }
+  return cachedSegmenter
+}
+
+function isHighSurrogate(code: number): boolean {
+  return code >= 0xd800 && code <= 0xdbff
+}
+
+function isLowSurrogate(code: number): boolean {
+  return code >= 0xdc00 && code <= 0xdfff
+}
+
+/** Count of grapheme clusters (code points in the fallback), never UTF-16 units. */
+export function graphemeLength(text: string): number {
+  if (text === '') return 0
+  const segmenter = getSegmenter()
+  if (segmenter) {
+    let count = 0
+    for (const _ of segmenter.segment(text)) count++
+    return count
+  }
+  // Fallback: code points (surrogate pairs count once).
+  let count = 0
+  for (const _ of text) count++
+  return count
+}
+
+/**
+ * Clamp `text` to at most `max` grapheme clusters. A cluster that would cross
+ * the limit is rejected whole — the result is always a valid cluster boundary.
+ */
+export function clampGraphemes(text: string, max: number): string {
+  if (max <= 0) return ''
+  const segmenter = getSegmenter()
+  if (segmenter) {
+    let count = 0
+    let endIndex = text.length
+    for (const part of segmenter.segment(text)) {
+      count++
+      if (count > max) {
+        endIndex = part.index
+        break
+      }
+    }
+    return text.slice(0, endIndex)
+  }
+  // Fallback: walk code points, never splitting a surrogate pair.
+  let count = 0
+  let i = 0
+  while (i < text.length && count < max) {
+    const code = text.charCodeAt(i)
+    i += isHighSurrogate(code) && i + 1 < text.length && isLowSurrogate(text.charCodeAt(i + 1)) ? 2 : 1
+    count++
+  }
+  return text.slice(0, i)
+}
+
+/** Whether `offset` sits on a grapheme-cluster boundary of `text`. */
+export function isGraphemeBoundary(text: string, offset: number): boolean {
+  if (offset <= 0 || offset >= text.length) return true
+  const segmenter = getSegmenter()
+  if (segmenter) {
+    for (const part of segmenter.segment(text)) {
+      if (part.index === offset) return true
+      if (part.index > offset) return false
+    }
+    return false
+  }
+  // Fallback: only reject offsets that split a surrogate pair.
+  return !(isLowSurrogate(text.charCodeAt(offset)) && isHighSurrogate(text.charCodeAt(offset - 1)))
+}

package/dist/composer/index.ts

@@ -0,0 +1,8 @@
+export * from './types.ts'
+export * from './graphemes.ts'
+export * from './rules.ts'
+export * from './trigger-engine.ts'
+export * from './suggestion.ts'
+export * from './tokens.ts'
+export * from './composer.ts'
+export * from './styles.ts'

package/dist/composer/rules.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure composer rules — the single source of truth shared by the enable-check,
+ * the Enter handler, and the submitted payload (so they can never disagree).
+ */
+
+import { graphemeLength } from './graphemes.js'
+import type { CounterState } from './types.js'
+
+/** One trim shared by the enable-check AND the sent payload. */
+export function payloadFor(raw: string): string {
+  return raw.trim()
+}
+
+export interface CanSendArgs {
+  text: string
+  attachments?: readonly unknown[]
+  disabled?: boolean
+  readOnly?: boolean
+  busy?: boolean
+}
+
+/**
+ * Send is derived from BOTH trimmed text and attachments — an attachments-only
+ * message is valid; a whitespace-only message never is.
+ */
+export function canSend({ text, attachments = [], disabled = false, readOnly = false, busy = false }: CanSendArgs): boolean {
+  if (disabled || readOnly || busy) return false
+  return payloadFor(text).length > 0 || attachments.length > 0
+}
+
+/**
+ * The platform-matrix resolver: physical Enter sends unless Shift is held or
+ * an IME composition is active (composing always wins — Enter confirms the
+ * candidate, never submits).
+ */
+export function shouldSubmitOnEnter({
+  shiftPressed,
+  isComposing,
+}: {
+  shiftPressed: boolean
+  isComposing: boolean
+}): boolean {
+  return !shiftPressed && !isComposing
+}
+
+/** The counter surfaces once remaining budget is within this fraction of maxLength. */
+export const COUNTER_VISIBLE_FRACTION = 0.2
+
+/**
+ * Counter math over grapheme budget. The counter is confirmatory, not the
+ * enforcement mechanism (clamping at the insert boundary prevents overflow).
+ */
+export function computeCounter(text: string, maxLength: number | undefined): CounterState {
+  if (maxLength === undefined) {
+    return { visible: false, remaining: null, overLimit: false }
+  }
+  const remaining = maxLength - graphemeLength(text)
+  return {
+    visible: remaining <= maxLength * COUNTER_VISIBLE_FRACTION,
+    remaining,
+    overLimit: remaining <= 0,
+  }
+}

package/dist/composer/styles.ts

@@ -0,0 +1,102 @@
+/**
+ * cva style variants for the composer surface, pill, tray, and menu.
+ * Boolean-ish variants use string 'true'/'false' keys per repo convention
+ * (raw booleans fail the dts build).
+ */
+
+import { cva } from '../shared/index.ts'
+
+/** Outer surface (the rounded card wrapping tray + field + action row). */
+export const composerSurfaceVariants = cva({
+  base: [
+    'overflow-hidden rounded-2xl border border-border bg-background shadow-sm',
+    'transition-shadow focus-within:border-foreground/25 focus-within:shadow-md',
+  ].join(' '),
+  variants: {
+    disabled: {
+      true: 'pointer-events-none opacity-60',
+      false: '',
+    },
+    error: {
+      true: 'border-destructive/50',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    disabled: 'false',
+    error: 'false',
+  },
+})
+
+/** The text field itself (borderless inside the surface). */
+export const composerFieldClass =
+  'block w-full resize-none bg-transparent px-3.5 py-3 text-sm placeholder:text-muted-foreground focus:outline-none'
+
+/** Attachment tray above the field, inside the dock. */
+export const composerTrayClass = 'flex flex-wrap gap-2 px-3 pt-3'
+
+/** A single attachment chip. */
+export const composerAttachmentChipVariants = cva({
+  base: 'inline-flex items-center gap-1 rounded-md bg-muted px-2 py-0.5 text-xs',
+  variants: {
+    status: {
+      pending: 'opacity-70',
+      uploading: 'opacity-70',
+      ready: '',
+      error: 'text-destructive',
+    },
+  },
+  defaultVariants: {
+    status: 'pending',
+  },
+})
+
+/** A committed inline token pill rendered by adapters over the flat string. */
+export const composerTokenPillClass =
+  'rounded bg-accent/40 px-0.5 text-accent-foreground'
+
+/** The caret-anchored suggestion menu. */
+export const composerMenuClass =
+  'z-20 w-72 overflow-hidden rounded-xl border border-border bg-popover shadow-lg'
+
+/** A suggestion row; `active` follows keyboard/pointer last-input-wins. */
+export const composerMenuItemVariants = cva({
+  base: 'flex w-full items-center gap-2 px-3 py-2 text-left text-sm',
+  variants: {
+    active: {
+      true: 'bg-accent',
+      false: 'hover:bg-accent/50',
+    },
+  },
+  defaultVariants: {
+    active: 'false',
+  },
+})
+
+/** Character counter; switches to the attention treatment at/over the limit. */
+export const composerCounterVariants = cva({
+  base: 'text-xs tabular-nums',
+  variants: {
+    overLimit: {
+      true: 'font-medium text-destructive',
+      false: 'text-muted-foreground',
+    },
+  },
+  defaultVariants: {
+    overLimit: 'false',
+  },
+})
+
+/** Primary action (send ⇄ stop swap driven by `{hasText, canSend, isBusy}`). */
+export const composerPrimaryActionVariants = cva({
+  base: 'flex h-9 w-9 items-center justify-center rounded-full transition',
+  variants: {
+    enabled: {
+      true: 'bg-primary text-primary-foreground hover:opacity-90',
+      false: 'bg-muted text-muted-foreground',
+    },
+  },
+  defaultVariants: {
+    enabled: 'false',
+  },
+})

package/dist/composer/suggestion.ts

@@ -0,0 +1,261 @@
+/**
+ * Suggestion menu state (R13, R14): debounced async resolution with a
+ * monotonic requestToken staleness guard, delayed loading state, empty/error
+ * states with retry, a per-trigger circuit breaker, and keyboard navigation.
+ *
+ * Timers are plain setTimeout/clearTimeout — cancelable and deterministic
+ * under vitest fake timers; the controller never touches DOM globals.
+ */
+
+import type { ComposerCandidate, SuggestionState } from './types.js'
+import type { TriggerMatch } from './trigger-engine.js'
+
+/** Loading UI appears only if the resolver is still pending after this long. */
+export const LOADING_DELAY_MS = 120
+/** Deferred (blur) dismissal grace so a pointer tap on a row can land first. */
+export const DISMISS_GRACE_MS = 120
+/** Consecutive resolver throws for one trigger before remote calls stop for the session. */
+export const CIRCUIT_BREAKER_THRESHOLD = 2
+
+export const CLOSED_SUGGESTION_STATE: SuggestionState = {
+  isOpen: false,
+  items: [],
+  visibleItems: [],
+  activeIndex: 0,
+  loading: false,
+  error: null,
+  requestToken: 0,
+}
+
+export interface SuggestionController {
+  readonly state: SuggestionState
+  /** Reconcile with the current trigger match after any mutation/caret move. */
+  sync(match: TriggerMatch | null): void
+  moveNext(): void
+  movePrevious(): void
+  setActiveIndex(index: number): void
+  retry(): void
+  /** Close after a grace period (blur); a commit during the grace cancels it. */
+  dismissDeferred(onClosed: () => void): void
+  cancelDeferredDismiss(): void
+  /** Close immediately and invalidate any in-flight resolution. */
+  close(): void
+  isTripped(triggerId: string): boolean
+  destroy(): void
+}
+
+export function createSuggestionController({ emit }: { emit: () => void }): SuggestionController {
+  let state: SuggestionState = CLOSED_SUGGESTION_STATE
+  let match: TriggerMatch | null = null
+  let requestCounter = 0
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null
+  let loadingTimer: ReturnType<typeof setTimeout> | null = null
+  let dismissTimer: ReturnType<typeof setTimeout> | null = null
+  const consecutiveFailures = new Map<string, number>()
+  const tripped = new Set<string>()
+
+  function clearTimer(timer: ReturnType<typeof setTimeout> | null): null {
+    if (timer !== null) clearTimeout(timer)
+    return null
+  }
+
+  function setState(patch: Partial<SuggestionState>): void {
+    state = { ...state, ...patch }
+  }
+
+  function sameOccurrence(a: TriggerMatch | null, b: TriggerMatch | null): boolean {
+    return (
+      a !== null &&
+      b !== null &&
+      a.trigger.id === b.trigger.id &&
+      a.symbolStart === b.symbolStart
+    )
+  }
+
+  function closeInternal(): void {
+    debounceTimer = clearTimer(debounceTimer)
+    loadingTimer = clearTimer(loadingTimer)
+    // Bumping the counter invalidates any in-flight resolution (D13).
+    requestCounter++
+    match = null
+    state = CLOSED_SUGGESTION_STATE
+  }
+
+  function applyResults(forMatch: TriggerMatch, items: ComposerCandidate[]): void {
+    loadingTimer = clearTimer(loadingTimer)
+    consecutiveFailures.set(forMatch.trigger.id, 0)
+    setState({
+      isOpen: true,
+      items,
+      visibleItems: items.slice(0, forMatch.trigger.maxVisibleResults),
+      activeIndex: 0,
+      loading: false,
+      error: null,
+    })
+  }
+
+  function applyFailure(forMatch: TriggerMatch, error: unknown): void {
+    loadingTimer = clearTimer(loadingTimer)
+    const triggerId = forMatch.trigger.id
+    const failures = (consecutiveFailures.get(triggerId) ?? 0) + 1
+    consecutiveFailures.set(triggerId, failures)
+    if (failures >= CIRCUIT_BREAKER_THRESHOLD) {
+      // Session fallback: stop resolving remotely, close silently (D6).
+      tripped.add(triggerId)
+      closeInternal()
+      return
+    }
+    setState({
+      isOpen: true,
+      items: [],
+      visibleItems: [],
+      loading: false,
+      error: error instanceof Error ? error.message : 'Failed to load suggestions',
+    })
+  }
+
+  /**
+   * `notifySync` — emit() after a synchronously-settled resolve. False when a
+   * composer mutation is already in flight (it emits once at the end); true
+   * when invoked from a timer, where nobody else will notify.
+   */
+  function dispatch(forMatch: TriggerMatch, notifySync: boolean): void {
+    const token = ++requestCounter
+    setState({ requestToken: token })
+    let result: ComposerCandidate[] | Promise<ComposerCandidate[]>
+    try {
+      result = forMatch.trigger.resolve(forMatch.query)
+    } catch (error) {
+      applyFailure(forMatch, error)
+      if (notifySync) emit()
+      return
+    }
+    if (Array.isArray(result)) {
+      applyResults(forMatch, result)
+      if (notifySync) emit()
+      return
+    }
+    // Async: show the loading state only if it is still pending after 120ms.
+    loadingTimer = clearTimer(loadingTimer)
+    loadingTimer = setTimeout(() => {
+      if (token !== requestCounter) return
+      setState({ isOpen: true, loading: true })
+      emit()
+    }, LOADING_DELAY_MS)
+    result.then(
+      (items) => {
+        // Staleness guard: a slow response must never overwrite a newer one,
+        // and results arriving after the trigger closed are ignored.
+        if (token !== requestCounter || !sameOccurrence(match, forMatch)) return
+        applyResults(forMatch, items)
+        emit()
+      },
+      (error) => {
+        if (token !== requestCounter || !sameOccurrence(match, forMatch)) return
+        applyFailure(forMatch, error)
+        emit()
+      },
+    )
+  }
+
+  function schedule(forMatch: TriggerMatch): void {
+    debounceTimer = clearTimer(debounceTimer)
+    if (forMatch.trigger.debounceMs <= 0) {
+      dispatch(forMatch, false)
+      return
+    }
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null
+      if (sameOccurrence(match, forMatch) && match?.query === forMatch.query) {
+        dispatch(forMatch, true)
+      }
+    }, forMatch.trigger.debounceMs)
+  }
+
+  return {
+    get state() {
+      return state
+    },
+
+    sync(next: TriggerMatch | null): void {
+      if (next === null) {
+        if (match !== null || state.isOpen) closeInternal()
+        return
+      }
+      if (tripped.has(next.trigger.id)) {
+        if (match !== null || state.isOpen) closeInternal()
+        return
+      }
+      const isSame = sameOccurrence(match, next)
+      const queryChanged = !isSame || match?.query !== next.query
+      match = next
+      if (!isSame) {
+        // Fresh occurrence: start from a clean open menu.
+        state = { ...CLOSED_SUGGESTION_STATE, isOpen: true, requestToken: state.requestToken }
+      }
+      if (queryChanged) schedule(next)
+    },
+
+    moveNext(): void {
+      const count = state.items.length
+      if (!state.isOpen || count === 0) return
+      const wrap = match?.trigger.wrapNavigation ?? true
+      const next = wrap
+        ? (state.activeIndex + 1) % count
+        : Math.min(state.activeIndex + 1, count - 1)
+      setState({ activeIndex: next })
+    },
+
+    movePrevious(): void {
+      const count = state.items.length
+      if (!state.isOpen || count === 0) return
+      const wrap = match?.trigger.wrapNavigation ?? true
+      const previous = wrap
+        ? (state.activeIndex - 1 + count) % count
+        : Math.max(state.activeIndex - 1, 0)
+      setState({ activeIndex: previous })
+    },
+
+    setActiveIndex(index: number): void {
+      if (!state.isOpen || state.items.length === 0) return
+      setState({ activeIndex: Math.max(0, Math.min(index, state.items.length - 1)) })
+    },
+
+    retry(): void {
+      if (match === null) return
+      if (tripped.has(match.trigger.id)) return
+      setState({ error: null })
+      dispatch(match, false)
+    },
+
+    dismissDeferred(onClosed: () => void): void {
+      dismissTimer = clearTimer(dismissTimer)
+      dismissTimer = setTimeout(() => {
+        dismissTimer = null
+        closeInternal()
+        onClosed()
+      }, DISMISS_GRACE_MS)
+    },
+
+    cancelDeferredDismiss(): void {
+      dismissTimer = clearTimer(dismissTimer)
+    },
+
+    close(): void {
+      dismissTimer = clearTimer(dismissTimer)
+      closeInternal()
+    },
+
+    isTripped(triggerId: string): boolean {
+      return tripped.has(triggerId)
+    },
+
+    destroy(): void {
+      debounceTimer = clearTimer(debounceTimer)
+      loadingTimer = clearTimer(loadingTimer)
+      dismissTimer = clearTimer(dismissTimer)
+      match = null
+      state = CLOSED_SUGGESTION_STATE
+    },
+  }
+}