uidex 0.2.0 → 0.2.4

package/dist/core/index.d.cts

@@ -5,27 +5,39 @@ interface UidexDefaults {
     color?: string;
     borderStyle?: BorderStyle;
     borderWidth?: number;
-    showLabel?: boolean;
-    labelPosition?: LabelPosition;
 }
 interface UidexConfig {
     defaults?: UidexDefaults;
     colors?: Record<string, string>;
 }
+type UidexKind = 'block' | 'component' | 'primitive';
 interface UidexLocation {
     filePath: string;
     line: number;
+    kind: UidexKind;
     doc?: string;
+    scopes?: string[];
 }
 type UidexMap = Record<string, UidexLocation[]>;
+interface PrimitiveEntry {
+    name: string;
+    filePath: string;
+    scope: string;
+    composes: string[];
+    usedBy: string[];
+    kind: 'primitive';
+}
 interface UidexPage {
     dir: string;
     content: string;
+    description?: string;
     componentIds: string[];
+    rootId?: string;
 }
 interface UidexFeature {
     dir: string;
     content: string;
+    description?: string;
     componentIds: string[];
 }
 interface KeyboardShortcut {
@@ -56,12 +68,16 @@ type FeedbackResult = {
     ok: false;
     error: string;
 };
+type UidexTheme = 'dark' | 'light' | 'auto';
 interface UidexUIOptions {
     components?: UidexMap;
     pages?: UidexPage[];
     features?: UidexFeature[];
+    uiComponents?: PrimitiveEntry[];
     config?: UidexConfig;
     buttonPosition?: ButtonPosition;
+    /** Theme for the devtools widget. Default: 'auto'. */
+    theme?: UidexTheme;
     onSelect?: (id: string) => void;
     /** Keyboard shortcut to toggle inspect mode. Set to false to disable. */
     inspectShortcut?: KeyboardShortcut | false;
@@ -100,6 +116,7 @@ interface FeedbackReport {
     route: string | null;
     timestamp: string;
     pageTitle: string;
+    pageDescription?: string;
     locale: string;
     sessionId: string;
     viewport: {
@@ -119,149 +136,38 @@ interface FeedbackReport {
     metadata?: Record<string, string>;
     consoleLogs?: ConsoleLogEntry[];
     networkErrors?: NetworkErrorEntry[];
+    gitBranch?: string;
+    gitCommit?: string;
+    contextId?: string;
+}
+interface GitContext {
+    branch: string;
+    commit?: string;
 }
 interface OverlayOptions {
     color?: string;
     borderStyle?: BorderStyle;
     borderWidth?: number;
-    label?: string;
-    showLabel?: boolean;
-    labelPosition?: LabelPosition;
     colors?: Record<string, string>;
-}
-
-type ModalView = {
-    type: 'page';
-    dir: string;
-} | {
-    type: 'feature';
-    dir: string;
-} | {
-    type: 'component';
-    id: string;
-} | {
-    type: 'graph';
-};
-interface ModalPage {
-    title: string;
-    dir: string;
-    content: string;
-    componentIds: string[];
-}
-interface ModalFeature {
-    title: string;
-    dir: string;
-    content: string;
-    componentIds: string[];
-}
-interface ModalData {
-    pages: ModalPage[];
-    features: ModalFeature[];
-    components: UidexMap;
-    presentIds: Set<string>;
-}
-interface ModalOptions {
-    onComponentNavigate?: (id: string) => void;
-    elementGetter?: (id: string) => Element | null;
-    ingest?: IngestConfig;
-    onSubmit?: (report: FeedbackReport, result: FeedbackResult) => void;
-    sessionId?: string;
-    getConsoleLogs?: () => ConsoleLogEntry[];
-    getNetworkErrors?: () => NetworkErrorEntry[];
-}
-declare class Modal {
-    private backdrop;
-    private sidebar;
-    private mainContent;
-    private renderTarget;
-    private boundKeyDown;
-    private data;
-    private currentView;
-    private modalType;
-    private sidebarLevel;
-    private expandedGroups;
-    private searchQuery;
-    private searchInput;
-    private options;
-    private static readonly VIEW_TYPE_TO_LEVEL;
-    /** Strip the scanner root dir (e.g. "app") so pages display as routes: app → /, app/foo → /foo */
-    private static formatPageDir;
-    constructor(options?: ModalOptions);
-    /** Set the shadow root to render modals into. */
-    setShadowRoot(root: ShadowRoot): void;
-    /** Update the data model. Refreshes sidebar and content if modal is open. */
-    setData(data: ModalData): void;
-    /** Open the modal. If already open, navigates to the given view. */
-    open(view?: ModalView): void;
-    /** Navigate to a view within the open modal. */
-    navigateTo(view: ModalView): void;
-    hide(): void;
-    destroy(): void;
-    isOpen(): boolean;
-    private getDefaultView;
-    /**
-     * Create the shared modal frame: backdrop, dialog, header (title + close), and mount.
-     * Returns the dialog and header elements so callers can append extra header/body content.
-     */
-    private createModalFrame;
-    /** Finalize modal frame: append close button to header, header to dialog, mount to DOM. */
-    private mountModalFrame;
-    private createShell;
-    private renderSidebar;
-    private renderSidebarRoot;
-    private renderSidebarSublevel;
-    private currentViewMatchesLevel;
-    private getFirstViewForLevel;
-    private getComponentPrefix;
-    private groupComponentsByPrefix;
-    private createSidebarItem;
-    private updateSidebarActive;
-    private getSearchResults;
-    private renderSearchResults;
-    private renderMainContent;
-    private renderPageView;
-    private renderFeatureView;
-    private renderComponentView;
-    private renderGraphView;
-    /** Open a dedicated feedback modal for a specific component. */
-    openFeedback(id: string): void;
-    private createFeedbackShell;
-    /** Render component context (features, pages, doc) above the feedback form. */
-    private renderFeedbackContext;
-    private createChipContainer;
-    private renderFeedbackFormContent;
-    private createComponentChip;
-    private createFeatureChipsSection;
-    private createComponentChipsSection;
-    private createFormGroup;
-    private createSelect;
-    private createChecklistItem;
-    private renderMarkdown;
-    /**
-     * Capture an element by cloning it with inlined computed styles into an
-     * SVG foreignObject, rendering to canvas via an <img> data-URI, and
-     * returning a PNG data-URL.
-     */
-    private captureElementScreenshot;
-    /** Visual CSS properties worth inlining for a screenshot clone. */
-    private static readonly VISUAL_PROPS;
-    /** Recursively copy visual computed styles from source onto a cloned target. */
-    private inlineComputedStyles;
-    private collectEnv;
-    private getBrowserName;
-    private describeElement;
-    private handleKeyDown;
+    /** Outward padding in pixels — expands the overlay beyond the target rect. */
+    padding?: number;
+    /** Opacity of the overlay border (0–1). */
+    opacity?: number;
+    /** Opacity of the semi-transparent background fill (0–1). Default 0.08. */
+    fillOpacity?: number;
 }
 
 declare class UidexUI {
     private menu;
     private overlay;
+    private blockOverlay;
     private modal;
     private inspector;
     private options;
     private mounted;
     private shadowHost;
     private shadowRoot;
+    private themeWrapper;
     private observer;
     private refreshTimer;
     private copyTimer;
@@ -269,27 +175,56 @@ declare class UidexUI {
     private activeMode;
     private sessionId;
     private capture;
+    private theme;
+    private mediaQuery;
+    private boundMediaChange;
+    private classObserver;
+    private cursorTooltip;
+    private pinnedOverlays;
     constructor(options?: UidexUIOptions);
     mount(container?: HTMLElement): void;
+    /** Change the widget theme at runtime. */
+    setTheme(theme: UidexTheme): void;
+    private resolveAutoTheme;
+    private cleanupThemeListeners;
+    private applyTheme;
     destroy(): void;
     startInspect(): void;
     stopInspect(): void;
     isInspecting(): boolean;
-    /** Open the modal panel, optionally to a specific view. */
-    openPanel(view?: ModalView): void;
-    private toggleMode;
-    private updateMenuActiveStates;
+    /** Open the command palette. */
+    openCommand(): void;
+    /** Open the page dialog. */
+    openPage(dir?: string): void;
+    /** Cycle through inspect modes: inspect → copy → feedback → off. */
+    private cycleMode;
+    /** Set a specific inspect mode directly. */
+    private setMode;
     private getComponentsMap;
     private getPagesArray;
     private getFeaturesArray;
     private extractPageTitle;
-    /** Hamburger button handler — open modal to default (current page) view. */
-    private handleExpandClick;
+    /** Page button handler. */
+    private handlePageClick;
+    /** Match current URL pathname to a page dir. */
+    private matchCurrentRoute;
+    /** Format a page dir as a route by stripping prefix segments and route groups. */
+    private formatRoute;
+    /** Check if a route pattern matches a pathname, handling dynamic segments. */
+    private routeMatches;
+    /** Command button handler. */
+    private handleCommandClick;
     /** Selection handler — routes by active mode. */
     private handleSelect;
+    private clearPinnedOverlays;
     private handleCopySelect;
     private findElement;
+    private scrollAndHighlight;
+    private get overlayConfig();
+    private lastHighlightedElement;
     private handleHighlight;
+    /** Detect which components live inside which blocks via DOM ancestry. */
+    private scanBlockContainment;
     /** Push current pages/features/components/presentIds to the modal. */
     private updateModalData;
     /** Scan which registered component IDs are currently in the DOM. */
@@ -303,61 +238,93 @@ declare class UidexUI {
 }
 declare function createUidexUI(options?: UidexUIOptions): UidexUI;
 
+type ActiveMode = 'inspect' | 'copy' | 'feedback' | null;
 interface MenuOptions {
-    onInspectToggle?: () => void;
-    onCopyToggle?: () => void;
-    onFeedbackToggle?: () => void;
-    onExpandClick?: () => void;
+    onInspectCycle?: () => void;
+    onModeSelect?: (mode: 'inspect' | 'copy' | 'feedback' | null) => void;
+    onPageClick?: () => void;
+    onCommandClick?: () => void;
 }
 declare class Menu {
-    private container;
-    private group;
-    private expandBtn;
-    private inspectBtn;
-    private copyBtn;
-    private feedbackBtn;
+    private host;
+    private root;
     private options;
-    private isDragging;
-    private dragStartX;
-    private dragStartY;
-    private dragStartLeft;
-    private dragStartTop;
-    private hasDragged;
-    private boundPointerDown;
-    private boundPointerMove;
-    private boundPointerUp;
+    private activeMode;
+    private hasPages;
+    private positionClass;
+    private container;
     constructor(options?: MenuOptions);
+    setPosition(position: ButtonPosition): void;
     getContainer(): HTMLDivElement | null;
-    /** Update a button's active state. */
-    private setButtonActive;
-    setInspectActive(active: boolean): void;
-    setCopyActive(active: boolean): void;
-    setFeedbackActive(active: boolean): void;
-    private createButton;
+    setActiveMode(mode: ActiveMode): void;
+    setHasPages(has: boolean): void;
+    setContainer(el: HTMLElement | null): void;
     create(): HTMLDivElement;
     destroy(): void;
-    private handlePointerDown;
-    private handlePointerMove;
-    private handlePointerUp;
-    private snapToCorner;
+    private render;
+}
+
+type ModalPage = UidexPage & {
+    title: string;
+    description?: string;
+};
+type ModalFeature = UidexFeature & {
+    title: string;
+};
+interface ModalData {
+    pages: ModalPage[];
+    features: ModalFeature[];
+    components: UidexMap;
+    presentIds: Set<string>;
+    blockContainment: Map<string, string[]>;
+    uiComponents: Map<string, PrimitiveEntry>;
+}
+interface ModalOptions {
+    onComponentNavigate?: (id: string) => void;
+    onLocate?: (id: string) => void;
+    elementGetter?: (id: string) => Element | null;
+    ingest?: IngestConfig;
+    onSubmit?: (report: FeedbackReport, result: FeedbackResult) => void;
+    sessionId?: string;
+    getConsoleLogs?: () => ConsoleLogEntry[];
+    getNetworkErrors?: () => NetworkErrorEntry[];
+}
+
+declare class ModalManager {
+    private container;
+    private host;
+    private root;
+    private store;
+    private options;
+    constructor(options?: ModalOptions);
+    setContainer(el: HTMLElement): void;
+    setData(data: ModalData): void;
+    openCommand(): void;
+    openPage(dir?: string): void;
+    openComponent(id: string): void;
+    openUi(filePath: string): void;
+    openFeedback(id: string): void;
+    closeAll(): void;
+    isOpen(): boolean;
+    destroy(): void;
+    private ensureMounted;
+    private render;
 }
 
 declare class Overlay {
     private element;
-    private labelElement;
     private target;
+    private baseOptions;
     private options;
     private boundUpdatePosition;
     private rafId;
     constructor(options?: OverlayOptions);
-    show(target: HTMLElement, label?: string): void;
+    show(target: HTMLElement, overrides?: Partial<OverlayOptions>): void;
     hide(): void;
     destroy(): void;
     updateOptions(options: Partial<OverlayOptions>): void;
     private createElement;
     private updateStyles;
-    private updateLabel;
-    private applyLabelPosition;
     private updatePosition;
     private addListeners;
     private removeListeners;
@@ -365,8 +332,16 @@ declare class Overlay {
 
 interface InspectorOptions {
     shortcut?: KeyboardShortcut;
-    onHighlight?: (element: HTMLElement | null, id: string | null) => void;
-    onSelect?: (element: HTMLElement, id: string) => void;
+    onHighlight?: (element: HTMLElement | null, id: string | null, parentBlock?: {
+        element: HTMLElement;
+        id: string;
+    } | null, cursor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+    onSelect?: (element: HTMLElement, id: string, opts?: {
+        persistent?: boolean;
+    }) => void;
     onActivate?: () => void;
     onDeactivate?: () => void;
 }
@@ -392,6 +367,14 @@ declare class Inspector {
     private handleClick;
 }
 
+declare class CursorTooltip {
+    private element;
+    show(x: number, y: number, label: string, color: string): void;
+    hide(): void;
+    destroy(): void;
+    private createElement;
+}
+
 /**
  * Injects the uidex styles into a shadow root as a <style> element.
  * This isolates all uidex CSS from the host page.
@@ -404,6 +387,8 @@ declare function registerPages(pages: UidexPage[]): void;
 declare function getPages(): UidexPage[] | null;
 declare function registerFeatures(features: UidexFeature[]): void;
 declare function getFeatures(): UidexFeature[] | null;
+declare function registerGitContext(ctx: GitContext): void;
+declare function getGitContext(): GitContext | null;
 
 declare function classNames(...classes: (string | undefined | null | false)[]): string;
 declare function getContrastColor(hexColor: string): string;
@@ -436,4 +421,4 @@ declare function submitFeedback(endpoint: string, apiKey: string, report: Feedba
     sequenceNumber: number;
 }>;
 
-export { type BorderStyle, type ButtonPosition, type ConsoleLogEntry, type FeedbackReport, type FeedbackResult, type FeedbackSeverity, type FeedbackType, IngestCapture, type IngestConfig, Inspector, type KeyboardShortcut, type LabelPosition, Menu, Modal, type ModalView, type NetworkErrorEntry, Overlay, type OverlayOptions, type UidexConfig, type UidexDefaults, type UidexFeature, type UidexLocation, type UidexMap, type UidexPage, UidexUI, type UidexUIOptions, classNames, createUidexUI, generateSessionId, getComponents, getContrastColor, getFeatures, getPages, hexToRgba, injectStyles, registerComponents, registerFeatures, registerPages, resolveColor, submitFeedback };
+export { type BorderStyle, type ButtonPosition, type ConsoleLogEntry, CursorTooltip, type FeedbackReport, type FeedbackResult, type FeedbackSeverity, type FeedbackType, type GitContext, IngestCapture, type IngestConfig, Inspector, type KeyboardShortcut, type LabelPosition, Menu, ModalManager as Modal, type ModalData, type ModalFeature, ModalManager, type ModalOptions, type ModalPage, type NetworkErrorEntry, Overlay, type OverlayOptions, type PrimitiveEntry, type UidexConfig, type UidexDefaults, type UidexFeature, type UidexLocation, type UidexMap, type UidexPage, type UidexTheme, UidexUI, type UidexUIOptions, classNames, createUidexUI, generateSessionId, getComponents, getContrastColor, getFeatures, getGitContext, getPages, hexToRgba, injectStyles, registerComponents, registerFeatures, registerGitContext, registerPages, resolveColor, submitFeedback };