Branch Merge Analysis: callil/storybook-ia-refactor

Date: 2026-03-17 Source branch: callil/storybook-ia-refactor (base commit: 2827fd5) Target branch: jmpicnic/list-view-management-620 (head: 94585cb)

1. Unique Contributions in callil/storybook-ia-refactor

The branch contains three categories of changes, none of which overlap with the List View Component work.

1.1 Use Case Story Framework (new)

A new 780-line DSL-like toolkit at src/use-cases/framework.tsx that replaces ad-hoc story patterns with a declarative, minimal-boilerplate system.

Exported constructs:

Export	Kind	Purpose
GuideEntry	Type	Metadata for guide panels (title, description, interaction)
Scene<T>	Type	Snapshot in a stepwise walkthrough (wizard state + guide entry)
WizardProps<T>	Type	Props injected by framework viewers
PlayContext	Type	Context passed to play callbacks (canvas, goToScene, delay)
UseCaseConfig<T>	Type	Full configuration object for story creation
useWizard()	Hook	Manages wizard state (step, submitted, formData)
FormField, FormSelect, FormRow	Component	Basic form controls
SummaryCard, SummaryRow, Divider	Component	Review/summary layout
SuccessScreen	Component	Terminal success state
GuidePanel	Component	Contextual guide display
StoryControlBar	Component	Scene navigation (Previous/Next/Reset)
StepIndicator	Component	Progress visualization
UseCaseShell	Component	Main container for all chrome
createUseCaseStories<T>()	Factory	Returns { Interactive, Stepwise, Automated } story variants
formatCurrency()	Utility	Formatting helper

Key design decisions:

• One UseCaseConfig<T> declaration produces three story modes (Interactive, Stepwise, Automated)
• Scene snapshots decouple walkthrough from implementation
• Automated mode uses CustomEvent('scene-change') for play-function progression
• Generic <T> ensures type-safe form state across scenes

Demonstrated in: create-supplier/happy-path.stories.tsx — reimplemented using the framework (758 lines, up from the old ad-hoc version).

1.2 Business Affiliates Use Cases — Removal (~5,200 lines deleted)

Deleted all pre-framework use case stories and their shared infrastructure:

Shared infrastructure removed (src/use-cases/reference/business-affiliates/_shared/):

• affiliate-typeahead.tsx (371 lines)
• column-defs.tsx (146 lines)
• confirm-dialog.tsx (157 lines)
• grid-cell-renderers.tsx (149 lines)
• mock-data.ts (489 lines)
• msw-handlers.ts (329 lines)
• story-step-delay.ts (15 lines)
• supplier-drawer.tsx (988 lines)
• suppliers-page.tsx (430 lines)
• suppliers-sidebar.tsx (24 lines)
• types.ts (56 lines)

Use case stories removed:

• BA-0001 Browse and Search (7 story files + 2 page wrappers)
• BA-0002 View Details (1 story file)
• BA-0003 Create Supplier (2 story files + 1 page wrapper — happy-path.stories.tsx was reimplemented, not deleted)
• BA-0004 Edit Supplier (2 story files + 1 page wrapper)
• BA-0005 Delete Supplier (3 story files + 2 page wrappers)
• BR-0002 Affiliate Typeahead (1 story file)
• business-affiliates.mdx (212 lines — overall description page)

MDX files removed: All BA use case descriptions except create-supplier.mdx (modified, not deleted).

1.3 Storybook & CI Simplification

.storybook/main.ts:

• Removed @storybook/addon-links from addons
• Removed STORYBOOK_BASE environment variable handling (subpath deployment)
• Removed wrap-ag-grid-css-in-layer Vite plugin (replaced by CSS @import layer() syntax)
• Removed fix-mocker-entry-base-path Vite plugin (only needed for subpath)

.storybook/preview.ts:

