FRD: Audit Barrel Export Status

Field	Value
ID	FRD-048
Owner	David Holmes
Status	Shipped
Last Updated	2026-05-26
Target Release	v2.1.0
Type	Infra
Complexity	S

Document Summary

Eight components in src/components/ui/ are not exported from the barrel file (src/index.ts). This FRD defines the work to audit each component and make an explicit decision: promote to public export or mark with @internal JSDoc. The result is a clear public API surface with no ambiguously-scoped components.

Introduction

Overview

The design system publishes its public API through src/index.ts. Eight UI components exist in the source tree but are not exported, leaving their status ambiguous. Consumers who import directly from file paths bypass the public API contract and risk breakage. This audit resolves the ambiguity for each component.

Goals

For each of the 8 components, decide: public export or @internal.
Promote components that are stable and useful to consumers to the barrel export.
Mark components that are internal implementation details with @internal JSDoc and document them as non-public.
Ensure src/index.ts accurately represents the public API surface.

Non-Goals

Refactoring or redesigning any component.
Removing components (internal components remain available for internal use).
Adding new features to any component.

Scope

In Scope

Item	Description
`slide-out-panel-manager.tsx`	234 lines. Panel container used by multiple surfaces.
`filter-pill-bar.tsx`	115 lines. Filter UI used in search and list views.
`search-result-row.tsx`	236 lines. List item for search results.
`overlay-caret.tsx`	108 lines. Positioning caret for overlay/tooltip components.
`gauge-ring.tsx`	150 lines. Circular gauge visualization.
`manifest-viewer.tsx`	9 lines. YAML/JSON manifest display.
`pod-terminal-live-session.tsx`	182 lines. Live terminal session display.
`pod-terminal-virtualized-transcript.tsx`	Virtualized transcript for terminal output.
`src/index.ts`	Barrel export file to update for promoted components.

Out of Scope

Item	Reason
Adding stories	Covered by FRD-047.
Component refactoring	This audit decides export status, not implementation quality.
Scorecard component	`scorecard.tsx` is already exported.

Users and Pain Points

User	Pain Point
Package consumer	Cannot tell which components are safe to import from the barrel vs. which are internal.
Package consumer	Importing from deep file paths risks breakage when internal files are moved or renamed.
Package maintainer	No explicit decision on which components are public creates uncertainty about the semver impact of changes.

Definitions

Term	Definition
Barrel export	The `src/index.ts` file that re-exports the public API. Consumers import from the package root.
`@internal`	A JSDoc tag indicating the component is not part of the public API and may change without a semver major bump.
Public API	The set of exports from `src/index.ts` that consumers may rely on under semver guarantees.

Current State

src/index.ts exports the majority of the design system’s components. The following eight components are defined in src/components/ui/ but are absent from the barrel:

slide-out-panel-manager.tsx — used by application panels.
filter-pill-bar.tsx — used in search/list views.
search-result-row.tsx — used in search results.
overlay-caret.tsx — used as a sub-component of overlays/tooltips.
gauge-ring.tsx — used in dashboards.
manifest-viewer.tsx — used in Kubernetes/deployment views.
pod-terminal-live-session.tsx — used in terminal features.
pod-terminal-virtualized-transcript.tsx — used as a sub-component of terminal views.

None have @internal JSDoc tags. Their export status is ambiguous.

Proposed Solution

Conduct a per-component audit evaluating:

Consumer demand — Is this component useful outside the design system’s own internal consumption?
API stability — Is the component’s prop interface stable enough for public consumption?
Standalone viability — Can the component be used independently, or does it only make sense as a child of another component?
Bundle cost — Does the component pull in heavy dependencies that would penalize consumers who do not use it?

Preliminary assessment (subject to audit confirmation)

Component	Recommendation	Rationale
`slide-out-panel-manager`	Promote	General-purpose panel container useful to any application.
`filter-pill-bar`	Promote	General-purpose filter UI component.
`search-result-row`	Promote	Useful for any search interface.
`overlay-caret`	Internal	Sub-component of overlay system; not useful standalone.
`gauge-ring`	Promote	General-purpose visualization component.
`manifest-viewer`	Internal	Specialized to Kubernetes manifest display; narrow audience.
`pod-terminal-live-session`	Internal	Specialized; heavy dependencies (xterm).
`pod-terminal-virtualized-transcript`	Internal	Sub-component of terminal; not useful standalone.

Requirements

