uidex 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -34,11 +34,16 @@ interface Route {
34
34
  path: string;
35
35
  page: string;
36
36
  }
37
+ interface FlowStep {
38
+ entityId: string;
39
+ action?: string;
40
+ }
37
41
  interface Flow {
38
42
  kind: "flow";
39
43
  id: string;
40
44
  loc: Location;
41
45
  touches: string[];
46
+ steps: FlowStep[];
42
47
  }
43
48
  interface Page extends EntityWithMetaBase {
44
49
  kind: "page";
@@ -337,15 +342,16 @@ interface FeedbackResult {
337
342
  sequenceNumber: number;
338
343
  externalLink?: FeedbackExternalLink;
339
344
  }
340
- interface IngestConfigEpic {
345
+ interface IngestConfigIssue {
346
+ id: string;
341
347
  key: string;
342
348
  summary: string;
343
- status: string;
349
+ issueType: string;
344
350
  }
345
351
  interface IngestConfig {
346
352
  hasJira: boolean;
347
353
  integrationId?: string;
348
- epics?: IngestConfigEpic[];
354
+ parentIssues?: IngestConfigIssue[];
349
355
  }
350
356
  /**
351
357
  * Generic so third-party adapters (e.g. `uidex-cloud`) can plug in their own
@@ -355,6 +361,12 @@ interface IngestConfig {
355
361
  */
356
362
  interface CloudAdapter<TPayload = FeedbackPayload, TResult = FeedbackResult, TIntegrations = {
357
363
  getConfig(): Promise<IngestConfig>;
364
+ /**
365
+ * Synchronous read of the eagerly-fetched config. Returns `null` until the
366
+ * initial fetch resolves; views that need a sync answer (e.g. detail
367
+ * actions deciding whether to surface a Jira button) read this.
368
+ */
369
+ getCachedConfig(): IngestConfig | null;
358
370
  }> {
359
371
  readonly feedback: {
360
372
  submit(payload: TPayload): Promise<TResult>;
@@ -410,6 +422,10 @@ interface CleanupStack {
410
422
  type CursorTooltipContent = {
411
423
  entity: Entity;
412
424
  node?: Element | null;
425
+ layer?: {
426
+ index: number;
427
+ total: number;
428
+ };
413
429
  } | string;
414
430
  interface CursorTooltip {
415
431
  destroy(): void;
@@ -432,11 +448,13 @@ interface OverlayShowOptions {
432
448
  borderStyle?: string;
433
449
  borderWidth?: number;
434
450
  fillOpacity?: number;
451
+ backdrop?: boolean;
435
452
  }
436
453
  interface Overlay {
437
454
  show(target: Element, options?: OverlayShowOptions): void;
438
455
  hide(): void;
439
456
  destroy(): void;
457
+ onDismiss: (() => void) | null;
440
458
  readonly isVisible: boolean;
441
459
  }
442
460
  interface OverlayDeps {
@@ -451,11 +469,16 @@ interface InspectorMatch {
451
469
  /** Display name resolved via `displayName(entity, element)`. */
452
470
  label: string;
453
471
  }
472
+ interface InspectorMatchStack {
473
+ matches: InspectorMatch[];
474
+ index: number;
475
+ current: InspectorMatch;
476
+ }
454
477
  interface InspectorOptions {
455
478
  session: SessionStore;
456
479
  registry?: Registry;
457
- resolve?: (target: Element) => InspectorMatch | null;
458
- onHover?: (match: InspectorMatch | null, cursor: {
480
+ resolveAll?: (target: Element) => InspectorMatch[];
481
+ onHover?: (stack: InspectorMatchStack | null, cursor: {
459
482
  x: number;
460
483
  y: number;
461
484
  } | null) => void;
@@ -463,6 +486,10 @@ interface InspectorOptions {
463
486
  x: number;
464
487
  y: number;
465
488
  }) => void;
489
+ onCycle?: (stack: InspectorMatchStack, cursor: {
490
+ x: number;
491
+ y: number;
492
+ }) => void;
466
493
  }
467
494
  interface Inspector {
468
495
  mount(): void;
@@ -517,7 +544,10 @@ interface CreateSurfaceShellOptions {
517
544
  * host.
518
545
  */
519
546
  inspector?: Pick<InspectorOptions, "onSelect"> & {
520
- onAfterHover?: InspectorOptions["onHover"];
547
+ onAfterHover?: (match: InspectorMatch | null, cursor: {
548
+ x: number;
549
+ y: number;
550
+ } | null) => void;
521
551
  };
522
552
  }
523
553
  interface SurfaceShell {
@@ -572,6 +602,8 @@ interface ListItem {
572
602
  leading?: () => Node;
573
603
  /** Raw data attribute tag appended to the row (for test/e2e hooks). */
574
604
  tag?: string;
605
+ /** Contextual actions surfaced in the footer popup when this row is highlighted. */
606
+ actions?: readonly ShellAction[];
575
607
  }
576
608
  interface DetailSurface {
577
609
  kind: "detail";
@@ -612,19 +644,21 @@ type DetailAction = (DetailActionBase & {
612
644
  }) | (DetailActionBase & {
613
645
  run: (ctx: DetailActionRunContext) => void | Promise<void>;
614
646
  });
615
- type DetailActionIcon = "copy" | "message-circle" | "chevron-down" | "target";
647
+ type DetailActionIcon = "copy" | "camera" | "message-circle-warning" | "chevron-down" | "highlighter" | "ticket-plus" | "view";
616
648
  interface DetailActionRunContext {
617
649
  setLabel(next: string, durationMs?: number): void;
618
650
  }
651
+ interface ResolvedFlowStep {
652
+ ordinal: number;
653
+ entity: Entity;
654
+ action?: string;
655
+ }
619
656
  type DetailSection = {
620
657
  id: "description";
621
658
  text: string;
622
659
  } | {
623
660
  id: "acceptance";
624
661
  items: readonly string[];
625
- } | {
626
- id: "scopes";
627
- scopes: readonly string[];
628
662
  } | {
629
663
  id: "composes";
630
664
  label: string;
@@ -642,7 +676,10 @@ type DetailSection = {
642
676
  } | {
643
677
  id: "touches";
644
678
  entities: readonly Entity[];
645
- unresolved: readonly string[];
679
+ filterable?: boolean;
680
+ } | {
681
+ id: "steps";
682
+ steps: readonly ResolvedFlowStep[];
646
683
  filterable?: boolean;
647
684
  } | {
648
685
  id: "routes";
@@ -661,6 +698,11 @@ interface FormSurface {
661
698
  * routed to the matching `<FieldError>` and submission is skipped.
662
699
  */
663
700
  schema?: StandardSchemaV1<Record<string, unknown>>;
701
+ /**
702
+ * Promise resolving to a base64 screenshot data URL. When provided, the
703
+ * form renderer shows a thumbnail preview above the fields.
704
+ */
705
+ screenshotPreview?: Promise<string | null>;
664
706
  }
665
707
  /**
666
708
  * Minimal StandardSchemaV1 surface — kept inline so the SDK doesn't need a
@@ -757,6 +799,8 @@ interface ViewPalette {
757
799
  }
758
800
  interface ViewDirectory {
759
801
  list(): readonly View[];
802
+ recents(): readonly EntityRef[];
803
+ favorites(): readonly EntityRef[];
760
804
  }
761
805
  interface ViewPushTarget {
762
806
  id: string;
@@ -782,6 +826,10 @@ interface ViewContext {
782
826
  navigate: (ref: EntityRef) => void;
783
827
  /** Pin the overlay to `ref` until the user presses Esc. */
784
828
  pinHighlight: (ref: EntityRef) => void;
829
+ /** Toggle favorite status for an entity ref. */
830
+ toggleFavorite: (ref: EntityRef) => void;
831
+ /** Check if an entity ref is favorited. */
832
+ isFavorite: (ref: EntityRef) => boolean;
785
833
  /** Shell-owned search input. The shell dispatches its value into the active surface. */
786
834
  searchInput: HTMLInputElement;
787
835
  /** Drives the Surface's singleton overlay from inside a custom surface. */
@@ -812,6 +860,7 @@ interface ShellAction {
812
860
  id: string;
813
861
  label: string;
814
862
  shortcut?: string;
863
+ icon?: () => Node;
815
864
  perform: () => void | Promise<void>;
816
865
  intent?: ShellActionIntent;
817
866
  }
@@ -838,14 +887,25 @@ declare class ViewValidationError extends Error {
838
887
  }
839
888
 
840
889
  interface ActionsPopupHandle {
890
+ readonly trigger: HTMLButtonElement;
841
891
  readonly element: HTMLElement;
842
- open(actions: ShellAction[]): void;
892
+ setActions(actions: ShellAction[]): void;
893
+ open(): void;
843
894
  close(): void;
844
895
  isOpen(): boolean;
845
- handleKey(e: KeyboardEvent): boolean;
846
896
  destroy(): void;
847
897
  }
848
898
 
899
+ interface PaletteShortcut {
900
+ /** The key value (e.g. "k", "j", ";"). Matched case-insensitively. */
901
+ key: string;
902
+ /** Require Cmd (Mac) / Ctrl (Win/Linux). Default: true. */
903
+ mod?: boolean;
904
+ /** Require Shift. Default: false. */
905
+ shift?: boolean;
906
+ }
907
+ declare function formatShortcutLabel(shortcut: PaletteShortcut): string;
908
+
849
909
  declare const SURFACE_HOST_CLASS = "uidex-surface-host";
850
910
  declare const SURFACE_CONTAINER_CLASS = "uidex-container";
851
911
  declare const Z_BASE = 2147483644;
@@ -860,6 +920,10 @@ interface ViewRegistrar {
860
920
  get(id: string): View | undefined;
861
921
  findMatch(ref: EntityRef): View | null;
862
922
  navigate(ref: EntityRef): void;
923
+ recents(): readonly EntityRef[];
924
+ favorites(): readonly EntityRef[];
925
+ toggleFavorite(ref: EntityRef): void;
926
+ isFavorite(ref: EntityRef): boolean;
863
927
  }
864
928
  interface ViewRegistrarOptions {
865
929
  session: SessionStore;
@@ -876,6 +940,7 @@ interface ViewStackOptions {
876
940
  sdkCloud: CloudAdapter;
877
941
  highlight: HighlightController;
878
942
  globalActions?: (ctx: ViewContext) => ShellAction[];
943
+ shortcut?: PaletteShortcut;
879
944
  dev?: boolean;
880
945
  }
881
946
  interface ViewStack {
@@ -889,7 +954,7 @@ interface ViewStack {
889
954
  }
890
955
  declare function createViewStack(options: ViewStackOptions): ViewStack;
891
956
 
892
- declare const commandPaletteView: View;
957
+ declare function createCommandPaletteView(shortcut?: PaletteShortcut): View;
893
958
 
894
959
  declare const componentDetailView: View;
895
960
  declare const featureDetailView: View;
@@ -902,7 +967,7 @@ declare const feedbackView: View;
902
967
 
903
968
  declare const flowDetailView: View;
904
969
 
905
- declare const DEFAULT_VIEWS: readonly [View, View, View, View, View, View, View, View, View, View, View, View];
970
+ declare function buildDefaultViews(shortcut?: PaletteShortcut): View[];
906
971
 
907
972
  interface CreateUidexOptions {
908
973
  theme?: ThemePreference;
@@ -923,6 +988,8 @@ interface CreateUidexOptions {
923
988
  * an options object to override either channel.
924
989
  */
925
990
  ingest?: IngestOptions | null;
991
+ /** Keyboard shortcut for the command palette. Defaults to Cmd+K / Ctrl+K. */
992
+ shortcut?: PaletteShortcut;
926
993
  }
927
994
  interface Uidex {
928
995
  mount(target?: Element): void;
@@ -936,4 +1003,4 @@ interface Uidex {
936
1003
  }
937
1004
  declare function createUidex(options?: CreateUidexOptions): Uidex;
938
1005
 
939
- export { type Cleanup, type CloudAdapter, type ConsoleCapture, type ConsoleEntry, type ConsoleLevel, type ConsoleLogEntry, type Corner, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type CustomSurface, DEFAULT_VIEWS, type DetailAction, type DetailActionIcon, type DetailActionRunContext, type DetailSection, type DetailSubtitle, type DetailSurface, ENTITY_KINDS, type Element$1 as Element, type Entity, type EntityByKind, type EntityKind, type EntityRef, type Feature, type FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type Flow, type FormField, type FormSubmit, type FormSubmitResult, type FormSurface, type FormValue, type HighlightController, type Ingest, type IngestConfig, type IngestConfigEpic, type IngestOptions, type Inspector, type InspectorMatch, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type NetworkCapture, type NetworkEntry, type NetworkErrorEntry, type Overlay, type OverlayShowOptions, type Page, type Primitive, type Region, type Registry, type ResolvedTheme, type Route, SURFACE_CONTAINER_CLASS, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionActions, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SourceRef, type SurfaceHost, type SurfaceHostOptions, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type View, type ViewContext, type ViewDirectory, type ViewPalette, type ViewPushTarget, type ViewRegistrar, type ViewRegistrarOptions, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Viewport, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, assertEntityKind, commandPaletteView, componentDetailView, createConsoleCapture, createCursorTooltip, createHighlightController, createIngest, createInspector, createMenuBar, createNetworkCapture, createOverlay, createRegistry, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewRegistrar, createViewStack, defaultResolveMatch, displayName, entityKey, featureDetailView, feedbackView, flowDetailView, getNativeFetch, isMetaKind, nativeFetch, pageDetailView, prettify, primitiveDetailView, regionDetailView, resolveEntityElement, resolveIngestOptions, resolveTheme, widgetDetailView };
1006
+ export { type Cleanup, type CloudAdapter, type ConsoleCapture, type ConsoleEntry, type ConsoleLevel, type ConsoleLogEntry, type Corner, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type CustomSurface, type DetailAction, type DetailActionIcon, type DetailActionRunContext, type DetailSection, type DetailSubtitle, type DetailSurface, ENTITY_KINDS, type Element$1 as Element, type Entity, type EntityByKind, type EntityKind, type EntityRef, type Feature, type FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type Flow, type FormField, type FormSubmit, type FormSubmitResult, type FormSurface, type FormValue, type HighlightController, type Ingest, type IngestConfig, type IngestConfigIssue, type IngestOptions, type Inspector, type InspectorMatch, type InspectorMatchStack, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type NetworkCapture, type NetworkEntry, type NetworkErrorEntry, type Overlay, type OverlayShowOptions, type Page, type PaletteShortcut, type Primitive, type Region, type Registry, type ResolvedTheme, type Route, SURFACE_CONTAINER_CLASS, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionActions, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SourceRef, type SurfaceHost, type SurfaceHostOptions, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type View, type ViewContext, type ViewDirectory, type ViewPalette, type ViewPushTarget, type ViewRegistrar, type ViewRegistrarOptions, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Viewport, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, assertEntityKind, buildDefaultViews, componentDetailView, createCommandPaletteView, createConsoleCapture, createCursorTooltip, createHighlightController, createIngest, createInspector, createMenuBar, createNetworkCapture, createOverlay, createRegistry, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewRegistrar, createViewStack, defaultResolveMatch, displayName, entityKey, featureDetailView, feedbackView, flowDetailView, formatShortcutLabel, getNativeFetch, isMetaKind, nativeFetch, pageDetailView, prettify, primitiveDetailView, regionDetailView, resolveEntityElement, resolveIngestOptions, resolveTheme, widgetDetailView };
package/dist/index.d.ts CHANGED
@@ -34,11 +34,16 @@ interface Route {
34
34
  path: string;
35
35
  page: string;
36
36
  }
37
+ interface FlowStep {
38
+ entityId: string;
39
+ action?: string;
40
+ }
37
41
  interface Flow {
38
42
  kind: "flow";
39
43
  id: string;
40
44
  loc: Location;
41
45
  touches: string[];
46
+ steps: FlowStep[];
42
47
  }
43
48
  interface Page extends EntityWithMetaBase {
44
49
  kind: "page";
@@ -337,15 +342,16 @@ interface FeedbackResult {
337
342
  sequenceNumber: number;
338
343
  externalLink?: FeedbackExternalLink;
339
344
  }
340
- interface IngestConfigEpic {
345
+ interface IngestConfigIssue {
346
+ id: string;
341
347
  key: string;
342
348
  summary: string;
343
- status: string;
349
+ issueType: string;
344
350
  }
345
351
  interface IngestConfig {
346
352
  hasJira: boolean;
347
353
  integrationId?: string;
348
- epics?: IngestConfigEpic[];
354
+ parentIssues?: IngestConfigIssue[];
349
355
  }
350
356
  /**
351
357
  * Generic so third-party adapters (e.g. `uidex-cloud`) can plug in their own
@@ -355,6 +361,12 @@ interface IngestConfig {
355
361
  */
356
362
  interface CloudAdapter<TPayload = FeedbackPayload, TResult = FeedbackResult, TIntegrations = {
357
363
  getConfig(): Promise<IngestConfig>;
364
+ /**
365
+ * Synchronous read of the eagerly-fetched config. Returns `null` until the
366
+ * initial fetch resolves; views that need a sync answer (e.g. detail
367
+ * actions deciding whether to surface a Jira button) read this.
368
+ */
369
+ getCachedConfig(): IngestConfig | null;
358
370
  }> {
359
371
  readonly feedback: {
360
372
  submit(payload: TPayload): Promise<TResult>;
@@ -410,6 +422,10 @@ interface CleanupStack {
410
422
  type CursorTooltipContent = {
411
423
  entity: Entity;
412
424
  node?: Element | null;
425
+ layer?: {
426
+ index: number;
427
+ total: number;
428
+ };
413
429
  } | string;
414
430
  interface CursorTooltip {
415
431
  destroy(): void;
@@ -432,11 +448,13 @@ interface OverlayShowOptions {
432
448
  borderStyle?: string;
433
449
  borderWidth?: number;
434
450
  fillOpacity?: number;
451
+ backdrop?: boolean;
435
452
  }
436
453
  interface Overlay {
437
454
  show(target: Element, options?: OverlayShowOptions): void;
438
455
  hide(): void;
439
456
  destroy(): void;
457
+ onDismiss: (() => void) | null;
440
458
  readonly isVisible: boolean;
441
459
  }
442
460
  interface OverlayDeps {
@@ -451,11 +469,16 @@ interface InspectorMatch {
451
469
  /** Display name resolved via `displayName(entity, element)`. */
452
470
  label: string;
453
471
  }
472
+ interface InspectorMatchStack {
473
+ matches: InspectorMatch[];
474
+ index: number;
475
+ current: InspectorMatch;
476
+ }
454
477
  interface InspectorOptions {
455
478
  session: SessionStore;
456
479
  registry?: Registry;
457
- resolve?: (target: Element) => InspectorMatch | null;
458
- onHover?: (match: InspectorMatch | null, cursor: {
480
+ resolveAll?: (target: Element) => InspectorMatch[];
481
+ onHover?: (stack: InspectorMatchStack | null, cursor: {
459
482
  x: number;
460
483
  y: number;
461
484
  } | null) => void;
@@ -463,6 +486,10 @@ interface InspectorOptions {
463
486
  x: number;
464
487
  y: number;
465
488
  }) => void;
489
+ onCycle?: (stack: InspectorMatchStack, cursor: {
490
+ x: number;
491
+ y: number;
492
+ }) => void;
466
493
  }
467
494
  interface Inspector {
468
495
  mount(): void;
@@ -517,7 +544,10 @@ interface CreateSurfaceShellOptions {
517
544
  * host.
518
545
  */
519
546
  inspector?: Pick<InspectorOptions, "onSelect"> & {
520
- onAfterHover?: InspectorOptions["onHover"];
547
+ onAfterHover?: (match: InspectorMatch | null, cursor: {
548
+ x: number;
549
+ y: number;
550
+ } | null) => void;
521
551
  };
522
552
  }
523
553
  interface SurfaceShell {
@@ -572,6 +602,8 @@ interface ListItem {
572
602
  leading?: () => Node;
573
603
  /** Raw data attribute tag appended to the row (for test/e2e hooks). */
574
604
  tag?: string;
605
+ /** Contextual actions surfaced in the footer popup when this row is highlighted. */
606
+ actions?: readonly ShellAction[];
575
607
  }
576
608
  interface DetailSurface {
577
609
  kind: "detail";
@@ -612,19 +644,21 @@ type DetailAction = (DetailActionBase & {
612
644
  }) | (DetailActionBase & {
613
645
  run: (ctx: DetailActionRunContext) => void | Promise<void>;
614
646
  });
615
- type DetailActionIcon = "copy" | "message-circle" | "chevron-down" | "target";
647
+ type DetailActionIcon = "copy" | "camera" | "message-circle-warning" | "chevron-down" | "highlighter" | "ticket-plus" | "view";
616
648
  interface DetailActionRunContext {
617
649
  setLabel(next: string, durationMs?: number): void;
618
650
  }
651
+ interface ResolvedFlowStep {
652
+ ordinal: number;
653
+ entity: Entity;
654
+ action?: string;
655
+ }
619
656
  type DetailSection = {
620
657
  id: "description";
621
658
  text: string;
622
659
  } | {
623
660
  id: "acceptance";
624
661
  items: readonly string[];
625
- } | {
626
- id: "scopes";
627
- scopes: readonly string[];
628
662
  } | {
629
663
  id: "composes";
630
664
  label: string;
@@ -642,7 +676,10 @@ type DetailSection = {
642
676
  } | {
643
677
  id: "touches";
644
678
  entities: readonly Entity[];
645
- unresolved: readonly string[];
679
+ filterable?: boolean;
680
+ } | {
681
+ id: "steps";
682
+ steps: readonly ResolvedFlowStep[];
646
683
  filterable?: boolean;
647
684
  } | {
648
685
  id: "routes";
@@ -661,6 +698,11 @@ interface FormSurface {
661
698
  * routed to the matching `<FieldError>` and submission is skipped.
662
699
  */
663
700
  schema?: StandardSchemaV1<Record<string, unknown>>;
701
+ /**
702
+ * Promise resolving to a base64 screenshot data URL. When provided, the
703
+ * form renderer shows a thumbnail preview above the fields.
704
+ */
705
+ screenshotPreview?: Promise<string | null>;
664
706
  }
665
707
  /**
666
708
  * Minimal StandardSchemaV1 surface — kept inline so the SDK doesn't need a
@@ -757,6 +799,8 @@ interface ViewPalette {
757
799
  }
758
800
  interface ViewDirectory {
759
801
  list(): readonly View[];
802
+ recents(): readonly EntityRef[];
803
+ favorites(): readonly EntityRef[];
760
804
  }
761
805
  interface ViewPushTarget {
762
806
  id: string;
@@ -782,6 +826,10 @@ interface ViewContext {
782
826
  navigate: (ref: EntityRef) => void;
783
827
  /** Pin the overlay to `ref` until the user presses Esc. */
784
828
  pinHighlight: (ref: EntityRef) => void;
829
+ /** Toggle favorite status for an entity ref. */
830
+ toggleFavorite: (ref: EntityRef) => void;
831
+ /** Check if an entity ref is favorited. */
832
+ isFavorite: (ref: EntityRef) => boolean;
785
833
  /** Shell-owned search input. The shell dispatches its value into the active surface. */
786
834
  searchInput: HTMLInputElement;
787
835
  /** Drives the Surface's singleton overlay from inside a custom surface. */
@@ -812,6 +860,7 @@ interface ShellAction {
812
860
  id: string;
813
861
  label: string;
814
862
  shortcut?: string;
863
+ icon?: () => Node;
815
864
  perform: () => void | Promise<void>;
816
865
  intent?: ShellActionIntent;
817
866
  }
@@ -838,14 +887,25 @@ declare class ViewValidationError extends Error {
838
887
  }
839
888
 
840
889
  interface ActionsPopupHandle {
890
+ readonly trigger: HTMLButtonElement;
841
891
  readonly element: HTMLElement;
842
- open(actions: ShellAction[]): void;
892
+ setActions(actions: ShellAction[]): void;
893
+ open(): void;
843
894
  close(): void;
844
895
  isOpen(): boolean;
845
- handleKey(e: KeyboardEvent): boolean;
846
896
  destroy(): void;
847
897
  }
848
898
 
899
+ interface PaletteShortcut {
900
+ /** The key value (e.g. "k", "j", ";"). Matched case-insensitively. */
901
+ key: string;
902
+ /** Require Cmd (Mac) / Ctrl (Win/Linux). Default: true. */
903
+ mod?: boolean;
904
+ /** Require Shift. Default: false. */
905
+ shift?: boolean;
906
+ }
907
+ declare function formatShortcutLabel(shortcut: PaletteShortcut): string;
908
+
849
909
  declare const SURFACE_HOST_CLASS = "uidex-surface-host";
850
910
  declare const SURFACE_CONTAINER_CLASS = "uidex-container";
851
911
  declare const Z_BASE = 2147483644;
@@ -860,6 +920,10 @@ interface ViewRegistrar {
860
920
  get(id: string): View | undefined;
861
921
  findMatch(ref: EntityRef): View | null;
862
922
  navigate(ref: EntityRef): void;
923
+ recents(): readonly EntityRef[];
924
+ favorites(): readonly EntityRef[];
925
+ toggleFavorite(ref: EntityRef): void;
926
+ isFavorite(ref: EntityRef): boolean;
863
927
  }
864
928
  interface ViewRegistrarOptions {
865
929
  session: SessionStore;
@@ -876,6 +940,7 @@ interface ViewStackOptions {
876
940
  sdkCloud: CloudAdapter;
877
941
  highlight: HighlightController;
878
942
  globalActions?: (ctx: ViewContext) => ShellAction[];
943
+ shortcut?: PaletteShortcut;
879
944
  dev?: boolean;
880
945
  }
881
946
  interface ViewStack {
@@ -889,7 +954,7 @@ interface ViewStack {
889
954
  }
890
955
  declare function createViewStack(options: ViewStackOptions): ViewStack;
891
956
 
892
- declare const commandPaletteView: View;
957
+ declare function createCommandPaletteView(shortcut?: PaletteShortcut): View;
893
958
 
894
959
  declare const componentDetailView: View;
895
960
  declare const featureDetailView: View;
@@ -902,7 +967,7 @@ declare const feedbackView: View;
902
967
 
903
968
  declare const flowDetailView: View;
904
969
 
905
- declare const DEFAULT_VIEWS: readonly [View, View, View, View, View, View, View, View, View, View, View, View];
970
+ declare function buildDefaultViews(shortcut?: PaletteShortcut): View[];
906
971
 
907
972
  interface CreateUidexOptions {
908
973
  theme?: ThemePreference;
@@ -923,6 +988,8 @@ interface CreateUidexOptions {
923
988
  * an options object to override either channel.
924
989
  */
925
990
  ingest?: IngestOptions | null;
991
+ /** Keyboard shortcut for the command palette. Defaults to Cmd+K / Ctrl+K. */
992
+ shortcut?: PaletteShortcut;
926
993
  }
927
994
  interface Uidex {
928
995
  mount(target?: Element): void;
@@ -936,4 +1003,4 @@ interface Uidex {
936
1003
  }
937
1004
  declare function createUidex(options?: CreateUidexOptions): Uidex;
938
1005
 
939
- export { type Cleanup, type CloudAdapter, type ConsoleCapture, type ConsoleEntry, type ConsoleLevel, type ConsoleLogEntry, type Corner, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type CustomSurface, DEFAULT_VIEWS, type DetailAction, type DetailActionIcon, type DetailActionRunContext, type DetailSection, type DetailSubtitle, type DetailSurface, ENTITY_KINDS, type Element$1 as Element, type Entity, type EntityByKind, type EntityKind, type EntityRef, type Feature, type FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type Flow, type FormField, type FormSubmit, type FormSubmitResult, type FormSurface, type FormValue, type HighlightController, type Ingest, type IngestConfig, type IngestConfigEpic, type IngestOptions, type Inspector, type InspectorMatch, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type NetworkCapture, type NetworkEntry, type NetworkErrorEntry, type Overlay, type OverlayShowOptions, type Page, type Primitive, type Region, type Registry, type ResolvedTheme, type Route, SURFACE_CONTAINER_CLASS, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionActions, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SourceRef, type SurfaceHost, type SurfaceHostOptions, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type View, type ViewContext, type ViewDirectory, type ViewPalette, type ViewPushTarget, type ViewRegistrar, type ViewRegistrarOptions, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Viewport, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, assertEntityKind, commandPaletteView, componentDetailView, createConsoleCapture, createCursorTooltip, createHighlightController, createIngest, createInspector, createMenuBar, createNetworkCapture, createOverlay, createRegistry, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewRegistrar, createViewStack, defaultResolveMatch, displayName, entityKey, featureDetailView, feedbackView, flowDetailView, getNativeFetch, isMetaKind, nativeFetch, pageDetailView, prettify, primitiveDetailView, regionDetailView, resolveEntityElement, resolveIngestOptions, resolveTheme, widgetDetailView };
1006
+ export { type Cleanup, type CloudAdapter, type ConsoleCapture, type ConsoleEntry, type ConsoleLevel, type ConsoleLogEntry, type Corner, type CreateSessionOptions, type CreateSurfaceShellOptions, type CreateUidexOptions, type CursorTooltip, type CursorTooltipDeps, type CustomSurface, type DetailAction, type DetailActionIcon, type DetailActionRunContext, type DetailSection, type DetailSubtitle, type DetailSurface, ENTITY_KINDS, type Element$1 as Element, type Entity, type EntityByKind, type EntityKind, type EntityRef, type Feature, type FeedbackExternalLink, type FeedbackPayload, type FeedbackResult, type FeedbackSuggestedTarget, type Flow, type FormField, type FormSubmit, type FormSubmitResult, type FormSurface, type FormValue, type HighlightController, type Ingest, type IngestConfig, type IngestConfigIssue, type IngestOptions, type Inspector, type InspectorMatch, type InspectorMatchStack, type InspectorOptions, KIND_STYLE, type KindStyleEntry, type ListItem, type ListSurface, type Location, type MenuBar, type MenuBarOptions, type MetaEntityKind, type Metadata, type NetworkCapture, type NetworkEntry, type NetworkErrorEntry, type Overlay, type OverlayShowOptions, type Page, type PaletteShortcut, type Primitive, type Region, type Registry, type ResolvedTheme, type Route, SURFACE_CONTAINER_CLASS, SURFACE_HOST_CLASS, SURFACE_IGNORE_SELECTOR, type Scope, type SessionActions, type SessionSnapshot, type SessionState, type SessionStore, type ShellAction, type ShellHint, type SourceRef, type SurfaceHost, type SurfaceHostOptions, type SurfaceShell, type ThemeDetector, type ThemeDetectorDeps, type ThemePreference, type Uidex, UnknownEntityKindError, type View, type ViewContext, type ViewDirectory, type ViewPalette, type ViewPushTarget, type ViewRegistrar, type ViewRegistrarOptions, type ViewStack, type ViewStackEntry, type ViewStackOptions, type ViewSurface, ViewValidationError, type Viewport, type Widget, Z_BASE, Z_CHROME, Z_OVERLAY, assertEntityKind, buildDefaultViews, componentDetailView, createCommandPaletteView, createConsoleCapture, createCursorTooltip, createHighlightController, createIngest, createInspector, createMenuBar, createNetworkCapture, createOverlay, createRegistry, createSession, createSurfaceHost, createSurfaceShell, createThemeDetector, createUidex, createViewRegistrar, createViewStack, defaultResolveMatch, displayName, entityKey, featureDetailView, feedbackView, flowDetailView, formatShortcutLabel, getNativeFetch, isMetaKind, nativeFetch, pageDetailView, prettify, primitiveDetailView, regionDetailView, resolveEntityElement, resolveIngestOptions, resolveTheme, widgetDetailView };