• Simplified MSW initialization: removed serviceWorker.url override (was for subpath)
• Removed 44-line Business Affiliates sidebar hierarchy from storySort
• Collapsed use-case sort to 'Reference', 'Procurement', [...], 'Samples', '*'

src/styles/ag-theme-arda.css:

• Changed @import 'ag-grid-community/styles/ag-grid.css'; to @import '...' layer(base);
• Removed 6-line comment block explaining the old Rollup workaround

CI/Playwright:

• .github/workflows/ci.yml: removed subpath deployment test job
• .github/workflows/deploy-pages.yml: removed STORYBOOK_BASE env variable
• playwright.config.ts: removed subpath-deployment project definition
• Deleted tests/smoke/subpath-deployment.spec.ts (83 lines)
• Deleted tests/smoke/subpath-server.mjs (77 lines)

package.json:

• Removed @storybook/addon-links dependency

2. Overlap Analysis

Files Modified in Both Branches

Only 3 files are modified in both branches:

File	Our change	Callil’s change	Conflict?
src/use-cases/reference/business-affiliates/_shared/affiliate-typeahead.tsx	Import path: @/lib/utils → @/types/canary/utils	Deleted entirely	No — deletion wins
src/use-cases/reference/business-affiliates/_shared/confirm-dialog.tsx	Import path update	Deleted entirely	No — deletion wins
src/use-cases/reference/business-affiliates/_shared/supplier-drawer.tsx	Import path update	Deleted entirely	No — deletion wins

Files That Exist in Both Branches (Unmodified from Main)

These files are NOT modified in either branch but will need attention due to Callil’s deletions of files that reference them:

• src/use-cases/reference/business-affiliates/pages/suppliers-list-view.stories.tsx — Callil modifies it (import path change); we don’t touch it.

Storybook Config — Semantic Conflict

No textual git conflicts exist, but the two branches take opposite positions on subpath deployment and AG Grid CSS layering:

Feature	Our branch (main)	Callil’s branch
STORYBOOK_BASE subpath	Present (inherited from main)	Removed
wrap-ag-grid-css-in-layer plugin	Present (inherited from main)	Removed (replaced with CSS @import layer())
fix-mocker-entry-base-path plugin	Present (inherited from main)	Removed
MSW serviceWorker.url override	Present (inherited from main)	Removed
@storybook/addon-links	Present (inherited from main)	Removed
BA sidebar storySort	Present (inherited from main)	Removed

Note: Our branch did not add these features — they exist on main. But our branch did not remove them either, so if Callil’s branch merges first, our branch would need to be rebased and these sections would disappear.

3. Incorporation Outline

Step 1: Cherry-pick the Use Case Framework

Bring in the new src/use-cases/framework.tsx and the reimplemented create-supplier/happy-path.stories.tsx.

Files to copy/merge:

• src/use-cases/framework.tsx (new file — no conflict)
• src/use-cases/reference/business-affiliates/create-supplier/happy-path.stories.tsx (new content — replaces old)
• src/use-cases/reference/business-affiliates/create-supplier/create-supplier.mdx (modified)

Effort: Low. Direct copy.

Step 2: Delete Business Affiliates Stories

Remove all deleted files and directories from src/use-cases/reference/business-affiliates/ except the create-supplier stories and the pages/ directory (which Callil keeps with a minor modification).

Files to delete: ~30 files across _shared/, browse-and-search/, view-details/, edit-supplier/, delete-supplier/, affiliate-typeahead/, plus business-affiliates.mdx and the old create-supplier variants.

Effort: Low. git rm of known file list.

Step 3: Adopt AG Grid CSS @import layer() Syntax

Callil’s approach is cleaner — use native CSS layer import syntax instead of the Vite transform plugin.

Changes:

1. In src/styles/ag-theme-arda.css: change imports to @import '...' layer(base);, remove comment block
2. In src/styles/canary/ag-theme-arda.css: apply the same change
3. In .storybook/main.ts: remove the wrap-ag-grid-css-in-layer plugin