ID	Priority	Requirement
BARREL-01	P0	Each of the 8 components has an explicit public or internal designation.
BARREL-02	P0	Public components are added to `src/index.ts`.
BARREL-03	P0	Internal components have `@internal` JSDoc on their default export.
BARREL-04	P1	The barrel export change is accompanied by a CHANGELOG entry noting newly public components.

Functional Requirements

Components promoted to public export must be importable from the package root (e.g., import { FilterPillBar } from '@dmwd/design-system').
Internal components must have /** @internal */ on the component function and on the TypeScript type export (if any).
The barrel export must not pull in heavy dependencies (xterm, react-virtuoso) eagerly. If a promoted component has heavy deps, it must use dynamic import or be exported from a separate entry point.
The CHANGELOG entry lists each newly-public component with a one-line description.

Non-Functional Requirements

Category	Requirement
Bundle size	Promoting a component to the barrel must not increase the base bundle by more than 5 kB (uncompressed). Heavy-dep components must use a separate entry point or dynamic import.
Semver	Promoting components to public export is a minor version bump (new feature).
Discoverability	Public components appear in Storybook docs and IDE auto-complete from the barrel import.

API/Interface Requirements

Updated src/index.ts with new exports for promoted components:

export { SlideOutPanelManager } from './components/ui/slide-out-panel-manager';
export { FilterPillBar } from './components/ui/filter-pill-bar';
export { SearchResultRow } from './components/ui/search-result-row';
export { GaugeRing } from './components/ui/gauge-ring';
// Exact list subject to audit results.

Accessibility Requirements

No direct accessibility impact from the export decision. Promoted components should already meet accessibility standards; if they do not, follow-up work is needed (tracked separately).

Content and Documentation Requirements

Each promoted component must have a Storybook story (coordinated with FRD-047).
CHANGELOG.md entry for the release noting newly-public components.
Internal components documented with @internal in TSDoc.

Dependencies

Dependency	Type	Notes
`src/index.ts`	Internal	Barrel export file.
FRD-047 (undocumented stories)	Internal	Stories should exist before promoting to public.
The 8 component source files	Internal	`src/components/ui/`.

Risks and Tradeoffs

Risk	Likelihood	Impact	Mitigation
Promoting an unstable component locks its API under semver.	Medium	Medium	Only promote components with stable, well-defined props. Use the audit criteria to evaluate stability.
Heavy dependencies leak into the base bundle.	Medium	High	Use separate entry points or dynamic import for components with heavy deps (xterm, react-virtuoso).
Internal components are still imported by deep path by existing consumers.	Low	Low	`@internal` JSDoc serves as a warning. A future eslint rule could enforce barrel-only imports.

Open Questions

Should heavy-dep components get a separate package entry point (e.g., @dmwd/design-system/terminal) instead of staying internal? Leaning toward separate entry point if demand exists.
Should the audit include a grep for external consumers importing these components by deep path? Would inform the promote/internal decision.
Should manifest-viewer be promoted if it gains broader applicability (e.g., any YAML/JSON viewer)?

Acceptance Criteria

Each of the 8 components has an explicit designation (public or internal) documented in a decision table.
Public components are exported from src/index.ts.
Internal components have @internal JSDoc.
No heavy-dependency components are eagerly pulled into the base barrel bundle.
CHANGELOG entry lists newly-public components.
pnpm typecheck passes.
pnpm vitest run --project unit passes.

LLM Handoff Instructions

When implementing this FRD:

Read each of the 8 component source files to assess prop stability and dependency weight.
Check if each component is imported by other components in the design system (internal consumption) or by external packages.
For each component, make the promote/internal decision and record it in a decision table.
For promoted components, add an export line to src/index.ts, following the existing export style (named exports, alphabetical order).
For internal components, add /** @internal */ JSDoc above the component function export.
If any promoted component imports @xterm/xterm, react-virtuoso, or recharts, create a separate entry point in package.json exports field rather than adding it to the main barrel.
Update CHANGELOG.md with the newly-public components.
Run pnpm typecheck and pnpm vitest run --project unit.

Decision Log

Date	Decision	Rationale
2026-05-26	Audit all 8 un-exported components rather than batch-promoting.	Each component has different stability, dependency, and utility profiles. A case-by-case decision prevents regret.
2026-05-26	Use `@internal` JSDoc rather than removing internal components.	Internal components are used within the design system. Removing them would break internal consumers.
2026-05-26	Separate entry points for heavy-dep components.	Prevents base bundle bloat while still offering the component to advanced consumers.

Document History

Version	Date	Author	Changes
0.1	2026-05-26	David Holmes	Initial draft.