refactor: replace index files with named files for improved clarity and maintainability TCKT-404 (#633)

* refactor: replace index files with named files for improved clarity and maintainability TCKT-404

* docs: add ADR for using named exports and avoiding index files TCKT-404

Author: kalasgarov

documents/adr/0017-use-named-exports.md

@@ -0,0 +1,50 @@
+# ADR 0017: Use Named Exports Over Default Exports and Avoid index Files
+
+Date: 04-16-2025
+
+## Status
+Approved
+
+## Context
+During the recent refactoring of the `Form` and `FormManager` components in the `design` package, we noticed inconsistencies in the use of default exports, named exports, and `index` files. Some files used default exports, while others used named exports. Additionally, many directories relied on `index.tsx` files, which made it harder to locate specific components or utilities in the codebase.
+
+Default exports can sometimes lead to ambiguity, especially when renaming imports, and they do not provide the same level of tooling support (e.g., auto-imports in IDEs) as named exports. Named exports, on the other hand, make it clear what is being exported and allow for more consistent imports across the codebase.
+
+Similarly, `index` files can introduce ambiguity when navigating the codebase, as multiple `index.tsx` files across different directories make it harder to locate specific functionality. Using descriptive file names improves clarity and maintainability.
+
+## Decision
+We will adopt the following guidelines for exports and file structure moving forward:
+1. **Use named exports** for all components, utilities, and types.
+2. **Avoid default exports**, except in cases where a file exports a single, primary entity (e.g., a React component that represents the main purpose of the file).
+3. **Avoid `index` files** in favor of descriptive file names (e.g., `FormManager.tsx` instead of `index.tsx`).
+
+## Consequences
+- **Consistency:** The codebase will have a consistent export style and file structure, making it easier to read and maintain.
+- **Tooling Support:** Named exports improve IDE tooling, such as auto-imports and refactoring.
+- **Clarity:** Named exports and descriptive file names make it clear what is being exported and where functionality resides, reducing ambiguity.
+- **Ease of Navigation:** Avoiding `index` files ensures that file names are descriptive, making it easier to locate specific components or utilities.
+
+## Examples
+### Before (Default Export):
+```tsx
+// FormManager.tsx
+export default function FormManager() { ... }
+
+// Importing in other files
+import FormManager from './FormManager';
+```
+
+### After (Named Export):
+```tsx
+// FormManager.tsx
+export function FormManager() { ... }
+
+// Importing in other files
+import { FormManager } from './FormManager';
+```
+
+## Related Changes
+This decision was applied during the refactoring of the `Form` and `FormManager` components in the design package. As part of this refactor:
+
+- Default exports were replaced with named exports.
+- `index.tsx` files were replaced with descriptive file names (e.g., `FormManager.tsx`, `PatternComponents.tsx`).

packages/design/src/Form/Form.stories.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import type { Meta, StoryObj } from '@storybook/react';
 
-import Form from './index.js';
+import Form from './Form.js';
 import { createTestFormContext, createTestSession } from '../test-form.js';
 import { MemoryRouter } from 'react-router-dom';
 

packages/design/src/Form/index.tsx packages/design/src/Form/Form.tsxpackages/design/src/Form/index.tsx renamed to packages/design/src/Form/Form.tsx

@@ -8,30 +8,10 @@ import {
   type FormConfig,
   type FormRoute,
   type FormSession,
-  type PatternProps,
   type Prompt,
-  type PromptComponent,
 } from '@gsa-tts/forms-core';
 import { renderPromptComponents } from './form-common.js';
-
-export type FormUIContext = {
-  config: FormConfig;
-  components: ComponentForPattern;
-  uswdsRoot: `${string}/`;
-};
-
-export type ComponentForPattern<T extends PatternProps = PatternProps> = Record<
-  string,
-  PatternComponent<T>
->;
-
-export type PatternComponent<T extends PatternProps = PatternProps<unknown>> =
-  React.ComponentType<
-    T & {
-      context: FormUIContext;
-      childComponents?: PromptComponent[];
-    }
-  >;
+import { FormUIContext } from './types.js';
 
 const usePrompt = (
   initialPrompt: Prompt,

packages/design/src/Form/components/AccordionRow/AccordionRow.stories.tsx

@@ -1,7 +1,7 @@
 import React from 'react';
 import { type Meta, type StoryObj } from '@storybook/react';
 
-import AccordionRow from './index.js';
+import AccordionRow from './AccordionRow.js';
 
 const meta: Meta<typeof AccordionRow> = {
   title: 'patterns/AccordionRow',

…c/Form/components/AccordionRow/index.tsx …components/AccordionRow/AccordionRow.tsxpackages/design/src/Form/components/AccordionRow/index.tsx renamed to packages/design/src/Form/components/AccordionRow/AccordionRow.tsx packages/design/src/Form/components/AccordionRow/index.tsx renamed to packages/design/src/Form/components/AccordionRow/AccordionRow.tsx

@@ -2,7 +2,7 @@ import React, { useState } from 'react';
 import classNames from 'classnames';
 
 import { type AccordionRowProps } from '@gsa-tts/forms-core';
-import { type PatternComponent } from '../../index.js';
+import { type PatternComponent } from '../../types.js';
 
 const AccordionRow: PatternComponent<AccordionRowProps> = ({
   inputId,

packages/design/src/Form/components/Address/Address.stories.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import { FormProvider, useForm } from 'react-hook-form';
 import { type Meta, type StoryObj } from '@storybook/react';
 
-import AddressPattern from './index.js';
+import AddressPattern from './Address.js';
 import { stateTerritoryOrMilitaryPostList } from '@gsa-tts/forms-core';
 
 const meta: Meta<typeof AddressPattern> = {

…gn/src/Form/components/Address/index.tsx …/src/Form/components/Address/Address.tsxpackages/design/src/Form/components/Address/index.tsx renamed to packages/design/src/Form/components/Address/Address.tsx packages/design/src/Form/components/Address/index.tsx renamed to packages/design/src/Form/components/Address/Address.tsx

@@ -4,7 +4,7 @@ import { useFormContext } from 'react-hook-form';
 
 import { type AddressComponentProps } from '@gsa-tts/forms-core';
 
-import { type PatternComponent } from '../../index.js';
+import { type PatternComponent } from '../../types.js';
 
 const AddressPattern: PatternComponent<AddressComponentProps> = ({
   childProps,

packages/design/src/Form/components/Attachment/Attachment.stories.tsx

@@ -6,7 +6,7 @@ import { type AttachmentProps } from '@gsa-tts/forms-core';
 import { FormProvider, useForm } from 'react-hook-form';
 import type { Meta, StoryObj } from '@storybook/react';
 
-import Attachment from './index.js';
+import Attachment from './Attachment.js';
 
 const defaultArgs = {
   _patternId: '',

…src/Form/components/Attachment/index.tsx …orm/components/Attachment/Attachment.tsxpackages/design/src/Form/components/Attachment/index.tsx renamed to packages/design/src/Form/components/Attachment/Attachment.tsx packages/design/src/Form/components/Attachment/index.tsx renamed to packages/design/src/Form/components/Attachment/Attachment.tsx

@@ -3,7 +3,7 @@ import React, { useState } from 'react';
 import { useFormContext } from 'react-hook-form';
 import { type AttachmentProps } from '@gsa-tts/forms-core';
 import { attachmentFileTypeOptions } from '@gsa-tts/forms-core';
-import { type PatternComponent } from '../../../Form/index.js';
+import { type PatternComponent } from '../../types.js';
 
 const Attachment: PatternComponent<AttachmentProps> = props => {
   const { register } = useFormContext();

packages/design/src/Form/components/Checkbox/Checkbox.stories.tsx

@@ -2,7 +2,7 @@ import React from 'react';
 import { FormProvider, useForm } from 'react-hook-form';
 import { type Meta, type StoryObj } from '@storybook/react';
 
-import { CheckboxPattern } from './Checkbox.js';
+import CheckboxPattern from './Checkbox.js';
 import { CheckboxProps } from '@gsa-tts/forms-core';
 
 const meta: Meta<typeof CheckboxPattern> = {