@dungle-scrubs/admin-ui-soft 0.0.0-stage → 0.1.0

package/dist/ai/compositions/attention-feed/attention-feed.d.ts

@@ -0,0 +1,127 @@
+import { Confidence } from "../../../components/assistant-ui/elements/confidence-marker.js";
+import * as React from "react";
+//#region src/ai/compositions/attention-feed/attention-feed.d.ts
+/** How well a suggestion is supported, as ConfidenceMarker draws it. */
+export type AttentionConfidence = Confidence;
+/** One claim in a suggestion's summary, with its own confidence. */
+export interface AttentionClaim {
+  id: string;
+  text: string;
+  confidence: AttentionConfidence;
+  /** What the claim rests on, such as "Ann Lee, 08:12 today". */
+  basis: string;
+}
+/** A proactive suggestion an agent raised for the owner. */
+export interface AttentionSuggestion {
+  id: string;
+  /** Who raised it, such as "Email agent". */
+  source: string;
+  /** Where in the source it comes from, such as "Fastmail inbox" or "#ops". */
+  sourceDetail?: string;
+  /** An app link that opens the source. Open source follows it. */
+  sourceHref?: string;
+  /** A lucide icon for the source. Defaults to a bot glyph. */
+  sourceIcon?: React.ReactNode;
+  /** The suggested action, as a headline: "Unsubscribe from Uniqlo". Also the card's name. */
+  action: string;
+  /** Why, in a sentence or two. */
+  summary: string;
+  /** How well `summary` is supported. */
+  confidence: AttentionConfidence;
+  /** What the confidence rests on, such as "14 of 14 archived unread". */
+  basis: string;
+  /**
+   * The summary split into claims, each with its own confidence. When set,
+   * it is shown in place of `summary`, `confidence` and `basis`.
+   */
+  claims?: readonly AttentionClaim[];
+  /** When the agent raised it (ISO 8601). */
+  createdAt?: string;
+}
+/** When a snoozed suggestion comes back. The app owns the timer. */
+export type AttentionSnoozePreset = "1-hour" | "tonight" | "tomorrow" | "next-week";
+/** The snooze presets, in menu order. */
+export declare const ATTENTION_SNOOZE_PRESETS: readonly {
+  id: AttentionSnoozePreset;
+  label: string;
+}[];
+/** What a key can do to the suggestion under the cursor. */
+export type AttentionAction = "accept" | "dismiss" | "not-useful" | "snooze" | "open";
+/** Optional feedback that comes with a dismissal. */
+export type AttentionDismissFeedback = "not-useful";
+export interface AttentionActionError {
+  /** The suggestion whose action failed. */
+  itemId: string;
+  /** Plain-text error, for example the server's message. */
+  message: string;
+}
+export interface AttentionFeedProps {
+  /** The suggestions, newest first. */
+  items: readonly AttentionSuggestion[];
+  /** The owner accepted a suggestion: run its action. */
+  onAccept: (itemId: string) => void;
+  /** The owner dismissed a suggestion, optionally marking it not useful. */
+  onDismiss: (itemId: string, feedback?: AttentionDismissFeedback) => void;
+  /** The owner snoozed a suggestion until `preset`. The app owns the timer. */
+  onSnooze: (itemId: string, preset: AttentionSnoozePreset) => void;
+  /**
+   * The owner opened a suggestion's source. A suggestion with `sourceHref`
+   * also follows its link. Without either, the card has no Open source.
+   */
+  onOpenSource?: (itemId: string) => void;
+  /**
+   * Keyboard key (`KeyboardEvent.key`) to action. A mapped key wins over the
+   * built-in `j`/`k`; the arrow keys always navigate. Defaults to `a` accept,
+   * `d` dismiss, `n` not useful, `s` snooze and `o` open source.
+   */
+  keymap?: Readonly<Record<string, AttentionAction>>;
+  /** Whether a suggestion's action is in flight. Its controls are disabled meanwhile. */
+  isPending?: (itemId: string) => boolean;
+  /**
+   * The last failed action. It shows on the suggestion, or above the list
+   * once the suggestion is gone, until the owner dismisses it. The feed never
+   * retries.
+   */
+  actionError?: AttentionActionError | null;
+  /** The owner dismissed `actionError`. Clear it here. */
+  onDismissActionError?: () => void;
+  /**
+   * Suggestions that appeared after the first load, newest first. Announce
+   * them here, for example with an AlertToast.
+   */
+  onArrive?: (items: AttentionSuggestion[]) => void;
+  /** The suggestion the cursor is on (controlled). A new value scrolls it into view. */
+  focusedId?: string | null;
+  /** The suggestion the cursor starts on (uncontrolled). */
+  defaultFocusedId?: string | null;
+  onFocusChange?: (itemId: string | null) => void;
+  /** Formats `createdAt` for display. Defaults to the local time, such as 09:12. */
+  formatTime?: (iso: string) => string;
+  /** Accessible name of the feed. */
+  label?: string;
+  /** Show placeholder cards while the first load is in flight. */
+  isLoading?: boolean;
+  /** Plain-text load error, shown above the suggestions. */
+  error?: string;
+  /** Text shown when nothing needs attention. */
+  emptyLabel?: string;
+  className?: string;
+}
+/**
+ * Proactive agent suggestions as cards: each shows its source, its summary
+ * underlined by confidence (ConfidenceMarker: hover or focus a claim for its
+ * basis), and the suggested action. Accept it, dismiss it (optionally as not
+ * useful), snooze it to a preset, or open its source.
+ *
+ * Keyboard: the same model as DecisionQueue. `j`/`k` or the arrows move the
+ * cursor between cards and `keymap` keys act on the card under it, with the
+ * keys hinted above the list and on each button. Keys are ignored while focus
+ * is in a text field.
+ *
+ * Decisions are non-optimistic: a card shows pending (`isPending`) until the
+ * app removes it, and a failed action shows its error on the card until
+ * dismissed. In a feed narrower than 32rem (a phone) each card also swipes:
+ * a full swipe dismisses it, and the revealed buttons accept or dismiss.
+ */
+export declare function AttentionFeed(props: AttentionFeedProps): React.JSX.Element;
+//#endregion