@fgv/ts-res-ui-components 5.0.0-21 → 5.0.0-23

package/src/components/pickers/ResourcePicker/index.tsx

@@ -1,234 +0,0 @@
-import React, { useState, useMemo, useCallback } from 'react';
-import { MagnifyingGlassIcon, ListBulletIcon, FolderIcon } from '@heroicons/react/24/outline';
-import { ResourcePickerProps, ResourceSelection, ResourcePickerOptions } from './types';
-import { ResourcePickerList } from './ResourcePickerList';
-import { ResourcePickerTree } from './ResourcePickerTree';
-import { searchResources, filterTreeBranch } from './utils/treeNavigation';
-
-/**
- * Comprehensive resource picker component with search, view modes, and annotation support.
- *
- * The ResourcePicker provides a flexible interface for browsing and selecting resources
- * from processed resource collections. It supports both list and tree view modes,
- * search functionality, visual annotations, and pending resource management.
- *
- * Key features:
- * - **Multiple view modes**: List view for simple browsing, tree view for hierarchical navigation
- * - **Search functionality**: Search across all resources or within a specific branch
- * - **Visual annotations**: Display badges, indicators, and suffixes for enhanced UX
- * - **Pending resources**: Show unsaved changes alongside persisted resources
- * - **Branch isolation**: Focus on a specific branch node of the resource tree
- * - **Type safety**: Full TypeScript support with generic resource data types
- *
- * @example
- * ```tsx
- * function MyResourceEditor() {
- *   const [selectedId, setSelectedId] = useState<string | null>(null);
- *   const [selectedData, setSelectedData] = useState<MyResourceType | null>(null);
- *
- *   return (
- *     <ResourcePicker<MyResourceType>
- *       resources={processedResources}
- *       selectedResourceId={selectedId}
- *       onResourceSelect={(selection) => {
- *         setSelectedId(selection.resourceId);
- *         setSelectedData(selection.resourceData || null);
- *
- *         if (selection.isPending) {
- *           console.log(`Pending ${selection.pendingType} operation`);
- *         }
- *       }}
- *       defaultView="tree"
- *       enableSearch={true}
- *       searchPlaceholder="Search resources..."
- *       resourceAnnotations={{
- *         'user.welcome': {
- *           badge: { text: '3', variant: 'info' },
- *           suffix: '(3 candidates)'
- *         }
- *       }}
- *       pendingResources={[{
- *         id: 'user.new-item',
- *         type: 'new',
- *         displayName: 'New Welcome Message',
- *         resourceData: { text: 'Hello World!' }
- *       }]}
- *       height="500px"
- *     />
- *   );
- * }
- * ```
- *
- * @public
- */
-export const ResourcePicker = <T = unknown,>({
-  resources,
-  selectedResourceId,
-  onResourceSelect,
-  resourceAnnotations,
-  pendingResources,
-  options,
-  className = '',
-  onMessage
-}: ResourcePickerProps<T>) => {
-  // Extract options with defaults
-  const {
-    defaultView = 'list',
-    showViewToggle = true,
-    rootPath,
-    hideRootNode = false,
-    enableSearch = true,
-    searchPlaceholder,
-    searchScope = 'current-branch',
-    emptyMessage,
-    height = '600px'
-  } = options || {};
-  const [viewMode, setViewMode] = useState<'list' | 'tree'>(defaultView);
-  const [searchTerm, setSearchTerm] = useState('');
-
-  // Get resource IDs based on current filters
-  const resourceIds = useMemo(() => {
-    if (!resources?.summary.resourceIds) {
-      return [];
-    }
-
-    let ids = resources.summary.resourceIds;
-
-    // Apply branch filtering if specified
-    if (rootPath) {
-      ids = filterTreeBranch(ids, rootPath, hideRootNode);
-    }
-
-    // Apply search filtering
-    if (searchTerm) {
-      ids = searchResources(ids, searchTerm, searchScope, rootPath);
-    }
-
-    return ids;
-  }, [resources?.summary.resourceIds, rootPath, hideRootNode, searchTerm, searchScope]);
-
-  // Handle resource selection
-  const handleResourceSelect = useCallback(
-    (selection: ResourceSelection<T>) => {
-      onResourceSelect(selection);
-      if (selection.resourceId) {
-        onMessage?.('info', `Selected resource: ${selection.resourceId}`);
-      }
-    },
-    [onResourceSelect, onMessage]
-  );
-
-  // Calculate dynamic search placeholder
-  const getSearchPlaceholder = () => {
-    if (searchPlaceholder) {
-      return searchPlaceholder;
-    }
-    if (rootPath && hideRootNode) {
-      const segments = rootPath.split('/');
-      const branchName = segments[segments.length - 1];
-      return `Search ${branchName}...`;
-    }
-    return 'Search resources...';
-  };
-
-  // Handle empty state
-  if (!resources) {
-    return (
-      <div className={`${className} p-4 text-center text-gray-500`}>
-        <p>{emptyMessage || 'No resources loaded'}</p>
-      </div>
-    );
-  }
-
-  const containerHeight = typeof height === 'number' ? `${height}px` : height;
-
-  return (
-    <div className={`flex flex-col ${className}`} style={{ height: containerHeight }}>
-      {/* Header with search and view toggle */}
-      {(enableSearch || showViewToggle) && (
-        <div className="flex flex-col gap-3 mb-4">
-          {/* Search Box */}
-          {enableSearch && (
-            <div className="relative">
-              <MagnifyingGlassIcon className="absolute left-3 top-1/2 transform -translate-y-1/2 h-4 w-4 text-gray-400" />
-              <input
-                type="text"
-                placeholder={getSearchPlaceholder()}
-                value={searchTerm}
-                onChange={(e) => setSearchTerm(e.target.value)}
-                className="w-full pl-10 pr-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500 focus:border-transparent text-sm"
-              />
-            </div>
-          )}
-
-          {/* View Mode Toggle */}
-          {showViewToggle && (
-            <div className="flex items-center justify-between">
-              <span className="text-sm text-gray-600">
-                {resourceIds.length} resource{resourceIds.length !== 1 ? 's' : ''}
-                {searchTerm && ` matching "${searchTerm}"`}
-              </span>
-              <div className="flex items-center space-x-1 bg-gray-100 rounded-lg p-1">
-                <button
-                  onClick={() => setViewMode('list')}
-                  className={`flex items-center px-2 py-1 text-xs font-medium rounded transition-colors ${
-                    viewMode === 'list'
-                      ? 'bg-white text-gray-900 shadow-sm'
-                      : 'text-gray-600 hover:text-gray-900'
-                  }`}
-                  title="List View"
-                >
-                  <ListBulletIcon className="h-4 w-4" />
-                  <span className="ml-1">List</span>
-                </button>
-                <button
-                  onClick={() => setViewMode('tree')}
-                  className={`flex items-center px-2 py-1 text-xs font-medium rounded transition-colors ${
-                    viewMode === 'tree'
-                      ? 'bg-white text-gray-900 shadow-sm'
-                      : 'text-gray-600 hover:text-gray-900'
-                  }`}
-                  title="Tree View"
-                >
-                  <FolderIcon className="h-4 w-4" />
-                  <span className="ml-1">Tree</span>
-                </button>
-              </div>
-            </div>
-          )}
-        </div>
-      )}
-
-      {/* Resource List or Tree */}
-      <div className="flex-1 overflow-y-auto border border-gray-200 rounded-lg bg-gray-50">
-        {viewMode === 'tree' ? (
-          <ResourcePickerTree<T>
-            resources={resources}
-            pendingResources={pendingResources}
-            selectedResourceId={selectedResourceId}
-            onResourceSelect={handleResourceSelect}
-            resourceAnnotations={resourceAnnotations}
-            searchTerm={searchTerm}
-            rootPath={rootPath}
-            hideRootNode={hideRootNode}
-            emptyMessage={emptyMessage}
-          />
-        ) : (
-          <ResourcePickerList<T>
-            resourceIds={resources.summary.resourceIds || []}
-            pendingResources={pendingResources}
-            selectedResourceId={selectedResourceId}
-            onResourceSelect={handleResourceSelect}
-            resourceAnnotations={resourceAnnotations}
-            searchTerm={searchTerm}
-            rootPath={rootPath}
-            hideRootNode={hideRootNode}
-            emptyMessage={emptyMessage}
-          />
-        )}
-      </div>
-    </div>
-  );
-};
-
-export default ResourcePicker;

