ds-component-restructure

ds-component-restructure

Restructure a ds-react component folder to follow canonical conventions — without breaking the public API.

Canonical Structure

<component>/
├── index.ts                          # "use client" + re-exports from root
├── <Component>.stories.tsx           # Storybook stories
├── <Component>.tests.stories.tsx     # Storybook play-tests (only if play tests exist)
├── <Component>.meta.ts               # Meta info for component. Used for documentation generation.
├── root/
│   ├── <Component>Root.tsx           # Main compound component + sub-component namespace
│   ├── <Component>Root.context.ts    # Context (if shared across sub-components)
│   ├── <Component>Root.test.ts       # Unit tests for root (if needed)
│   └── use<Hook>.ts                  # Files for root-level hooks (if needed)
├── <subcomponent>/                   # One dir per sub-component
│   ├── <Component><Subcomponent>.tsx
│   ├── <Component><Subcomponent>.test.ts  # Unit tests for sub-component (if needed)
│   └── use<Hook>.ts                       # Files for sub-component-level hooks (if needed)
├── helpers/
│   ├── <helper-name>.ts
│   └── <helper-name>.test.ts         # Unit tests co-located with helper
└── <Component>.types.ts              # Shared types (if needed across multiple files)

Naming Rules

Procedure

1. Read the Component

Read every file in the component folder — index.ts, all .tsx/.ts source files, meta file, stories, and test stories. Ignore inconsistencies in file naming and structure; the goal is to fix those, not preserve them. Use the component-field in the meta file to determine the proper naming if unsure.

Done when: every file's role (component, hook, type, context, test, metadata) is known, and every symbol currently exported from index.ts is recorded.

2. Map Files to Target Structure

Build this table before touching any files:

For each file:

• Determine new path and whether it moves/renames
• Check whether content needs splitting (e.g. types → <Component>.types.ts)
• List every file that imports it (grep for the filename or exported symbol)
• Flag circular dep risks: context importing sub-components, helpers importing component files, types importing non-types

Resolve circular deps before proceeding: move shared pieces to a lower-level file (types → .types.ts, utilities → helpers/).

Done when: every file in the component folder has a row in the table, and every circular-dependency risk is resolved or explicitly noted.

3. Create New Files

For each row in the mapping table where the path changes:

1. Create the file at the new path with all import paths updated to reflect new locations
2. Update every file in the "Importers to update" column — use the mapping table, don't rely on memory
3. Do NOT delete old files yet

Case-only renames (path differs only in letter casing, e.g. heading.stories.tsx → Heading.stories.tsx) must NOT use the create-new + delete-old flow. On case-insensitive filesystems (macOS and Windows default) the two paths resolve to the same file, so creating the new file overwrites the old and the later "delete old" step destroys your content — and git records no rename. Handle these with the two-step git mv in the Case-only renames edge case instead.

4. Update Stories

Move stories to component root dir. If stories import from internal paths, update those paths.

Exception: A stories/ subdirectory is acceptable if it already exists — do not flatten it.

Casing: Story filenames follow <Component>.stories.tsx (PascalCase). When the existing file is lowercase (e.g. heading.stories.tsx), this is a case-only rename — follow the Case-only renames procedure, do not create + delete.

5. Update index.ts

All exports are named — no default exports anywhere. The component index.ts re-exports the compound component, its sub-components, and their types from the root file:

"use client";
export {
  <Component>,                   // compound root (named)
  <Component>Trigger,            // sub-components (named)
  // ...
} from "./root/<Component>Root";
export type {
  <Component>Props,
  <Component>TriggerProps,
  // ...
} from "./root/<Component>Root";

Group values first, then types. If types live in <Component>.types.ts, re-export them from there.

Compound root file export pattern

In <Component>Root.tsx, assemble the compound component with Object.assign — do not use an as <Component>Component cast or a dedicated <Component>Component interface:

const <Component>Root = forwardRef<HTMLDivElement, <Component>Props>((props, ref) => {
  // ...
});

/**
 * Component-level JSDoc (description, `@see`, `@example`) goes directly
 * above the `Object.assign` — this is the exported `<Component>` value.
 */
const <Component> = Object.assign(<Component>Root, {
  /**
   * @see 🏷️ {@link <Component>TriggerProps}
   */
  Trigger: <Component>Trigger,
  // ...
});

export { <Component>, <Component>Trigger };
export type { <Component>Props, <Component>TriggerProps };

Why Object.assign instead of as: the cast types the const as an interface that has no runtime valueDeclaration, so react-docgen-typescript (used by yarn docgen:meta) fails to extract props and can't document the component when it is exported via a grouped export { } statement. Object.assign lets TypeScript infer the intersection type from the value, so metadata generation works with named, bottom-of-file exports.

Sub-component files follow the same rule — named value export plus named type export at the bottom, no inline export interface and no default:

interface <Component>TriggerProps extends React.HTMLAttributes<HTMLDivElement> {
  // ...
}

const <Component>Trigger = forwardRef<HTMLDivElement, <Component>TriggerProps>(/* ... */);

export { <Component>Trigger };
export type { <Component>TriggerProps };

6. Update Meta File

Update imports in <Component>.meta.ts to reflect new paths. If the meta file imports from the component's index.ts, no changes are needed.

If component has no meta file, create one in the component root with the following content based on existing patterns. Note that each standalone component should have a meta file. But a "sub-component" (like AccordionItem) does not need a meta file.

### 7. Validate No Breaking Changes

**Export diff.** Before deleting old files, compare the exported names recorded during Step 1 against the new `index.ts`. Every name must be present:

- Exports in new index.ts that are missing from original → regression
- Exports in original that are missing from new index.ts → missing export (breaking change)

Concretely: grep for `export` lines in both versions and diff them. All component names and type names must match exactly.

**Build.** Run `yarn workspace @navikt/ds-react build` — must succeed with no TypeScript errors.

**Package root.** Verify `@navikt/core/react/src/index.ts` still re-exports the component. No changes needed there unless the component's `index.ts` path changed (it shouldn't).

**No case-duplicate tracked paths.** This is the most common restructure bug. On case-insensitive filesystems (macOS, Windows) git can end up tracking **two** entries that differ only in casing (e.g. `accordion.stories.tsx` **and** `Accordion.stories.tsx`) while the working tree shows only one file. The stale entry then breaks tests and checkout on other machines. `ls` / file search will NOT reveal it — you must ask git. Run:

```sh
git ls-files | awk '{l=tolower($0); if(seen[l]++) print "CASE-DUP:", $0}'
```

Any output is a leftover. Remove the stale entry from the index by its **exact old path** (this does not touch the correctly-cased file on disk):

```sh
git rm --cached '<exact old lowercase path>'
```

Then confirm only the intended casing remains, e.g. `git ls-files '*<component>*stories*'`.

**Done when:** the export diff is empty, the build succeeds, the package-root re-export is verified, and `git ls-files` reports no case-duplicate paths.

### 8. Remove Old Files

Only after verifying new files are correct and `in

---

*Content truncated.*