Risk: The vite-plugin approach was added because @import layer() didn’t survive Rollup code-splitting. Callil’s branch may have tested this with their simplified build. Needs verification that npm run build-storybook + VRT still pass with the CSS-only approach.

Step 4: Decide on Subpath Deployment (see OQ-1)

If removing subpath support:

1. In .storybook/main.ts: remove STORYBOOK_BASE handling and fix-mocker-entry-base-path plugin
2. In .storybook/preview.ts: simplify MSW initialization (remove serviceWorker.url)
3. In .github/workflows/ci.yml: remove subpath test job
4. In .github/workflows/deploy-pages.yml: remove STORYBOOK_BASE env
5. In playwright.config.ts: remove subpath-deployment project
6. Delete tests/smoke/subpath-deployment.spec.ts and tests/smoke/subpath-server.mjs

If keeping subpath support: skip all of the above.

Step 5: Clean Up Storybook Sidebar Sort

Update .storybook/preview.ts to remove the Business Affiliates hierarchy from storySort, replacing it with the collapsed version from Callil’s branch.

Step 6: Remove @storybook/addon-links

Remove from addons array in .storybook/main.ts and from package.json.

Step 7: Verify

1. npm run lint
2. npm run build:lib
3. npm run test
4. npm run build-storybook + npm run test:vrt:ci
5. Verify the create-supplier framework story renders correctly in Storybook

Open Questions

#	Summary	Recommendation	Guidance
OQ-1	Keep or remove subpath deployment support?	Remove — simplifies build	Agreed
OQ-2	AG Grid CSS layer approach	Adopt CSS @import layer() after verification	Agreed with verification.
OQ-3	Business Affiliates deletion timing	Include in this branch	Business Affiliates Use Cases must be kept.
OQ-4	Merge strategy	Cherry-pick into our branch, close Callil’s PR	Agreed, care needs to be paid to respect the import paths and file locations in the jmpicnic/list-view-management-620 branch.

OQ-1 — Subpath Deployment Support

Description: The callil/storybook-ia-refactor branch removes all subpath deployment infrastructure (STORYBOOK_BASE, service worker URL override, mocker path fix, CI test job). Our branch inherited this from main but did not add or use it. Should we keep it?

Options:

• (a) Remove subpath support (match Callil’s branch)
  • Pro: Simpler build config, fewer Vite plugins, no CI job to maintain. Storybook is served at root on Vercel (the current deployment target).
  • Con: If GitHub Pages subpath deployment is ever needed again, the infrastructure must be rebuilt.
• (b) Keep subpath support
  • Pro: Preserves the ability to deploy under /ux-prototype/ on GitHub Pages.
  • Con: Maintenance burden for a feature that may not be actively used.

Recommendation: (a) Remove. The Storybook site is deployed on Vercel at root path. The subpath infrastructure was for GitHub Pages and adds complexity without current use.

OQ-2 — AG Grid CSS Layer Approach

Description: Our branch uses a Vite transform plugin (wrap-ag-grid-css-in-layer) to wrap AG Grid CSS in @layer base. Callil’s branch removes this plugin and uses native @import '...' layer(base) syntax in the CSS file. The comment in our main branch explains that @import layer() didn’t survive Rollup code-splitting, which is why the plugin was created.

Options:

• (a) Adopt Callil’s CSS @import layer() approach
  • Pro: Simpler, no Vite plugin needed, standard CSS syntax.
  • Con: May break if Rollup code-splits AG Grid CSS (the original reason for the plugin). Needs build + VRT verification.
• (b) Keep the Vite plugin approach
  • Pro: Proven to work in both dev and production builds.
  • Con: Extra plugin complexity.

Recommendation: (a) Adopt the CSS approach, but verify first. Build Storybook and run VRT to confirm AG Grid styles render correctly. If VRT fails, revert to the plugin approach.

