+
)}
diff --git a/workspaces/bulk-import/plugins/bulk-import/src/components/AddRepositories/ConfigurableInstructions.tsx b/workspaces/bulk-import/plugins/bulk-import/src/components/AddRepositories/ConfigurableInstructions.tsx
new file mode 100644
index 0000000000..8b5af326d7
--- /dev/null
+++ b/workspaces/bulk-import/plugins/bulk-import/src/components/AddRepositories/ConfigurableInstructions.tsx
@@ -0,0 +1,129 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useMemo } from 'react';
+
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import Accordion from '@mui/material/Accordion';
+import AccordionDetails from '@mui/material/AccordionDetails';
+import AccordionSummary from '@mui/material/AccordionSummary';
+import Box from '@mui/material/Box';
+import { useTheme } from '@mui/material/styles';
+import Typography from '@mui/material/Typography';
+
+import { useInstructionsConfig, useInstructionsPreference } from '../../hooks';
+import { useTranslation } from '../../hooks/useTranslation';
+import { InstructionIcon } from './InstructionIcon';
+
+/**
+ * Configurable instructions component that displays the "How does it work" section
+ * based on configuration from app-config.yaml and user preferences
+ */
+export const ConfigurableInstructions = () => {
+ const theme = useTheme();
+ const { t } = useTranslation();
+ const config = useInstructionsConfig();
+ const [isExpanded, setExpanded] = useInstructionsPreference(
+ config.defaultExpanded,
+ );
+
+ // Build the list of steps based on configuration from app-config.yaml
+ const steps = useMemo(() => {
+ return config.steps.map(configStep => ({
+ id: configStep.id,
+ text: configStep.text,
+ icon: configStep.icon,
+ }));
+ }, [config.steps]);
+
+ // Don't render if disabled or no steps configured
+ if (!config.enabled || steps.length === 0) {
+ return null;
+ }
+
+ const title = t('page.importEntitiesSubtitle');
+
+ return (
+
+ );
+};
diff --git a/workspaces/bulk-import/plugins/bulk-import/src/components/AddRepositories/InstructionIcon.tsx b/workspaces/bulk-import/plugins/bulk-import/src/components/AddRepositories/InstructionIcon.tsx
new file mode 100644
index 0000000000..28ba221454
--- /dev/null
+++ b/workspaces/bulk-import/plugins/bulk-import/src/components/AddRepositories/InstructionIcon.tsx
@@ -0,0 +1,204 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { isValidElement } from 'react';
+
+import { useApp } from '@backstage/core-plugin-api';
+
+import MuiIcon from '@mui/material/Icon';
+import { useTheme } from '@mui/material/styles';
+import Typography from '@mui/material/Typography';
+
+import { getImageForIconClass } from '../../utils/icons';
+
+export interface InstructionIconProps {
+ icon?: string;
+ text: string;
+}
+
+/**
+ * Icon component for instruction steps that supports multiple icon formats:
+ * - Backstage system icons (e.g., 'kind:component', 'kind:api')
+ * - Material Design icons (e.g., 'settings', 'home', 'build')
+ * - SVG strings (e.g., '')
+ * - URLs (e.g., 'https://example.com/icon.png', '/assets/icon.svg')
+ * - Data URIs (e.g., 'data:image/svg+xml;base64,...')
+ * - Legacy built-in icons (e.g., 'approval-tool', 'choose-repositories')
+ */
+export const InstructionIcon = ({ icon, text }: InstructionIconProps) => {
+ const app = useApp();
+ const theme = useTheme();
+
+ // Common wrapper for consistent layout
+ const IconWrapper = ({ children }: { children: React.ReactNode }) => (
+
+
+ {children}
+
+
+ {text}
+
+
+ );
+
+ // If no icon is provided, show only text with consistent spacing
+ if (!icon) {
+ return (
+
+
+
+ );
+ }
+
+ // Handle React elements (though not expected from config)
+ if (isValidElement(icon)) {
+ return {icon};
+ }
+
+ const strIcon = icon as string;
+
+ // Ensure we have a valid string
+ if (typeof strIcon !== 'string') {
+ return (
+
+
+
+ );
+ }
+
+ // Try Backstage system icons first
+ const SystemIcon = app.getSystemIcon(strIcon);
+ if (SystemIcon) {
+ return (
+
+
+
+
+
+ );
+ }
+
+ // Handle SVG strings
+ if (strIcon.startsWith('
+
+
+ );
+ }
+
+ // Handle URLs and data URIs
+ if (
+ strIcon.startsWith('https://') ||
+ strIcon.startsWith('http://') ||
+ strIcon.startsWith('/') ||
+ strIcon.startsWith('data:image/')
+ ) {
+ return (
+
+
+
+ );
+ }
+
+ // Check for legacy built-in icons (backward compatibility)
+ const legacyIcons = [
+ 'approval-tool',
+ 'choose-repositories',
+ 'generate-cataloginfo',
+ 'edit-pullrequest',
+ 'track-status',
+ ];
+
+ if (legacyIcons.includes(strIcon)) {
+ // Use theme-aware legacy icons
+ const iconClassname =
+ theme.palette.mode === 'dark'
+ ? `icon-${strIcon}-white`
+ : `icon-${strIcon}-black`;
+
+ return (
+
+
+
+ );
+ }
+
+ // Fallback: treat as Material Design icon name
+ return (
+
+
+ {strIcon}
+
+
+ );
+};
diff --git a/workspaces/bulk-import/plugins/bulk-import/src/hooks/index.ts b/workspaces/bulk-import/plugins/bulk-import/src/hooks/index.ts
index 39a4af9da9..8e2a1d37ea 100644
--- a/workspaces/bulk-import/plugins/bulk-import/src/hooks/index.ts
+++ b/workspaces/bulk-import/plugins/bulk-import/src/hooks/index.ts
@@ -15,6 +15,8 @@
*/
export { useAddedRepositories } from './useAddedRepositories';
+export { useInstructionsConfig } from './useInstructionsConfig';
+export { useInstructionsPreference } from './useInstructionsPreference';
export { useRepositories } from './useRepositories';
export {
useNumberOfApprovalTools,
diff --git a/workspaces/bulk-import/plugins/bulk-import/src/hooks/useInstructionsConfig.ts b/workspaces/bulk-import/plugins/bulk-import/src/hooks/useInstructionsConfig.ts
new file mode 100644
index 0000000000..0bbb1e8a3f
--- /dev/null
+++ b/workspaces/bulk-import/plugins/bulk-import/src/hooks/useInstructionsConfig.ts
@@ -0,0 +1,113 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { configApiRef, useApi } from '@backstage/core-plugin-api';
+
+export interface InstructionsStep {
+ id: string;
+ text: string;
+ icon?: string;
+}
+
+export interface InstructionsConfig {
+ enabled: boolean;
+ defaultExpanded: boolean;
+ steps: InstructionsStep[];
+}
+
+/**
+ * Hook to get instructions configuration from app-config.yaml
+ */
+export function useInstructionsConfig(): InstructionsConfig {
+ const configApi = useApi(configApiRef);
+ const bulkImportConfig = configApi.getOptionalConfig('bulkImport');
+ const instructionsEnabled =
+ configApi.getOptionalBoolean('bulkImport.instructionsEnabled') ?? true;
+ const instructionsDefaultExpanded =
+ configApi.getOptionalBoolean('bulkImport.instructionsDefaultExpanded') ??
+ true;
+ let instructionsSteps =
+ configApi.getOptionalConfigArray('bulkImport.instructionsSteps') ?? [];
+
+ if (instructionsSteps.length === 0 && bulkImportConfig) {
+ instructionsSteps =
+ bulkImportConfig.getOptionalConfigArray('instructionsSteps') ?? [];
+
+ // If still empty, try accessing the raw data (bypass schema validation)
+ if (instructionsSteps.length === 0) {
+ try {
+ const rawData = (bulkImportConfig as any).data;
+ if (
+ rawData &&
+ rawData.instructionsSteps &&
+ Array.isArray(rawData.instructionsSteps)
+ ) {
+ // Convert raw data to InstructionsStep format
+ instructionsSteps = rawData.instructionsSteps.map((step: any) => ({
+ id: step.id,
+ text: step.text,
+ icon: step.icon
+ ? {
+ type: step.icon.type as 'builtin' | 'url',
+ source: step.icon.source,
+ }
+ : undefined,
+ }));
+ }
+ } catch (error) {
+ // Silently handle config access errors
+ }
+ }
+ }
+
+ // Use the flat config values
+ const enabled = instructionsEnabled;
+ const defaultExpanded = instructionsDefaultExpanded;
+ let stepsConfig = instructionsSteps;
+
+ // Legacy fallback approach (no longer needed with current config structure)
+ if (stepsConfig.length === 0) {
+ // Try accessing via bulkImport config object
+ const legacyBulkImportConfig = configApi.getOptionalConfig('bulkImport');
+ if (legacyBulkImportConfig) {
+ const instructionsConfig =
+ legacyBulkImportConfig.getOptionalConfig('instructions');
+ if (instructionsConfig) {
+ stepsConfig = instructionsConfig.getOptionalConfigArray('steps') ?? [];
+ }
+ }
+ }
+
+ const steps: InstructionsStep[] =
+ stepsConfig.length > 0
+ ? stepsConfig.map(stepConfig => ({
+ id: stepConfig.getString('id'),
+ text: stepConfig.getString('text'),
+ icon: stepConfig.has('icon')
+ ? stepConfig.getString('icon')
+ : undefined,
+ }))
+ : []; // No fallback needed - config should work now
+
+ // Use config steps directly - no hardcoded fallback
+ const finalSteps = steps;
+
+ return {
+ enabled,
+ defaultExpanded,
+ steps: finalSteps,
+ };
+}
diff --git a/workspaces/bulk-import/plugins/bulk-import/src/hooks/useInstructionsPreference.ts b/workspaces/bulk-import/plugins/bulk-import/src/hooks/useInstructionsPreference.ts
new file mode 100644
index 0000000000..dd9bdbf235
--- /dev/null
+++ b/workspaces/bulk-import/plugins/bulk-import/src/hooks/useInstructionsPreference.ts
@@ -0,0 +1,62 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+
+const STORAGE_KEY = 'bulk-import-instructions-expanded';
+
+/**
+ * Hook to manage user preference for instructions section expanded state
+ * Persists the state in localStorage
+ */
+export function useInstructionsPreference(
+ defaultExpanded: boolean,
+): [boolean, (expanded: boolean) => void] {
+ const [isExpanded, setIsExpanded] = useState(() => {
+ try {
+ const stored = localStorage.getItem(STORAGE_KEY);
+ return stored !== null ? JSON.parse(stored) : defaultExpanded;
+ } catch {
+ // If there's an error reading from localStorage, use the default
+ return defaultExpanded;
+ }
+ });
+
+ const setExpanded = useCallback((expanded: boolean) => {
+ setIsExpanded(expanded);
+ try {
+ localStorage.setItem(STORAGE_KEY, JSON.stringify(expanded));
+ } catch {
+ // Silently fail if localStorage is not available
+ // The state will still work for the current session
+ }
+ }, []);
+
+ // Update state if defaultExpanded changes and no user preference is stored
+ useEffect(() => {
+ try {
+ const stored = localStorage.getItem(STORAGE_KEY);
+ if (stored === null) {
+ setIsExpanded(defaultExpanded);
+ }
+ } catch {
+ // If localStorage is not available, just use the default
+ setIsExpanded(defaultExpanded);
+ }
+ }, [defaultExpanded]);
+
+ return [isExpanded, setExpanded];
+}