package/src/components/pickers/ResourcePicker/types.ts

@@ -1,301 +0,0 @@
-import React from 'react';
-import { ProcessedResources, ExtendedProcessedResources, ViewBaseProps } from '../../../types';
-
-/**
- * Resource selection data returned by the onResourceSelect callback.
- *
- * This interface provides comprehensive information about the selected resource,
- * eliminating the need for consumers to perform additional lookups.
- *
- * @example
- * ```tsx
- * const handleResourceSelect = (selection: ResourceSelection<MyResourceType>) => {
- *   if (selection.resourceId) {
- *     console.log('Selected:', selection.resourceId);
- *     if (selection.resourceData) {
- *       console.log('Data:', selection.resourceData);
- *     }
- *     if (selection.isPending) {
- *       console.log('Pending operation:', selection.pendingType);
- *     }
- *   }
- * };
- * ```
- *
- * @public
- */
-export interface ResourceSelection<T = unknown> {
-  /** The ID of the selected resource, or null if no selection */
-  resourceId: string | null;
-  /** The actual resource data if available and typed */
-  resourceData?: T;
-  /** Whether this is a pending (unsaved) resource */
-  isPending?: boolean;
-  /** Type of pending operation for unsaved resources */
-  pendingType?: 'new' | 'modified' | 'deleted';
-}
-
-/**
- * UI behavior configuration options for ResourcePicker.
- *
- * This interface groups all UI-related options that control how the ResourcePicker
- * behaves and appears, separate from functional data like annotations and pending resources.
- *
- * @example
- * ```tsx
- * const pickerOptions: ResourcePickerOptions = {
- *   defaultView: 'tree',
- *   enableSearch: true,
- *   searchPlaceholder: 'Find resources...',
- *   rootPath: 'user.messages',
- *   hideRootNode: true,
- *   height: '400px'
- * };
- * ```
- *
- * @public
- */
-export interface ResourcePickerOptions {
-  /** View and navigation options */
-  /** Default view mode to use on initial render */
-  defaultView?: 'list' | 'tree';
-  /** Whether to show the list/tree view toggle buttons */
-  showViewToggle?: boolean;
-
-  /** Branch isolation options */
-  /** Path to treat as root for tree branch isolation (e.g., "platform/territories") */
-  rootPath?: string;
-  /** Hide the root node itself, showing only its children */
-  hideRootNode?: boolean;
-
-  /** Search options */
-  /** Whether to enable the search input */
-  enableSearch?: boolean;
-  /** Placeholder text for the search input */
-  searchPlaceholder?: string;
-  /** Scope of search - entire tree or just the currently visible branch */
-  searchScope?: 'all' | 'current-branch';
-
-  /** Appearance options */
-  /** Message to display when no resources are available */
-  emptyMessage?: string;
-  /** Height of the picker component */
-  height?: string | number;
-}
-
-/**
- * Props for the ResourcePicker component.
- *
- * The ResourcePicker is a comprehensive component for browsing and selecting resources
- * with support for multiple view modes, search, annotations, and pending resources.
- * UI behavior is controlled through the options object, while functional data is
- * passed as separate props.
- *
- * @example
- * ```tsx
- * <ResourcePicker
- *   resources={processedResources}
- *   selectedResourceId={currentId}
- *   onResourceSelect={(selection) => {
- *     setCurrentId(selection.resourceId);
- *     if (selection.resourceData) {
- *       // Use the resource data directly
- *       handleResourceData(selection.resourceData);
- *     }
- *   }}
- *   resourceAnnotations={{
- *     'res1': { badge: { text: '3', variant: 'info' } }
- *   }}
- *   options={{
- *     defaultView: 'tree',
- *     enableSearch: true,
- *     searchPlaceholder: 'Find resources...',
- *     height: '400px'
- *   }}
- * />
- * ```
- *
- * @public
- */
-export interface ResourcePickerProps<T = unknown> extends ViewBaseProps {
-  /** Core functionality */
-  /** Processed resources to display in the picker */
-  resources: ProcessedResources | ExtendedProcessedResources | null;
-  /** Currently selected resource ID */
-  selectedResourceId: string | null;
-  /** Callback fired when a resource is selected, providing comprehensive selection data */
-  onResourceSelect: (selection: ResourceSelection<T>) => void;
-
-  /** Functional data */
-  /** Annotations to display next to resource names (badges, indicators, etc.) */
-  resourceAnnotations?: ResourceAnnotations;
-  /** Pending (unsaved) resources to display alongside persisted resources */
-  pendingResources?: PendingResource<T>[];
-
-  /** UI behavior configuration */
-  /** Options controlling picker appearance and behavior */
-  options?: ResourcePickerOptions;
-}
-
-/**
- * Annotations that can be displayed next to resource names in the picker.
- *
- * This allows the host application to provide visual indicators for resources,
- * such as candidate counts, editing status, or validation states.
- *
- * @example
- * ```tsx
- * const annotations: ResourceAnnotations = {
- *   'user.welcome': {
- *     badge: { text: '3', variant: 'info' },
- *     suffix: '(3 candidates)'
- *   },
- *   'user.modified': {
- *     badge: { text: 'M', variant: 'edited' },
- *     indicator: { type: 'dot', value: 'orange', tooltip: 'Modified' }
- *   }
- * };
- * ```
- *
- * @public
- */
-export interface ResourceAnnotations {
-  /** Map of resource IDs to their annotation configurations */
-  [resourceId: string]: ResourceAnnotation;
-}
-
-/**
- * Individual resource annotation configuration.
- *
- * Supports multiple types of visual indicators that can be combined:
- * - Badge: Small colored badge with text
- * - Indicator: Dot, icon, or text indicator with optional tooltip
- * - Suffix: Additional content displayed after the resource name
- *
- * @example
- * ```tsx
- * const annotation: ResourceAnnotation = {
- *   badge: { text: 'NEW', variant: 'new' },
- *   indicator: {
- *     type: 'icon',
- *     value: <CheckIcon />,
- *     tooltip: 'Validated'
- *   },
- *   suffix: <span className="text-gray-500">(5 candidates)</span>,
- *   className: 'resource-highlighted'
- * };
- * ```
- *
- * @public
- */
-export interface ResourceAnnotation {
-  /** Small colored badge displayed next to the resource name */
-  badge?: {
-    /** Text content of the badge */
-    text: string;
-    /** Visual style variant for the badge */
-    variant: 'info' | 'warning' | 'success' | 'error' | 'edited' | 'new';
-  };
-  /** Visual indicator (dot, icon, or text) with optional tooltip */
-  indicator?: {
-    /** Type of indicator to display */
-    type: 'dot' | 'icon' | 'text';
-    /** Content of the indicator (color for dot, React element for icon, string for text) */
-    value: string | React.ReactNode;
-    /** Optional tooltip text shown on hover */
-    tooltip?: string;
-  };
-  /** Additional content displayed after the resource name (e.g., candidate counts) */
-  suffix?: React.ReactNode;
-  /** Additional CSS class names to apply to the resource item */
-  className?: string;
-}
-
-/**
- * Represents a resource that hasn't been persisted yet.
- *
- * Pending resources are displayed alongside persisted resources in the picker,
- * allowing users to interact with unsaved changes. They are visually distinguished
- * with appropriate styling and annotations.
- *
- * @example
- * ```tsx
- * const pendingResources: PendingResource<MyResourceType>[] = [
- *   {
- *     id: 'user.new-welcome',
- *     type: 'new',
- *     resourceType: 'string',
- *     displayName: 'Welcome Message (New)',
- *     resourceData: { text: 'Welcome!', locale: 'en' }
- *   },
- *   {
- *     id: 'user.existing-modified',
- *     type: 'modified',
- *     displayName: 'User Profile (Modified)',
- *     resourceData: { name: 'Updated Name' }
- *   }
- * ];
- * ```
- *
- * @public
- */
-export interface PendingResource<T = unknown> {
-  /** Unique identifier for the pending resource */
-  id: string;
-  /** Type of pending operation */
-  type: 'new' | 'modified' | 'deleted';
-  /** Optional resource type identifier */
-  resourceType?: string;
-  /** Display name for the resource in the picker */
-  displayName?: string;
-  /** The actual resource data with type safety */
-  resourceData?: T;
-}
-
-/**
- * Props for individual resource items
- */
-export interface ResourceItemProps<T = unknown> {
-  resourceId: string;
-  displayName?: string;
-  isSelected: boolean;
-  isPending?: boolean;
-  annotation?: ResourceAnnotation;
-  onClick: (selection: ResourceSelection<T>) => void;
-  searchTerm?: string;
-  className?: string;
-  resourceData?: T; // The actual resource data if available
-  pendingType?: 'new' | 'modified' | 'deleted'; // Type of pending operation
-}
-
-/**
- * Props for the list view component
- */
-export interface ResourcePickerListProps<T = unknown> {
-  resourceIds: string[];
-  pendingResources?: PendingResource<T>[];
-  selectedResourceId: string | null;
-  onResourceSelect: (selection: ResourceSelection<T>) => void;
-  resourceAnnotations?: ResourceAnnotations;
-  searchTerm?: string;
-  rootPath?: string;
-  hideRootNode?: boolean;
-  className?: string;
-  emptyMessage?: string;
-}
-
-/**
- * Props for the tree view component
- */
-export interface ResourcePickerTreeProps<T = unknown> {
-  resources: ProcessedResources | ExtendedProcessedResources;
-  pendingResources?: PendingResource<T>[];
-  selectedResourceId: string | null;
-  onResourceSelect: (selection: ResourceSelection<T>) => void;
-  resourceAnnotations?: ResourceAnnotations;
-  searchTerm?: string;
-  rootPath?: string;
-  hideRootNode?: boolean;
-  className?: string;
-  emptyMessage?: string;
-}