OQ-3 — Business Affiliates Deletion Timing

Description: Callil’s branch deletes ~30 files of Business Affiliates use case stories. Should we incorporate this deletion into our List View branch or handle it separately?

Options:

• (a) Include in this branch — add a “Merge callil contributions” commit
  • Pro: Single PR covers both the List View work and the framework/cleanup. Avoids merge conflicts later.
  • Con: Larger PR scope, mixes two concerns.
• (b) Separate PR — let Callil’s branch merge independently
  • Pro: Clean separation of concerns. Each PR has its own review scope.
  • Con: Whichever merges second must rebase and resolve conflicts (though conflicts are trivial).

Recommendation: (a) Include in this branch. The conflicts are trivial (3 files we changed imports on that Callil deletes), and merging them together avoids a rebase dance. Add a clearly labeled commit.

OQ-4 — Merge Strategy

Description: How to incorporate Callil’s changes into our branch.

Options:

• (a) Cherry-pick Callil’s commits into our branch, then close Callil’s PR
  • Pro: Preserves Callil’s commit authorship. Our branch becomes the single merge target.
  • Con: Cherry-picking across diverged branches can be messy if commits touch the same files.
• (b) Merge Callil’s branch into ours (git merge callil/storybook-ia-refactor)
  • Pro: Simplest mechanically. Git resolves trivial conflicts automatically.
  • Con: Creates a merge commit. Callil’s commit history appears in our branch.
• (c) Manually replay — read Callil’s changes and apply them as new commits on our branch
  • Pro: Clean commit history. We control exactly what goes in.
  • Con: Doesn’t preserve Callil’s authorship on the commits.

Recommendation: (c) Manually replay. Callil’s branch has a single squashed commit. The changes are well-understood from this analysis. A manual replay as one or two clearly labeled commits gives the cleanest result and lets us adapt any conflicts (e.g., import paths, CSS layer syntax) in-flight.

Additional Guidance

• The project should include adopting the DSL approach for all stories to which it is applicable. Verification should include VRT before and after comparisons.
• The refactoring and clean up in the jmpicnic/list-view-management-620 should be kept regarding the placement of components, styles, types, etc. and the associated imports. (review commit history for details)
• All work should be done in a new branch off of jmpicnic/list-view-management-620 in its own worktree.

Round 1 Resolution Summary

#	Decision	Impact
OQ-1	Remove subpath deployment	Simplifies Storybook config and CI
OQ-2	Adopt CSS @import layer() with verification	Replaces Vite plugin with native CSS
OQ-3	Keep Business Affiliates use cases	Reverses Callil’s deletion; BA stories are retained
OQ-4	Manually replay on a new branch off jmpicnic/list-view-management-620	Separate worktree, preserves our import paths

Revised incorporation outline given OQ-3 reversal (keep BA) and DSL adoption scope:

1. Create new branch off jmpicnic/list-view-management-620 in a worktree
2. Bring in src/use-cases/framework.tsx (the DSL toolkit)
3. Apply Storybook config simplifications (remove subpath, addon-links, AG Grid CSS plugin)
4. Convert applicable BA stories to use the DSL framework (keeping them, not deleting)
5. Convert other applicable use-case stories to the DSL framework
6. VRT before/after at each conversion step
7. Verify all gates (lint, build, test, VRT)

Round 2 — Open Questions

#	Summary	Recommendation	Guidance
OQ-5	Which BA stories should be converted to the DSL?	Create/Edit/Delete flows (wizard-like); keep Browse/Search/View as-is	Agreed
OQ-6	Are non-BA stories in scope for DSL conversion?	Not in this branch — separate follow-up	Yes, we’ll need to review case by case, provide a table in a separate document (migration-candidates.md) with one row per candidate, a recommendation (Y/N) and a brief justification. Add a blank Decision column for my feedback.
OQ-7	What happens to Callil’s reimplemented create-supplier story?	Use it as the reference implementation for framework adoption	Agreed
OQ-8	VRT strategy for story conversions	Capture baselines before conversion, compare after	Agreed

