uidex 0.3.0 → 0.5.0

package/dist/react/index.d.cts

@@ -1,6 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, ComponentType, ReactElement } from 'react';
 import { StoreApi } from 'zustand/vanilla';
+import { ReportPayload, ReportResult, IngestConfig, ReportListResponse, PinRecord, ArchiveReason } from '@uidex/api-client';
+import { TemplateResult } from 'lit-html';
 
 declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
 type EntityKind = (typeof ENTITY_KINDS)[number];
@@ -35,11 +37,16 @@ interface Route {
     path: string;
     page: string;
 }
+interface FlowStep {
+    entityId: string;
+    action?: string;
+}
 interface Flow {
     kind: "flow";
     id: string;
     loc: Location;
     touches: string[];
+    steps: FlowStep[];
 }
 interface Page extends EntityWithMetaBase {
     kind: "page";
@@ -64,6 +71,26 @@ type EntityByKind<K extends EntityKind> = Extract<Entity, {
     kind: K;
 }>;
 
+interface ReportRecord {
+    id: string;
+    entity?: string;
+    reporter?: {
+        id?: string;
+        email?: string;
+        name?: string;
+    };
+    title?: string;
+    body: string;
+    type: string;
+    severity: string;
+    status: string;
+    labels?: string[];
+    url: string;
+    route?: string;
+    pageTitle?: string;
+    screenshot?: string;
+    createdAt: string;
+}
 interface Registry {
     add(entity: Entity): void;
     get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
@@ -71,6 +98,17 @@ interface Registry {
     query(predicate: (entity: Entity) => boolean): Entity[];
     byScope(scope: Scope): Entity[];
     touchedBy(flowId: string): Entity[];
+    setReports(kind: EntityKind, id: string, reports: readonly ReportRecord[]): void;
+    getReports(kind: EntityKind, id: string): readonly ReportRecord[];
+    listReportKeys(): readonly string[];
+    archiveReport?: (reportId: string, reason?: string) => void | Promise<void>;
+    onReportsChange(cb: () => void): () => void;
+}
+
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
 }
 
 type ThemePreference = "light" | "dark" | "auto";
@@ -89,89 +127,60 @@ interface SessionSnapshot {
     theme: ThemePreference;
     resolvedTheme: ResolvedTheme;
     ingestActive: boolean;
-}
-interface SessionActions {
-    hover(ref: EntityRef | null): void;
-    select(ref: EntityRef | null): void;
-    /**
-     * Append a view onto the view stack. Pure: never resolves defaults.
-     */
-    pushStack(entry: ViewStackEntry): void;
-    /**
-     * Remove the top entry from the view stack. No-op when the stack is empty.
-     */
-    popStack(): void;
-    /**
-     * Empty the view stack.
-     */
-    clearStack(): void;
-    /**
-     * Open a view by id. If `ref` is omitted, the current `selection` is captured;
-     * pass `null` explicitly to open the view with no ref context. Thin wrapper
-     * around `pushStack`.
-     */
-    openView(id: string, ref?: EntityRef | null): void;
     /**
-     * Clear the entire view stack. Thin wrapper around `clearStack`.
+     * Identity for the local user. Set once at session creation; gates realtime
+     * features (cursor labels, presence) and auto-populates report attribution.
      */
-    closeView(): void;
-    setInspectorActive(active: boolean): void;
-    toggleInspector(): void;
-    /** Pin the overlay to `ref` until `clearPinnedHighlight` is called. */
-    pinHighlight(ref: EntityRef): void;
-    clearPinnedHighlight(): void;
-    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
-    setIngest(active: boolean): void;
+    user: UserIdentity | null;
+}
+type SessionState = SessionSnapshot;
+
+interface NavigationState {
+    stack: ViewStackEntry[];
 }
-interface SessionState extends SessionSnapshot {
-    actions: SessionActions;
+interface NavigationActions {
+    push(entry: ViewStackEntry): void;
+    pop(): void;
+    replace(entry: ViewStackEntry): void;
+    clear(): void;
+    reset(stack: ViewStackEntry[]): void;
 }
+type NavigationStore = StoreApi<NavigationState> & {
+    nav: NavigationActions;
+};
 
-type SurfaceEvent = {
-    type: "TOGGLE_INSPECTOR";
-} | {
-    type: "OPEN_PALETTE";
-} | {
-    type: "PUSH_VIEW";
-    entry: ViewStackEntry;
-} | {
-    type: "POP_VIEW";
-} | {
-    type: "CLOSE";
-} | {
-    type: "ESC";
-} | {
-    type: "CMD_K";
-} | {
-    type: "SELECT";
-    ref: EntityRef | null;
-    entry: ViewStackEntry;
-} | {
-    type: "SET_SELECTION";
-    ref: EntityRef | null;
-} | {
-    type: "HOVER";
-    ref: EntityRef;
-    element: HTMLElement | null;
-    color?: string | null;
-} | {
-    type: "UNHOVER";
-} | {
-    type: "PIN";
-    ref?: EntityRef;
-} | {
-    type: "UNPIN";
-} | {
-    type: "SET_THEME";
-    theme: ThemePreference;
-    resolvedTheme: ResolvedTheme;
-} | {
-    type: "SET_INGEST";
-    active: boolean;
+type SurfaceMode = "idle" | "inspecting" | "palette" | "viewing";
+interface ModeSnapshot {
+    mode: SurfaceMode;
+    inspectorActive: boolean;
+}
+interface ModeTransitions {
+    openPalette(): void;
+    openInspector(): void;
+    closeInspector(): void;
+    toggleInspector(): void;
+    enterViewing(initialStack: ViewStackEntry[]): void;
+    dismiss(): void;
+    popOrTransition(): void;
+    pushView(entry: ViewStackEntry): void;
+}
+type ModeStore = StoreApi<ModeSnapshot> & {
+    transition: ModeTransitions;
 };
 
+interface HighlightActions {
+    hover(ref: EntityRef, element?: HTMLElement | null, color?: string | null): void;
+    unhover(): void;
+    pin(ref?: EntityRef): void;
+    unpin(): void;
+}
 type SessionStore = StoreApi<SessionState> & {
-    send(event: SurfaceEvent): void;
+    readonly nav: NavigationStore;
+    readonly mode: ModeStore;
+    readonly highlight: HighlightActions;
+    select(ref: EntityRef | null): void;
+    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
+    setIngest(active: boolean): void;
 };
 
 type ConsoleLevel = "warn" | "error";
@@ -215,92 +224,46 @@ interface NetworkCapture {
     clear(): void;
 }
 
-interface ConsoleLogEntry {
-    level: "log" | "warn" | "error" | "info";
-    message: string;
-    timestamp: string;
-}
-interface NetworkErrorEntry {
-    url: string;
-    method: string;
-    status: number | null;
-    statusText: string | null;
-    timestamp: string;
-}
-interface Viewport {
-    width: number;
-    height: number;
-}
-interface SourceRef {
-    filePath: string;
-    line: number;
-}
-interface FeedbackSuggestedTarget {
-    integrationId: string;
-    targetConfig: Record<string, unknown>;
-}
-interface FeedbackPayload {
-    type: "bug" | "feature" | "improvement" | "question";
-    severity: "low" | "medium" | "high" | "critical";
-    title?: string;
-    description: string;
-    componentId: string;
-    element?: string | null;
-    sources?: SourceRef[];
-    url: string;
-    path: string;
-    route?: string | null;
-    pageTitle?: string;
-    sessionId?: string;
-    reporterEmail?: string;
-    reporterName?: string;
-    timestamp: string;
-    viewport: Viewport;
-    screen: Viewport;
-    userAgent: string;
-    locale?: string;
-    environment?: string;
-    appVersion?: string;
-    consoleLogs?: ConsoleLogEntry[];
-    networkErrors?: NetworkErrorEntry[];
-    metadata?: Record<string, string>;
-    screenshot?: string;
-    suggestedTarget?: FeedbackSuggestedTarget;
-}
-interface FeedbackExternalLink {
-    ok: boolean;
-    url?: string;
-    key?: string;
-    error?: string;
-}
-interface FeedbackResult {
-    id: string;
-    sequenceNumber: number;
-    externalLink?: FeedbackExternalLink;
-}
-interface IngestConfigEpic {
-    key: string;
-    summary: string;
-    status: string;
-}
-interface IngestConfig {
-    hasJira: boolean;
-    integrationId?: string;
-    epics?: IngestConfigEpic[];
-}
-/**
- * Generic so third-party adapters (e.g. `uidex-cloud`) can plug in their own
- * payload/result/integration shapes. SDK-bundled `cloud()` returns the
- * defaulted form. `ViewContext.cloud` uses the fully-open variant; consumers
- * that need the SDK shape narrow with `as CloudAdapter`.
- */
-interface CloudAdapter<TPayload = FeedbackPayload, TResult = FeedbackResult, TIntegrations = {
+type RealtimePresenceUser = {
+    userId: string;
+    name: string;
+    avatar: string | null;
+};
+type RealtimeChannelState = "connecting" | "connected" | "disconnected";
+interface RealtimeConnectOpts {
+    user: UserIdentity;
+    route: string;
+}
+interface RealtimeChannel {
+    readonly state: RealtimeChannelState;
+    connect(): void;
+    disconnect(): void;
+    joinRoute(route: string): void;
+    onPresence(cb: (users: RealtimePresenceUser[]) => void): () => void;
+    onPin(cb: (pin: PinRecord) => void): () => void;
+}
+interface CloudAdapter<TPayload = ReportPayload, TResult = ReportResult, TIntegrations = {
     getConfig(): Promise<IngestConfig>;
+    getCachedConfig(): IngestConfig | null;
 }> {
-    readonly feedback: {
+    readonly reports: {
         submit(payload: TPayload): Promise<TResult>;
+        list?(opts?: {
+            page?: number;
+            limit?: number;
+        }): Promise<ReportListResponse>;
     };
     readonly integrations: TIntegrations;
+    readonly realtime: {
+        connect(opts: RealtimeConnectOpts): RealtimeChannel;
+    };
+    readonly pins: {
+        list(params: {
+            route?: string;
+            entities?: string;
+        }): Promise<PinRecord[]>;
+        archive(reportId: string, reason?: ArchiveReason): Promise<void>;
+    };
 }
 
 interface IngestOptions {
@@ -327,11 +290,30 @@ interface OverlayShowOptions {
     borderStyle?: string;
     borderWidth?: number;
     fillOpacity?: number;
+    backdrop?: boolean;
 }
 
 type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
 
-type ViewSurface = ListSurface | DetailSurface | FormSurface | CustomSurface;
+interface RouteMatch {
+    view: View;
+    priority: number;
+}
+interface Router {
+    resolve(ref: EntityRef): RouteMatch | null;
+    add(view: View, priority?: number): void;
+    remove(id: string): void;
+    get(id: string): View | undefined;
+    list(): readonly View[];
+    buildStack(entry: ViewStackEntry): ViewStackEntry[];
+    navigate(ref: EntityRef): void;
+    recents(): readonly EntityRef[];
+    favorites(): readonly EntityRef[];
+    toggleFavorite(ref: EntityRef): void;
+    isFavorite(ref: EntityRef): boolean;
+}
+
+type ViewSurface = ListSurface | DetailSurface | FormSurface;
 interface ListSurface {
     kind: "list";
     id: string;
@@ -340,6 +322,12 @@ interface ListSurface {
     emptyLabel?: string;
     defaultHighlight?: string;
     filter?(item: ListItem, query: string): boolean;
+    /**
+     * When false, the search input is hidden and the content element receives
+     * focus directly for keyboard navigation.
+     * @default true
+     */
+    searchable?: boolean;
 }
 interface ListItem {
     value: string;
@@ -359,12 +347,15 @@ interface ListItem {
     };
     /**
      * Optional leading-icon factory used for non-entity rows (e.g. a palette
-     * "Feedback" command). Called per-render so the returned Node is fresh.
+     * "Report" command). Called per-render so the returned Node is fresh.
      * The shell wraps whatever is returned in a rounded-square tile.
      */
     leading?: () => Node;
     /** Raw data attribute tag appended to the row (for test/e2e hooks). */
     tag?: string;
+    trailing?: TemplateResult;
+    /** Contextual actions surfaced in the footer popup when this row is highlighted. */
+    actions?: readonly ShellAction[];
 }
 interface DetailSurface {
     kind: "detail";
@@ -388,6 +379,7 @@ interface DetailActionBase {
     ariaLabel?: string;
     hint?: string;
     intent?: ShellActionIntent;
+    group?: string;
 }
 type DetailAction = (DetailActionBase & {
     copy: string;
@@ -405,19 +397,21 @@ type DetailAction = (DetailActionBase & {
 }) | (DetailActionBase & {
     run: (ctx: DetailActionRunContext) => void | Promise<void>;
 });
-type DetailActionIcon = "copy" | "message-circle" | "chevron-down" | "target";
+type DetailActionIcon = "archive-x" | "copy" | "camera" | "inbox" | "message-circle-warning" | "chevron-down" | "highlighter" | "sticky-note" | "ticket-plus" | "view";
 interface DetailActionRunContext {
     setLabel(next: string, durationMs?: number): void;
 }
+interface ResolvedFlowStep {
+    ordinal: number;
+    entity: Entity;
+    action?: string;
+}
 type DetailSection = {
     id: "description";
     text: string;
 } | {
     id: "acceptance";
     items: readonly string[];
-} | {
-    id: "scopes";
-    scopes: readonly string[];
 } | {
     id: "composes";
     label: string;
@@ -435,13 +429,26 @@ type DetailSection = {
 } | {
     id: "touches";
     entities: readonly Entity[];
-    unresolved: readonly string[];
+    filterable?: boolean;
+} | {
+    id: "steps";
+    steps: readonly ResolvedFlowStep[];
     filterable?: boolean;
 } | {
     id: "routes";
     paths: readonly string[];
     filterable?: boolean;
+} | {
+    id: "screenshot";
+    url: string;
+} | {
+    id: "metadata";
+    entries: readonly MetadataEntry[];
 };
+interface MetadataEntry {
+    label: string;
+    value: string;
+}
 interface FormSurface {
     kind: "form";
     id: string;
@@ -454,6 +461,11 @@ interface FormSurface {
      * routed to the matching `<FieldError>` and submission is skipped.
      */
     schema?: StandardSchemaV1<Record<string, unknown>>;
+    /**
+     * Promise resolving to a base64 screenshot data URL. When provided, the
+     * form renderer shows a thumbnail preview above the fields.
+     */
+    screenshotPreview?: Promise<string | null>;
 }
 /**
  * Minimal StandardSchemaV1 surface — kept inline so the SDK doesn't need a
@@ -533,10 +545,6 @@ type FormField = (FormFieldBase & {
     kind: "checkbox";
     value?: boolean;
 });
-interface CustomSurface {
-    kind: "custom";
-    render: (ctx: ViewContext, root: HTMLElement) => Cleanup | void;
-}
 
 interface ViewPalette {
     label: string;
@@ -547,9 +555,7 @@ interface ViewPalette {
      */
     icon?: () => Node;
     shortcut?: string;
-}
-interface ViewDirectory {
-    list(): readonly View[];
+    subtitle?: string | (() => string);
 }
 interface ViewPushTarget {
     id: string;
@@ -563,16 +569,19 @@ interface ViewContext {
     ref: EntityRef | null;
     registry: Registry;
     cloud: CloudAdapter<unknown, unknown, unknown> | null;
-    sdkCloud: CloudAdapter;
-    views: ViewDirectory;
+    /**
+     * Local user identity from `createUidex`'s `user` option, or `null` when
+     * unconfigured. Views that auto-populate attribution (e.g. report
+     * `reporterName`) read this here instead of touching the session store.
+     */
+    user: UserIdentity | null;
+    views: Router;
     /** Push a view onto the stack. Unregistered ids are a no-op. */
     push: (target: ViewPushTarget) => void;
     /** Pop the top view off the stack. No-op when the stack is empty. */
     pop: () => void;
     /** Clear the entire view stack. */
     close: () => void;
-    /** Resolve the first view matching `ref` and push it onto the stack. */
-    navigate: (ref: EntityRef) => void;
     /** Pin the overlay to `ref` until the user presses Esc. */
     pinHighlight: (ref: EntityRef) => void;
     /** Shell-owned search input. The shell dispatches its value into the active surface. */
@@ -581,6 +590,11 @@ interface ViewContext {
     highlight: HighlightController;
     /** Snapshot of the current view stack (top-most last). */
     getStack: () => readonly ViewStackEntry[];
+    pushEscapeLayer(handler: EscapeHandler): Cleanup;
+    /** Called after a report submission succeeds, to refresh pins etc. */
+    onAfterSubmit?: () => void;
+    /** Return the current route pattern. Falls back to `location.pathname`. */
+    getRoute?: () => string;
 }
 interface ShellHint {
     key: string;
@@ -605,6 +619,7 @@ interface ShellAction {
     id: string;
     label: string;
     shortcut?: string;
+    icon?: () => Node;
     perform: () => void | Promise<void>;
     intent?: ShellActionIntent;
 }
@@ -625,16 +640,20 @@ interface View {
      */
     focusTarget?: (root: HTMLElement, ctx: ViewContext) => HTMLElement | null;
     surface: (ctx: ViewContext) => ViewSurface;
+    /** Direct render for integration adapters (React, etc.). Mutually exclusive with surface renderers. */
+    render?: (ctx: ViewContext, root: HTMLElement) => Cleanup | void;
+    parent?: (ref: EntityRef | null) => ViewStackEntry | null;
 }
 
-interface ViewRegistrar {
-    register(view: View): void;
-    unregister(id: string): void;
-    list(): readonly View[];
-    get(id: string): View | undefined;
-    findMatch(ref: EntityRef): View | null;
-    navigate(ref: EntityRef): void;
+interface PaletteShortcut {
+    /** The key value (e.g. "k", "j", ";"). Matched case-insensitively. */
+    key: string;
+    /** Require Cmd (Mac) / Ctrl (Win/Linux). Default: true. */
+    mod?: boolean;
+    /** Require Shift. Default: false. */
+    shift?: boolean;
 }
+type EscapeHandler = () => boolean;
 
 interface CreateUidexOptions {
     theme?: ThemePreference;
@@ -655,13 +674,33 @@ interface CreateUidexOptions {
      * an options object to override either channel.
      */
     ingest?: IngestOptions | null;
+    /** Keyboard shortcut for the command palette. Defaults to Cmd+K / Ctrl+K. */
+    shortcut?: PaletteShortcut;
+    /**
+     * Identity for the local user. Required to opt into realtime collaborative
+     * features (peer cursors, presence). When omitted, realtime stays
+     * disconnected and report attribution falls back to whatever the user
+     * types in the report form.
+     */
+    user?: UserIdentity;
+    /** Git context for pin filtering. Typically mirrors `cloud({ git })`. */
+    git?: {
+        branch?: string;
+        commit?: string;
+    };
+    /**
+     * Return the current route pattern (e.g. `/users/:id`). Used for
+     * route-based pin matching and report attribution. When omitted, the SDK
+     * falls back to `location.pathname`.
+     */
+    getRoute?: () => string;
 }
 interface Uidex {
     mount(target?: Element): void;
     unmount(): void;
     readonly registry: Registry;
     readonly session: SessionStore;
-    readonly views: ViewRegistrar;
+    readonly views: Router;
     readonly cloud: CloudAdapter | null;
     readonly ingest: Ingest | null;
     readonly shadowRoot: ShadowRoot | null;
@@ -670,15 +709,16 @@ interface Uidex {
 interface UidexProviderProps {
     /**
      * Pre-built uidex instance (e.g. the `uidex` export from `uidex.gen.ts`).
-     * When provided, `projectKey`, `cloud`, and `config` are ignored.
+     * When provided, `projectKey`, `cloud`, `user`, and `config` are ignored.
      */
     instance?: Uidex;
     projectKey?: string;
     cloud?: CloudAdapter | null;
-    config?: Omit<CreateUidexOptions, "cloud">;
+    user?: UserIdentity;
+    config?: Omit<CreateUidexOptions, "cloud" | "user">;
     children?: ReactNode;
 }
-declare function UidexProvider({ instance: externalInstance, projectKey, cloud, config, children, }: UidexProviderProps): react_jsx_runtime.JSX.Element;
+declare function UidexProvider({ instance: externalInstance, projectKey, cloud, user, config, children, }: UidexProviderProps): react_jsx_runtime.JSX.Element;
 
 declare class UidexContextError extends Error {
     constructor(hookName: string);
@@ -708,4 +748,17 @@ interface KindChipProps {
 }
 declare function KindChip({ kind, label, withKindName, className, }: KindChipProps): ReactElement;
 
-export { KindChip, type KindChipProps, type ReactViewDef, UidexContextError, UidexMount, type UidexMountProps, UidexProvider, type UidexProviderProps, createReactView, useUidex };
+interface UidexDevtoolsProps {
+    loadRegistry: (target: Registry) => Registry;
+    projectKey?: string;
+    endpoint?: string;
+    user?: UserIdentity;
+    git?: {
+        branch?: string;
+        commit?: string;
+    };
+    config?: Omit<CreateUidexOptions, "cloud" | "user" | "git">;
+}
+declare function UidexDevtools({ loadRegistry, projectKey, endpoint, user, git, config, }: UidexDevtoolsProps): react_jsx_runtime.JSX.Element | null;
+
+export { KindChip, type KindChipProps, type ReactViewDef, UidexContextError, UidexDevtools, type UidexDevtoolsProps, UidexMount, type UidexMountProps, UidexProvider, type UidexProviderProps, createReactView, useUidex };