fix(joint-react): stop leaking internal types into the API docs

.changeset/react-public-api-types.md

@@ -0,0 +1,5 @@
+---
+"@joint/react": minor
+---
+
+types - export the types public signatures reference (`ComputedElementRecord`, `ComputedLinkRecord`, `GraphCellData`, paper event params, ...) so the API docs no longer show internal names

packages/joint-react/package.json

@@ -44,7 +44,7 @@
     "build": "rollup -c rollup.config.ts --configPlugin esbuild",
     "build-storybook": "storybook build",
     "storybook": "storybook dev -p 6006",
-    "test": "yarn run typecheck && yarn run knip && yarn run duplicity-detect && yarn run test:react19 && yarn run test:react18",
+    "test": "yarn run typecheck && yarn run knip && yarn run docs:check && yarn run duplicity-detect && yarn run test:react19 && yarn run test:react18",
     "test:react19": "jest",
     "test:react18": "jest --config jest.react18.config.mjs",
     "test-coverage": "jest --coverage",
@@ -56,6 +56,7 @@
     "format": "prettier --write \"./**/*.{js,jsx,json,ts,tsx}\"",
     "docs:typedoc": "typedoc --router group --out docs/api src",
     "docs:typedoc-md": "typedoc --options typedoc.config.mjs",