Correction from Round 2 research: The Use Case Story Framework (src/use-cases/framework.tsx) already exists on main — it was NOT introduced by Callil’s branch. Two stories already use it on main: use-cases/reference/items/add-supply/happy-path.stories.tsx and use-cases/samples/add-item/happy-path.stories.tsx. Callil’s branch did not modify framework.tsx at all. The sole framework-related contribution is the rewrite of create-supplier/happy-path.stories.tsx to use the existing framework instead of the ad-hoc CreatableSuppliersPage wrapper.

OQ-5 — Which BA Stories Should Be Converted to the DSL?

Description: The DSL framework (createUseCaseStories) is designed for multi-step workflows with wizard-like progression (form fill → review → submit → success). Not all BA stories fit this pattern. The current BA use cases are:

Use Case	Stories	Pattern	DSL Fit
BA-0001 Browse and Search	7 stories (list view, search, columns, select, pagination, deep link)	Grid interaction, no wizard flow	Low — these are grid observation stories, not wizard workflows
BA-0002 View Details	1 story (supplier details panel)	Click-to-view, no form	Low — single-step view, no wizard
BA-0003 Create Supplier	3 stories (happy path, validation, experimental wizard)	Multi-step form → submit → success	High — Callil already reimplemented happy-path
BA-0004 Edit Supplier	2 stories (happy path, validation)	Load → edit form → submit	Medium — similar to Create but starts with existing data
BA-0005 Delete Supplier	3 stories (from list, from panel, error)	Confirm dialog → delete → success	Low-Medium — simple confirmation, not a multi-step wizard
BR-0002 Affiliate Typeahead	1 story (create on the fly)	Typeahead with create flow	Medium — has a creation sub-flow

Options:

• (a) Convert only high-fit stories (BA-0003 Create, BA-0004 Edit)
  • Pro: Focused scope, clear DSL benefit, Callil already did the Create reference.
  • Con: Leaves most BA stories unconverted.
• (b) Convert all stories that have any interaction flow (BA-0003, BA-0004, BA-0005, BR-0002)
  • Pro: More comprehensive adoption, demonstrates DSL flexibility.
  • Con: BA-0005 Delete and BR-0002 are short flows that may not benefit much from the DSL.
• (c) Convert all BA stories including Browse/Search and View Details
  • Pro: Uniform pattern across all BA use cases.
  • Con: The DSL is designed for wizard flows; grid-observation stories would need to be forced into a scene-based pattern that doesn’t fit naturally.

Recommendation: (a) Convert BA-0003 Create and BA-0004 Edit. These are the clear wins — multi-step wizard flows that match the DSL’s design. Callil’s create-supplier/happy-path.stories.tsx serves as the reference. Other stories remain as-is. Further conversions can follow in a separate effort once the pattern is proven.

OQ-6 — Are Non-BA Stories in Scope for DSL Conversion?

Description: The guidance says “adopt the DSL approach for all stories to which it is applicable.” Beyond BA, the src/use-cases/ directory also contains Procurement use-case stories and Samples. Should these be converted in this branch?

Options:

• (a) BA stories only — keep this branch focused on incorporating Callil’s work
  • Pro: Bounded scope. Procurement stories are newer and may already follow better patterns.
  • Con: Doesn’t fully address the “all applicable” guidance.
• (b) Include Procurement and Samples if they have wizard-like flows
  • Pro: Comprehensive DSL adoption in one pass.
  • Con: Larger scope, more risk, longer branch lifetime.

Recommendation: (a) BA stories only. This branch’s purpose is incorporating Callil’s contributions. DSL adoption for other story families can be a follow-up project with its own plan.

OQ-7 — What Happens to Callil’s Reimplemented Create-Supplier Story?

Description: Callil reimplemented create-supplier/happy-path.stories.tsx using the framework (758 lines). The original version (pre-framework) still exists on our branch. How do we handle this?

Options:

• (a) Use Callil’s reimplementation directly — replace our version with theirs
  • Pro: Already tested with the framework. Serves as reference.
  • Con: May need import path adjustments for our branch’s file locations.
• (b) Use Callil’s as reference, rewrite from scratch using our branch’s conventions
  • Pro: Full control over import paths and patterns.
  • Con: Duplicates work Callil already did.

Recommendation: (a) Use Callil’s reimplementation, adjusting import paths to match our branch’s conventions (e.g., @/types/canary/utils for cn, canary shared formatters).

OQ-8 — VRT Strategy for Story Conversions

Description: The guidance requires “VRT before and after comparisons” for DSL conversions. The current VRT spec (canary-parity.spec.ts) tests canary-refactor vs dev-witness. BA stories are not in the VRT spec.

Options:

• (a) Add BA stories to VRT spec — capture baselines before conversion, compare after
  • Pro: Rigorous visual regression protection.
  • Con: BA stories are complex full-page stories with MSW data; VRT setup is non-trivial. Some visual differences may be expected (the DSL adds chrome like guide panels and step indicators).
• (b) Manual visual comparison — screenshot before/after in Storybook, document in PR
  • Pro: Simpler. Acknowledges that DSL conversion intentionally changes story chrome.
  • Con: Not automated, not repeatable.
• (c) VRT for page content only — clip screenshots to exclude DSL chrome (guide panel, controls)
  • Pro: Tests the actual form/page content hasn’t regressed while allowing framework chrome changes.
  • Con: Requires careful clip coordinates per story.

Recommendation: (b) Manual visual comparison. The DSL framework intentionally adds chrome (guide panels, step indicators, control bars) that doesn’t exist in the original stories. Automated VRT would fail on these expected differences. A manual before/after screenshot comparison documented in the PR is the pragmatic approach.

Round 2 Resolution Summary

#	Decision	Impact
OQ-5	Convert Create/Edit (wizard flows); keep Browse/Search/View/Delete as-is	Focused DSL adoption on high-fit stories
OQ-6	Produce migration-candidates.md with per-story assessment for all use-case stories	Enables informed decisions on broader DSL adoption
OQ-7	Use Callil’s rewrite of create-supplier/happy-path, adjust import paths	Reference implementation for the pattern
OQ-8	VRT baselines before conversion, compare after	Automated regression protection

Key correction: The DSL framework (src/use-cases/framework.tsx) already exists on main and our branch. It was not introduced by Callil’s branch. Two stories already use it. Callil’s only framework contribution is the rewrite of create-supplier/happy-path.stories.tsx.

Deliverable: migration-candidates.md created as a sibling document — see Migration Candidates.

Revised Incorporation Outline (Final)

Given all decisions, the actual scope of incorporating Callil’s work is:

1. Create new branch off jmpicnic/list-view-management-620 in a worktree
2. Storybook config simplification:
   • Remove subpath deployment support (OQ-1)
   • Adopt CSS @import layer() for AG Grid (OQ-2), verify with build + VRT
   • Remove @storybook/addon-links
   • Clean up BA sidebar storySort (simplify, don’t delete — BA stories are kept)
3. Adopt Callil’s create-supplier/happy-path rewrite (OQ-7) — adjust import paths for our branch
4. Convert BA-0004 Edit Supplier stories to use the DSL framework (OQ-5)
5. VRT baselines before/after each conversion (OQ-8)
6. Verify all gates: lint, build:lib, test, build-storybook, VRT

Not in scope:

• Deleting BA stories or shared infrastructure (OQ-3 reversal)
• Converting Browse/Search, View Details, Delete, or Affiliate Typeahead stories (OQ-5)
• Converting non-BA stories (OQ-6 — tracked in migration-candidates.md for future)