@industry-theme/file-city-panel 0.2.70 → 0.2.73

package/dist/types/IntroductionTour.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Introduction Tour Configuration
+ *
+ * Defines a guided tour through a codebase using the File City visualization.
+ * Each step can focus on specific directories, highlight files, and provide
+ * educational context to help new developers understand the codebase structure.
+ */
+import type { LayerItem } from '@principal-ai/file-city-react';
+/**
+ * A single step in the introduction tour
+ */
+export interface IntroductionTourStep {
+    /** Unique identifier for this step */
+    id: string;
+    /** Step title shown to the user */
+    title: string;
+    /** Detailed description of what this step shows */
+    description: string;
+    /** Optional estimated time to read/understand this step (in seconds) */
+    estimatedTime?: number;
+    /** Directory to focus on (will zoom and highlight this directory) */
+    focusDirectory?: string;
+    /** Highlight layers to show during this step */
+    highlightLayers?: HighlightLayerConfig[];
+    /** Specific files to highlight or point out */
+    highlightFiles?: string[];
+    /** Color mode to use for this step (fileTypes, git, coverage, etc.) */
+    colorMode?: 'fileTypes' | 'git' | 'pr' | 'commit' | 'coverage' | 'eslint' | 'typescript' | 'prettier' | 'knip' | 'alexandria';
+    /** Interactive actions the user should take */
+    interactiveActions?: InteractiveAction[];
+    /** Links to related documentation or resources */
+    resources?: TourResource[];
+    /** Whether to automatically advance to the next step */
+    autoAdvance?: boolean;
+    /** Duration before auto-advancing (in ms) */
+    autoAdvanceDelay?: number;
+}
+/**
+ * Configuration for a highlight layer in a tour step
+ * Uses LayerItem from the file-city-react library for full compatibility
+ */
+export interface HighlightLayerConfig {
+    /** Layer identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Color for the highlight (hex) */
+    color: string;
+    /** Files/directories to include in this layer - uses LayerItem from file-city-react */
+    items: LayerItem[];
+    /** Opacity (0-1) */
+    opacity?: number;
+    /** Border width in pixels */
+    borderWidth?: number;
+    /** Render strategy */
+    renderStrategy?: 'fill' | 'border' | 'cover';
+}
+/**
+ * Interactive action for user engagement
+ */
+export interface InteractiveAction {
+    /** Action type */
+    type: 'click-file' | 'hover-directory' | 'toggle-layer' | 'explore';
+    /** Action description */
+    description: string;
+    /** Target path or identifier */
+    target?: string;
+    /** Whether this action is required to proceed */
+    required?: boolean;
+}
+/**
+ * Resource link for additional context
+ */
+export interface TourResource {
+    /** Resource title */
+    title: string;
+    /** URL or file path */
+    url: string;
+    /** Resource type */
+    type: 'documentation' | 'video' | 'article' | 'code';
+}
+/**
+ * Complete introduction tour configuration
+ */
+export interface IntroductionTour {
+    /** Tour unique identifier */
+    id: string;
+    /** Tour title */
+    title: string;
+    /** Tour description/overview */
+    description: string;
+    /** Tour version (for tracking updates) */
+    version: string;
+    /** Target audience (beginner, intermediate, advanced) */
+    audience?: 'beginner' | 'intermediate' | 'advanced';
+    /** Prerequisites or required knowledge */
+    prerequisites?: string[];
+    /** Ordered list of steps */
+    steps: IntroductionTourStep[];
+    /** Tour metadata */
+    metadata?: {
+        author?: string;
+        createdAt?: string;
+        updatedAt?: string;
+        tags?: string[];
+    };
+}
+//# sourceMappingURL=IntroductionTour.d.ts.map

package/dist/types/IntroductionTour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IntroductionTour.d.ts","sourceRoot":"","sources":["../../src/types/IntroductionTour.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -5,4 +5,5 @@
  */
 export type { DataSlice, WorkspaceMetadata, RepositoryMetadata, FileTreeSource, ActiveFileSlice, PanelEventType, PanelEvent, PanelEventEmitter, PanelActions, PanelContextValue, PanelComponentProps, PanelMetadata, PanelLifecycleHooks, PanelDefinition, PanelModule, PanelRegistryEntry, PanelLoader, PanelRegistryConfig, } from '@principal-ade/panel-framework-core';
 export type { FileCityColorModesSliceData, QualitySliceData, ColorMode, ColorModeConfig, FileMetricData, HighlightLayer, } from '../panels/utils/qualityLayers';
+export type { IntroductionTour, IntroductionTourStep, HighlightLayerConfig, InteractiveAction, TourResource, } from './IntroductionTour';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAEV,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,eAAe,EAGf,cAAc,EACd,UAAU,EACV,iBAAiB,EAGjB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EAGnB,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,WAAW,EAGX,kBAAkB,EAClB,WAAW,EACX,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAG7C,YAAY,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,YAAY,EAEV,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,eAAe,EAGf,cAAc,EACd,UAAU,EACV,iBAAiB,EAGjB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,EAGnB,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,WAAW,EAGX,kBAAkB,EAClB,WAAW,EACX,mBAAmB,GACpB,MAAM,qCAAqC,CAAC;AAG7C,YAAY,EACV,2BAA2B,EAC3B,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,+BAA+B,CAAC;AAGvC,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,GACb,MAAM,oBAAoB,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { parseTour, parseTourOrThrow, findTourInFileTree, loadTourFromFileTree, TourValidationError, } from './tourParser';
+export type { TourParseResult } from './tourParser';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}

package/dist/utils/tourParser.d.ts

@@ -0,0 +1,46 @@
+import type { IntroductionTour } from '../types/IntroductionTour';
+/**
+ * Validation error for tour parsing
+ */
+export declare class TourValidationError extends Error {
+    readonly field?: string | undefined;
+    readonly value?: unknown | undefined;
+    constructor(message: string, field?: string | undefined, value?: unknown | undefined);
+}
+/**
+ * Result of tour parsing
+ */
+export interface TourParseResult {
+    success: boolean;
+    tour?: IntroductionTour;
+    errors?: TourValidationError[];
+}
+/**
+ * Parses and validates a tour JSON string
+ */
+export declare function parseTour(jsonString: string): TourParseResult;
+/**
+ * Parses tour JSON with a simplified API that throws on error
+ */
+export declare function parseTourOrThrow(jsonString: string): IntroductionTour;
+/**
+ * Finds *.tour.json file in a file tree
+ * Returns the file content if found, null otherwise
+ * If multiple tour files exist, returns the first one found (alphabetically)
+ */
+export declare function findTourInFileTree(fileTree: {
+    allFiles: Array<{
+        path: string;
+        content?: string;
+    }>;
+}): string | null;
+/**
+ * Convenience function to find and parse *.tour.json from a file tree
+ */
+export declare function loadTourFromFileTree(fileTree: {
+    allFiles: Array<{
+        path: string;
+        content?: string;
+    }>;
+}): TourParseResult;
+//# sourceMappingURL=tourParser.d.ts.map

package/dist/utils/tourParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tourParser.d.ts","sourceRoot":"","sources":["../../src/utils/tourParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAwB,MAAM,2BAA2B,CAAC;AAExF;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAG1B,KAAK,CAAC,EAAE,MAAM;aACd,KAAK,CAAC,EAAE,OAAO;gBAF/B,OAAO,EAAE,MAAM,EACC,KAAK,CAAC,EAAE,MAAM,YAAA,EACd,KAAK,CAAC,EAAE,OAAO,YAAA;CAKlC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,MAAM,CAAC,EAAE,mBAAmB,EAAE,CAAC;CAChC;AAkRD;;GAEG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAoC7D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,gBAAgB,CASrE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE;IAAE,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAgBnH;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE;IAC7C,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD,GAAG,eAAe,CAWlB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@industry-theme/file-city-panel",
-  "version": "0.2.70",
+  "version": "0.2.73",
   "description": "File City visualization panel extension for @principal-ade/panel-framework-core",
   "type": "module",
   "main": "dist/panels.bundle.js",