+    "docs:check": "typedoc --options typedoc.config.mjs --emit none --treatWarningsAsErrors",
     "bench": "jest --selectProjects default --testMatch '<rootDir>/bench/**/*.{test,spec}.ts?(x)'"
   },
   "exports": {

packages/joint-react/src/components/graph/graph-provider.tsx

@@ -7,7 +7,10 @@ import type { AutoSizeOrigin } from '../../store/graph-store';
 import type { OnIncrementalCellsChange } from '../../store/graph-projection';
 import type { ElementJSONInit, LinkJSONInit, CellInput } from '../../types/cell.types';
 
-/** Cells array accepted by GraphProvider. */
+/**
+ * Cells array accepted by GraphProvider.
+ * @inline
+ */
 type ProviderCells<Element extends ElementJSONInit, Link extends LinkJSONInit> = ReadonlyArray<
   Element | Link
 >;

packages/joint-react/src/hooks/use-cell-drag.ts

@@ -30,12 +30,23 @@ interface CellDragStateBase {
   readonly cellId?: dia.Cell.ID;
 }
 
-interface CellDragStateDragging extends Required<CellDragStateBase> {
-  isDragging: true;
-}
-interface CellDragStateIdle extends CellDragStateBase {
-  isDragging: false;
-}
+/**
+ * {@link CellDragState} while the cell is being dragged: every field is set.
+ * @interface
+ * @group Types
+ */
+export type CellDragStateDragging = Required<CellDragStateBase> & {
+  readonly isDragging: true;
+};
+/**
+ * {@link CellDragState} while the cell is not being dragged: only the flags are
+ * guaranteed.
+ * @interface
+ * @group Types
+ */
+export type CellDragStateIdle = CellDragStateBase & {
+  readonly isDragging: false;
+};
 /**
  * Drag state for the current cell, returned by {@link useCellDrag}. While a
  * drag is in progress (`isDragging` is `true`), the active fields (`event`,

packages/joint-react/src/hooks/use-cell-setters.ts

@@ -54,7 +54,7 @@ function writeMergedCell<Element extends ElementJSONInit, Link extends LinkJSONI
  * @template Link - link record shape
  * @group Types
  */
-type SetCellUpdater<Element extends ElementJSONInit, Link extends LinkJSONInit> = (
+export type SetCellUpdater<Element extends ElementJSONInit, Link extends LinkJSONInit> = (
   previous: Element | Link
 ) => Element | Link;
 
@@ -144,7 +144,7 @@ export function useSetCell<
  * @template Data - cell data shape
  * @group Types
  */
-type SetCellDataUpdater<Data> = (previousData: Data) => Data;
+export type SetCellDataUpdater<Data> = (previousData: Data) => Data;
 
 /**
  * Function exposed by {@link GraphApi}.setCellData. Two forms, both keyed by

packages/joint-react/src/hooks/use-cells.ts

@@ -26,13 +26,25 @@ type CellsResult<Cell extends AnyCellRecord, Selected> =
 /** Equality function on raw `unknown` values. */
 type UnknownEqual = (a: unknown, b: unknown) => boolean;
 
-/** Selector over the resolved cells array (the array forms of `useCells`). */
-type CellsSelector<Cell extends AnyCellRecord, Selected> = (
+/**
+ * Selector over the resolved cells array (the array forms of {@link useCells}).
+ * Return a primitive or an existing record, a fresh array or object on every
+ * call defeats the equality bail-out (pass `isEqual` for derived arrays).
+ * @template Cell - the cell record shape
+ * @template Selected - the selected value
+ * @group Types
+ */
+export type CellsSelector<Cell extends AnyCellRecord, Selected> = (
   cells: ReadonlyArray<Computed<Cell>>
 ) => Selected;
 
-/** Equality test that short-circuits a re-render when the selected value is unchanged. */
-type SelectedEqual<Selected> = (a: Selected, b: Selected) => boolean;
+/**
+ * Equality test that short-circuits a re-render when the selected value is
+ * unchanged. Defaults to `Object.is`.
+ * @template Selected - the selected value
+ * @group Types
+ */
+export type SelectedEqual<Selected> = (a: Selected, b: Selected) => boolean;
 
 // ── Module-scoped helpers ───────────────────────────────────────────────────
 

packages/joint-react/src/hooks/use-graph.ts

@@ -28,9 +28,6 @@ import type {
  */
 export type GraphJSON = dia.Graph.JSON;
 
-/** Drops an untyped (`unknown`) `data` side so it doesn't collapse a union. */
-type TypedData<Data> = unknown extends Data ? never : Data;
-
 /**
  * `data` type for the GraphApi's `setCellData`, derived from {@link useGraph}'s
  * `Element` / `Link` generics by reusing each record's `['data']`:
@@ -41,12 +38,20 @@ type TypedData<Data> = unknown extends Data ? never : Data;
  *
  * A cell id is opaque at the type level, so this cannot narrow element-vs-link
  * per call, it exposes the data shapes {@link useGraph} was told about.
+ * @template Element - element record shape
+ * @template Link - link record shape
+ * @group Types
  */
-type HandleCellData<Element extends ElementJSONInit, Link extends LinkJSONInit> = [
-  TypedData<Element['data']> | TypedData<Link['data']>,
-] extends [never]
-  ? Record<string, unknown>
-  : TypedData<Element['data']> | TypedData<Link['data']>;
+export type GraphCellData<
+  Element extends ElementJSONInit,
+  Link extends LinkJSONInit,
+> = unknown extends Element['data']
+  ? unknown extends Link['data']
+    ? Record<string, unknown>
+    : Link['data']
+  : unknown extends Link['data']
+    ? Element['data']
+    : Element['data'] | Link['data'];
 
 /**
  * Imperative API returned by {@link useGraph}.
@@ -86,7 +91,7 @@ export interface GraphApi<
    * at the type level, so when both are typed the updater sees their union.
    * Narrow inside it, or fix the `data` shape via `useGraph<ElementRecord<MyData>>()`.
    */
-  readonly setCellData: SetCellData<HandleCellData<Element, Link>>;
+  readonly setCellData: SetCellData<GraphCellData<Element, Link>>;
   /**
    * Remove a cell by id or dia.Cell reference. A nullish reference warns in dev
    * and no-ops; a reference that resolves to no cell is a silent no-op. The
@@ -231,7 +236,7 @@ export function useGraph<
   const { graph } = store;
 
   const setCell = useSetCell<Element, Link>();
-  const setCellData = useSetCellData<HandleCellData<Element, Link>>();
+  const setCellData = useSetCellData<GraphCellData<Element, Link>>();
   const removeCell = useRemoveCell();
   const removeCells = useRemoveCells();
   const resetCells = useResetCells<Element, Link>();

packages/joint-react/src/index.ts

@@ -14,7 +14,7 @@ export type { GraphProviderProps } from './components/graph/graph-provider';
 /** @group Types */
 export type { AutoSizeOrigin } from './store/graph-store';
 /** @group Types */
-export type { IncrementalCellsChange } from './store/graph-projection';
+export type { IncrementalCellsChange, OnIncrementalCellsChange } from './store/graph-projection';
 
 /**
  * <Paper/>
@@ -50,6 +50,7 @@ export type {
   CellVisibility,
   CellVisibilityParams,
   CellInteractivity,
+  CellInteractivityCallback,
   CellInteractivityParams,
 } from './presets';
 
@@ -86,7 +87,16 @@ export type { HTMLBoxProps } from './components/html-box';
  */
 export { useGraph } from './hooks/use-graph';
 /** @group Types */
-export type { GraphApi, GraphJSON, ExportToJSONOptions } from './hooks/use-graph';
+export type { GraphApi, GraphCellData, GraphJSON, ExportToJSONOptions } from './hooks/use-graph';
+/** @group Types */
+export type {
+  SetCell,
+  SetCellUpdater,
+  SetCellData,
+  SetCellDataUpdater,
+} from './hooks/use-cell-setters';
+/** @group Types */
+export type { ArrayUpdate } from './store/state-container';
 
 /** @group Types */
 export type { Transaction, TransactionOptions } from './hooks/use-graph-transaction';
@@ -111,6 +121,8 @@ export { DEFAULT_PAPER_ID } from './mvc/paper';
  * @group Hooks
  */
 export { useCells } from './hooks/use-cells';
+/** @group Types */
+export type { CellsSelector, SelectedEqual } from './hooks/use-cells';
 
 /**
  * useCell()
@@ -151,7 +163,35 @@ export type { ElementsMeasuredParams, OnElementsMeasured } from './hooks/use-on-
  */
 export { useOnPaperEvents } from './hooks/use-on-paper-events';
 /** @group Types */
-export type { PaperEventMap, PaperEventHandler } from './presets';
+export type {
+  PaperEventMap,
+  PaperEventHandler,
+  PaperEventHandlers,
+  PointerCellEventParams,
+  PointerElementEventParams,
+  PointerLinkEventParams,
+  PointerBlankEventParams,
+  FocusCellEventParams,
+  FocusElementEventParams,
+  FocusLinkEventParams,
+  HoverCellEventParams,
+  HoverElementEventParams,
+  HoverLinkEventParams,
+  HoverBlankEventParams,
+  WheelCellEventParams,
+  WheelElementEventParams,
+  WheelLinkEventParams,
+  WheelBlankEventParams,
+  MagnetEventParams,
+  LinkConnectEventParams,
+  PaperHoverEventParams,
+  PaperPanEventParams,
+  PaperPinchEventParams,
+  TranslateEventParams,
+  ScaleEventParams,
+  ResizeEventParams,
+  TransformEventParams,
+} from './presets';
 
 /**
  * useOnGraphEvents()
@@ -167,7 +207,11 @@ export type { GraphEventMap } from './hooks/use-on-graph-events';
  */
 export { useCellDrag } from './hooks/use-cell-drag';
 /** @group Types */
-export type { CellDragState } from './hooks/use-cell-drag';
+export type {
+  CellDragState,
+  CellDragStateDragging,
+  CellDragStateIdle,
+} from './hooks/use-cell-drag';
 
 /**
  * useMarkup()
@@ -212,7 +256,13 @@ export type {
   CellRecord,
   AnyCellRecord,
   Computed,
+  ComputedElementRecord,
+  ComputedLinkRecord,
+  ElementJSONInit,
+  LinkJSONInit,
 } from './types/cell.types';
+/** @group Types */
+export type { LiteralUnion, Nullable } from './types';
 
 /**
  * Element types and utilities
@@ -222,6 +272,13 @@ export type { InferElement } from './utils/create';
 /** @group Presets */
 export { elementPort, elementPorts, elementAttributes } from './presets';
 /** @group Types */
+export type {
+  ElementAttributes,
+  ElementPresetAttributes,
+  LinkAttributes,
+  LinkPresetAttributes,
+} from './presets';
+/** @group Types */
 export type { ElementRecord, ElementPosition, ElementSize } from './types/cell.types';
 /** @group Types */
 export type { ElementPort, ElementPortShape } from './presets';
@@ -273,6 +330,8 @@ export type {
   LinkRoutingStraightOptions,
   LinkRoutingOrthogonalOptions,
   LinkRoutingSmoothOptions,
+  LinkRouting,
+  BaseLinkOptions,
 } from './presets';
 /** @group Types */
 export type { LinkMarkerName, LinkMarker } from './theme/named-link-markers';
@@ -306,4 +365,4 @@ export { jsx } from './utils/joint-jsx/jsx-to-markup';
  */
 export { useLinkLayout } from './hooks/use-link-layout';
 /** @group Types */
-export type { LinkLayout } from './types/cell.types';
+export type { ElementLayout, LinkLayout } from './types/cell.types';

packages/joint-react/src/presets/cell-interactivity.ts

@@ -38,7 +38,7 @@ export interface CellInteractivityParams {
  * returns either a boolean or the native `InteractivityOptions` object.
  * @group Types
  */
-type CellInteractivityCallback = (
+export type CellInteractivityCallback = (
   context: CellInteractivityParams
 ) => boolean | dia.CellView.InteractivityOptions;
 

packages/joint-react/src/presets/index.ts

@@ -6,6 +6,8 @@ export {
   type LinkRoutingStraightOptions,
   type LinkRoutingOrthogonalOptions,
   type LinkRoutingSmoothOptions,
+  type LinkRouting,
+  type BaseLinkOptions,
 } from './link-routing';
 export {
   linkMarkerArrow,
@@ -54,7 +56,43 @@ export {
   type ValidateUnembeddingParams,
 } from './can-embed';
 export { type CellVisibility, type CellVisibilityParams } from './cell-visibility';
-export { type CellInteractivity, type CellInteractivityParams } from './cell-interactivity';
-export { elementAttributes } from './element-attributes';
-export { linkAttributes } from './link-attributes';
-export { type PaperEventMap, type PaperEventHandler } from './paper-events';
+export {
+  type CellInteractivity,
+  type CellInteractivityCallback,
+  type CellInteractivityParams,
+} from './cell-interactivity';
+export {
+  elementAttributes,
+  type ElementAttributes,
+  type ElementPresetAttributes,
+} from './element-attributes';
+export { linkAttributes, type LinkAttributes, type LinkPresetAttributes } from './link-attributes';
+export {
+  type PaperEventMap,
+  type PaperEventHandler,
+  type PaperEventHandlers,
+  type PointerCellEventParams,
+  type PointerElementEventParams,
+  type PointerLinkEventParams,
+  type PointerBlankEventParams,
+  type FocusCellEventParams,
+  type FocusElementEventParams,
+  type FocusLinkEventParams,
+  type HoverCellEventParams,
+  type HoverElementEventParams,
+  type HoverLinkEventParams,
+  type HoverBlankEventParams,
+  type WheelCellEventParams,
+  type WheelElementEventParams,
+  type WheelLinkEventParams,
+  type WheelBlankEventParams,
+  type MagnetEventParams,
+  type LinkConnectEventParams,
+  type PaperHoverEventParams,
+  type PaperPanEventParams,
+  type PaperPinchEventParams,
+  type TranslateEventParams,
+  type ScaleEventParams,
+  type ResizeEventParams,
+  type TransformEventParams,
+} from './paper-events';

packages/joint-react/src/presets/link-routing.ts

@@ -29,7 +29,11 @@ export interface LinkRouting {
   readonly defaultConnectionPoint?: dia.Paper.Options['defaultConnectionPoint'];
 }
 
-interface BaseLinkOptions {
+/**
+ * Options shared by every link routing preset.
+ * @group Types
+ */
+export interface BaseLinkOptions {
   /** Which side of an element or port each link end attaches to; see {@link LinkMode} for how each value behaves. @default 'auto' */
   readonly mode?: LinkMode;
   /** Offset (in px) applied to the connection point at the source end. @default 0 */