Skip to content

v6: lock down the @graphiql/react public surface before 6.0.0#4431

Draft
trevor-scheer wants to merge 3 commits into
graphiql-6from
trevor/public-api-surface-lockdown
Draft

v6: lock down the @graphiql/react public surface before 6.0.0#4431
trevor-scheer wants to merge 3 commits into
graphiql-6from
trevor/public-api-surface-lockdown

Conversation

@trevor-scheer

Copy link
Copy Markdown
Contributor

Summary

An audit of @graphiql/react's public barrels turned up a handful of exports that read as internal or dangerously generic. None have docs or a changeset, which is itself the signal they weren't meant to be public. Since everything here is unreleased on graphiql-6, this is the last window to fix it without a deprecation cycle.

  • getRunBlockReason, resolveActiveOperation, and MUTATION_REQUIRES_POST_REASON were re-exported from utility/index.ts even though they're pure Run-button implementation detail. Dropped from the barrel; the two internal call sites (stores/execution.ts, top-bar) now import ./run-block directly.
  • VarTab (exported alongside VarHeadersStrip) is about as generic as a type name gets in a shared package namespace. Renamed to VarHeadersTab.
  • Operation (exported alongside MethodPill) keeps its name. It's defined in @graphiql/toolkit and re-exported here because MethodPillProps.operation is typed with it, so it's effectively part of this package's API whether or not it originates here. Renaming it would leave one type with two public names, which is worse than the generic name it has now. Consumers get it from @graphiql/react without needing a direct toolkit dependency.
  • TopBarView / StatusBarView / SidePanelView (and their prop types) are the presentational half of a container/presentational split, exported alongside TopBar / StatusBar / SidePanel. Nothing outside graphiql-react imports them — even their own tests and stories already import from the component's own file, not the barrel — so they read as Storybook plumbing, not consumer API. Dropped from the barrel. The container components stay public, and so do the genuine response views (ResponseTreeView, ResponseTableView), which are real documented JSON/Tree/Table components, not a naming coincidence with the *View pattern above.
  • PortalProvider / usePortalContainer stay public. They're not leaked plumbing: graphiql's own <GraphiQL> component uses them to wire its container element into Radix's dialog/tooltip/dropdown portals so themed content doesn't fall back to rendering into document.body. Anyone assembling a custom shell around @graphiql/react components directly needs the same hook. The contract is already documented in the module's JSDoc.

Test plan

  • Import getRunBlockReason, resolveActiveOperation, or MUTATION_REQUIRES_POST_REASON from @graphiql/react and confirm none of them resolve anymore.
  • Import Operation from @graphiql/react and confirm it still resolves, with the 'query' | 'mutation' | 'subscription' shape, and that it's assignable to MethodPillProps['operation'].
  • Import VarTab from @graphiql/react and confirm it no longer resolves; import VarHeadersTab and confirm it does.
  • Import TopBarView, StatusBarView, or SidePanelView from @graphiql/react and confirm none of them resolve anymore; confirm TopBar, StatusBar, and SidePanel still do.
  • Confirm PortalProvider and usePortalContainer still import cleanly from @graphiql/react.
  • Run the app, open a mutation with a GET/QUERY method selected, and confirm the Run button still shows the blocked-reason tooltip (exercises the now-internal-only run-block path end to end).
  • yarn workspace @graphiql/react test passes.

Refs: #4219

`getRunBlockReason`, `resolveActiveOperation`, and
`MUTATION_REQUIRES_POST_REASON` are Run-button implementation detail with
no docs or changeset, re-exported through `utility/index.ts` by accident.
Drop them from the public barrel; the two internal call sites now import
`./run-block` directly.
`VarTab` is about as generic as a type name gets in a shared package
namespace. Name it for the component it belongs to.

`Operation` keeps its name: it's toolkit's type, re-exported here
because `MethodPillProps.operation` needs it. Aliasing it would give one
type two public names.
…blic barrel

These container/presentational splits export a presentational twin
alongside each container (TopBar/TopBarView, etc.), but nothing outside
graphiql-react imports the *View half — its own tests and stories already
import from the component's own file, not the package barrel. They read
as Storybook/testability plumbing rather than consumer API, so drop them
from components/index.ts. The container components (TopBar, StatusBar,
SidePanel) stay public, as do the genuine response views (ResponseTreeView,
ResponseTableView), which are documented JSON/Tree/Table components.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant