refactor(joint-react): coherent event-related public type names

packages/joint-react/.storybook/main.ts

@@ -61,7 +61,6 @@ const config: StorybookConfig = {
     config.resolve.alias = [
       // Subpath exports must come before the bare package alias
       { find: '@joint/react/internal', replacement: path.resolve(__dirname, '../src/internal.ts') },
-      { find: '@joint/react/presets', replacement: path.resolve(__dirname, '../src/presets/index.ts') },
       { find: /^@joint\/react$/, replacement: path.resolve(__dirname, '../src/index.ts') },
     ];
     // Pre-bundle the heavy `@joint/core` dep. It resolves through a

packages/joint-react/src/components/html-box.tsx

@@ -17,6 +17,11 @@ const AUTO_SIZE_STYLE: CSSProperties = {
   maxWidth: 200,
 };
 
+/**
+ * Props for the HTMLBox component, extending HTMLHostProps.
+ */
+export type HTMLBoxProps = HTMLHostProps;
+
 /**
  * Default themed HTML host that applies the `jj-box` CSS class.
  * Wraps {@link HTMLHost} (style-neutral foreignObject + measured div) and adds
@@ -32,7 +37,7 @@ const AUTO_SIZE_STYLE: CSSProperties = {
  * <Paper renderElement={({ label }) => <DefaultHTMLHost>{label}</DefaultHTMLHost>} />
  * ```
  */
-export function HTMLBox(props: Readonly<HTMLHostProps> = {}) {
+export function HTMLBox(props: Readonly<HTMLBoxProps> = {}) {
   const { className, style, useModelGeometry, ...rest } = props;
   const mergedClassName = className ? `jj-box ${className}` : 'jj-box';
   const baseStyle = useModelGeometry ? BASE_STYLE : { ...BASE_STYLE, ...AUTO_SIZE_STYLE };

packages/joint-react/src/components/paper/paper.types.ts

@@ -16,7 +16,7 @@ import type {
 import type { CellVisibility } from '../../presets/cell-visibility';
 import type { Interactive } from '../../presets/interactive';
 import type { LinkRouting } from '../../presets/link-routing';
-import type { NormalizedPaperHandlers } from '../../presets/paper-events';
+import type { PaperEventHandlers } from '../../presets/paper-events';
 
 /**
  * Value accepted by the Paper `transform` prop. Strings are parsed via the
@@ -27,7 +27,7 @@ import type { NormalizedPaperHandlers } from '../../presets/paper-events';
 export type PaperTransform = string | DOMMatrix;
 
 /** Context passed to the `defaultLink` factory. */
-export interface DefaultLinkContext {
+export interface DefaultLinkParams {
   /** The source end of the connection being created. */
   readonly source: ConnectionEnd;
   /** The paper instance. */
@@ -38,10 +38,10 @@ export interface DefaultLinkContext {
 
 /**
  * Value accepted by the Paper `defaultLink` prop — factory receiving
- * `DefaultLinkContext`, or a static `Partial<LinkRecord>`.
+ * `DefaultLinkParams`, or a static `Partial<LinkRecord>`.
  */
 export type DefaultLink =
-  | ((context: DefaultLinkContext) => dia.Link | Partial<LinkRecord>)
+  | ((context: DefaultLinkParams) => dia.Link | Partial<LinkRecord>)
   | Partial<LinkRecord>;
 
 /**
@@ -166,7 +166,7 @@ export interface PortalPaperOptions {
    * Values inside `options` override matching keys here.
    * @example
    * ```tsx
-   * import { linkRoutingOrthogonal } from '@joint/react/presets';
+   * import { linkRoutingOrthogonal } from '@joint/react';
    *
    * <Paper linkRouting={linkRoutingOrthogonal()} />
    * ```
@@ -222,9 +222,9 @@ export type RenderLink<LinkData = unknown> = (data: LinkData) => ReactNode;
  * The props for the Paper component. Extend the `dia.Paper.Options` interface.
  * For more information, see the JointJS documentation.
  *
- * Normalized paper events are exposed directly as props
+ * Paper events are exposed directly as props
  * (`onBlankContextMenu`, `onElementPointerClick`, `onLinkMouseEnter`, …) via
- * {@link NormalizedPaperHandlers}. Each handler receives a single context
+ * {@link PaperEventHandlers}. Each handler receives a single params
  * object — e.g. `onBlankContextMenu={({ paper, event, x, y }) => …}`.
  *
  * Handlers participate in the event subscription's dependency list, exactly
@@ -233,11 +233,11 @@ export type RenderLink<LinkData = unknown> = (data: LinkData) => ReactNode;
  * module-level function — so the paper subscribes once. A new inline arrow on
  * every render (`onBlankContextMenu={() => …}`) re-subscribes that paper's
  * events on every render; correct, but wasteful. For raw native event names or
- * events without a normalized form (`resize`, `transform`, `render:done`, …),
+ * events without an `on*` form (`resize`, `transform`, `render:done`, …),
  * use the `usePaperEvents` hook.
  * @see https://docs.jointjs.com/api/dia/Paper
  */
-export interface PaperProps extends PortalPaperOptions, PropsWithChildren, NormalizedPaperHandlers {
+export interface PaperProps extends PortalPaperOptions, PropsWithChildren, PaperEventHandlers {
   /**
    * A function that renders the element.
    *

packages/joint-react/src/hooks/use-create-portal-paper.tsx

@@ -97,7 +97,7 @@ function getLinkModelConstructor(graph: dia.Graph): LinkModelConstructor {
 
 /**
  * Creates a JointJS-compatible `defaultLink` callback from the React prop.
- * Wraps the user-facing `DefaultLinkContext` API and converts `LinkRecord` results
+ * Wraps the user-facing `DefaultLinkParams` API and converts `LinkRecord` results
  * into JointJS link model instances.
  * @param defaultLink
  */

packages/joint-react/src/hooks/use-measure-node.tsx

@@ -1,7 +1,7 @@
 import { useContext, useLayoutEffect, type RefObject } from 'react';
 import { CellIdContext } from '../context';
 import { useGraphStore } from './use-graph-store';
-import type { TransformMeasurement } from '../store/create-elements-size-observer';
+import type { TransformElementLayout } from '../store/create-elements-size-observer';
 import { usePaper } from './use-paper';
 import type { ElementSize } from '../types/cell.types';
 import { useCell } from './use-cell';
@@ -29,7 +29,7 @@ export interface MeasureNodeOptions {
    * useMeasureNode(nodeRef, { transform });
    * ```
    */
-  readonly transform?: TransformMeasurement;
+  readonly transform?: TransformElementLayout;
 }
 
 const EMPTY_OBJECT: MeasureNodeOptions = {};

packages/joint-react/src/hooks/use-paper-events.ts

@@ -9,7 +9,7 @@ const EMPTY_DEPENDENCIES: DependencyList = [];
 const EMPTY_HANDLERS: PaperEventMap = {};
 
 /**
- * Distinguishes a `PaperEventMap` (a plain object) from a `DependencyList`
+ * Distinguishes a `PaperEventMap` map (a plain object) from a `DependencyList`
  * (an array) — used to resolve the overloaded second argument without casts.
  * @param value - The handlers-or-dependencies argument.
  * @returns True when `value` is a handlers map rather than a dependency list.
@@ -18,8 +18,8 @@ function isPaperEventMap(value: PaperEventMap | DependencyList): value is PaperE
   return !Array.isArray(value);
 }
 
-/** Normalized {@link usePaperEvents} arguments. */
-interface ResolvedPaperEventsArgs {
+/** Resolved {@link usePaperEvents} arguments. */
+interface ResolvedPaperEventMapArgs {
   readonly target: PaperTarget | undefined;
   readonly handlers: PaperEventMap;
   readonly dependencies: DependencyList;
@@ -33,11 +33,11 @@ interface ResolvedPaperEventsArgs {
  * @param dependenciesArgument - Third arg: dependencies (target form only).
  * @returns The resolved target, handlers, and dependencies.
  */
-function resolvePaperEventsArgs(
+function resolvePaperEventMapArgs(
   paperOrHandlers: PaperTarget | PaperEventMap,
   handlersOrDependencies: PaperEventMap | DependencyList,
   dependenciesArgument: DependencyList
-): ResolvedPaperEventsArgs {
+): ResolvedPaperEventMapArgs {
   if (!isPaperTarget(paperOrHandlers)) {
     // usePaperEvents(handlers, dependencies?)
     const dependencies = isPaperEventMap(handlersOrDependencies)
@@ -70,7 +70,7 @@ export function subscribeToPaperEvents(
  * throws if no `Paper` context is available). Two key forms can be mixed in
  * the same handlers map:
  *
- * **Normalized form**: `on<Category><Event>` keys deliver a single context
+ * **CamelCase form**: `on<Category><Event>` keys deliver a single params
  * object with named properties.
  * ```tsx
  * usePaperEvents({
@@ -80,7 +80,7 @@ export function subscribeToPaperEvents(
  * ```
  *
  * **Raw form**: native JointJS event names with positional arguments. Use
- * for events without a normalized counterpart (`'resize'`, `'transform'`,
+ * for events without an `on*` counterpart (`'resize'`, `'transform'`,
  * `'render:done'`, `'cell:highlight'`, …).
  * ```tsx
  * usePaperEvents(paperId, {
@@ -89,8 +89,8 @@ export function subscribeToPaperEvents(
  * });
  * ```
  *
- * The normalized context omits the React-store `record` — to read the
- * normalised record shape, call `useCell(id, selector)` from your own
+ * The `on*` params object omits the React-store `record` — to read the
+ * record shape, call `useCell(id, selector)` from your own
  * component (the handler closure has access to the `id` it emits).
  * @param handlers - Event handlers map.
  * @param dependencies - Optional dependency array controlling re-subscription.
@@ -114,7 +114,7 @@ export function usePaperEvents(
   handlersOrDependencies: PaperEventMap | DependencyList = EMPTY_DEPENDENCIES,
   dependenciesArgument: DependencyList = EMPTY_DEPENDENCIES
 ): void {
-  const { target, handlers, dependencies } = resolvePaperEventsArgs(
+  const { target, handlers, dependencies } = resolvePaperEventMapArgs(
     paperOrHandlers,
     handlersOrDependencies,
     dependenciesArgument

packages/joint-react/src/index.ts

@@ -22,22 +22,22 @@ export type {
   RenderElement,
   RenderLink,
   DefaultLink,
-  DefaultLinkContext,
+  DefaultLinkParams,
 } from './components/paper/paper.types';
 export type {
   PortalHostCell,
   PortalSelector,
-  PortalSelectorContext,
+  PortalSelectorParams,
 } from './mvc/react-paper.types';
 export type {
   ValidateConnection,
-  ValidateConnectionContext,
+  ValidateConnectionParams,
   ValidateEmbedding,
-  ValidateEmbeddingContext,
+  ValidateEmbeddingParams,
   ValidateUnembedding,
-  ValidateUnembeddingContext,
+  ValidateUnembeddingParams,
   ConnectionStrategy,
-  ConnectionStrategyContext,
+  ConnectionStrategyParams,
   ConnectionStrategyOptions,
   ConnectionStrategyPin,
   CanConnectOptions,
@@ -60,7 +60,7 @@ export type { HTMLHostProps } from './components/html-host';
  * <HTMLBox/>
  */
 export { HTMLBox } from './components/html-box';
-export type { HTMLHostProps as HTMLBoxProps } from './components/html-host';
+export type { HTMLBoxProps } from './components/html-box';
 
 // Hooks
 // -----
@@ -98,8 +98,8 @@ export { useCellId } from './hooks/use-cell-id';
 export { useMeasureNode } from './hooks/use-measure-node';
 export type { MeasureNodeOptions } from './hooks/use-measure-node';
 export type {
-  TransformMeasurement,
-  MeasurementContext,
+  TransformElementLayout,
+  TransformElementLayoutParams,
 } from './store/create-elements-size-observer';
 
 /**
@@ -111,7 +111,7 @@ export { useNodesMeasuredEffect } from './hooks/use-nodes-measured-effect';
  * usePaperEvents()
  */
 export { usePaperEvents } from './hooks/use-paper-events';
-export type { PaperEventMap } from './presets';
+export type { PaperEventMap, PaperEventHandler } from './presets';
 
 /**
  * useGraphEvents()
@@ -167,17 +167,58 @@ export type {
 /**
  * Element types and utilities
  */
+export { elementPort, elementPorts, elementAttributes } from './presets';
 export type { ElementRecord, ElementPosition, ElementSize } from './types/cell.types';
-export type { ElementPort, PortShape } from './presets';
+export type {
+  ElementPort,
+  ElementPortShape
+} from './presets';
 
 /**
  * Link types and utilities
  */
 export { resolveLinkMarker } from './theme/named-link-markers';
+export {
+  linkRoutingStraight,
+  linkRoutingOrthogonal,
+  linkRoutingSmooth,
+  linkLabel,
+  linkLabels,
+  linkStyle,
+  linkStyleLine,
+  linkStyleWrapper,
+  linkAttributes,
+  linkMarkerArrow,
+  linkMarkerArrowOpen,
+  linkMarkerArrowSunken,
+  linkMarkerArrowQuill,
+  linkMarkerArrowDouble,
+  linkMarkerCircle,
+  linkMarkerDiamond,
+  linkMarkerLine,
+  linkMarkerCross,
+  linkMarkerFork,
+  linkMarkerForkClose,
+  linkMarkerMany,
+  linkMarkerManyOptional,
+  linkMarkerOne,
+  linkMarkerOneOptional,
+  linkMarkerOneOrMany,
+} from './presets';
 export type { LinkRecord } from './types/cell.types';
-export type { LinkStyle, LinkLabel, LinkMarkerRecord } from './presets';
+export type {
+  LinkStyle,
+  LinkLabel,
+  LinkMarkerRecord,
+  LinkMarkerOptions,
+  LinkMode,
+  LinkRoutingStraightOptions,
+  LinkRoutingOrthogonalOptions,
+  LinkRoutingSmoothOptions,
+} from './presets';
 export type { LinkMarkerName, LinkMarker } from './theme/named-link-markers';
 
+
 // MVC
 // ---
 

packages/joint-react/src/mvc/react-paper.types.ts

@@ -24,7 +24,7 @@ export interface PortalHostCell {
 }
 
 /** Context passed to a `PortalSelector` callback. */
-export interface PortalSelectorContext {
+export interface PortalSelectorParams {
   /** The cell model. Has a `portalSelector` field when it opts into portal rendering. */
   readonly model: dia.Cell & PortalHostCell;
   /** The paper instance. */
@@ -39,7 +39,7 @@ export interface PortalSelectorContext {
  *
  * - A **string** is used directly as the selector for `cellView.findNode()`.
  * - **`null`** disables all portal rendering.
- * - A **function** receives a {@link PortalSelectorContext} and returns:
+ * - A **function** receives a {@link PortalSelectorParams} and returns:
  *   - a **selector string** — look up that node,
  *   - an **`Element`** — use that DOM node directly,
  *   - **`null`** — skip rendering for this cell,
@@ -48,7 +48,7 @@ export interface PortalSelectorContext {
 export type PortalSelector =
   | string
   | null
-  | ((context: PortalSelectorContext) => string | Element | null | undefined);
+  | ((context: PortalSelectorParams) => string | Element | null | undefined);
 
 /**
  * Options for creating a ReactPaper instance with lifecycle callbacks.

packages/joint-react/src/presets/can-connect.ts

@@ -15,7 +15,7 @@ export interface ConnectionEnd {
 }
 
 /** Structured context for connection validation. */
-export interface ValidateConnectionContext {
+export interface ValidateConnectionParams {
   /** The source end of the connection. */
   readonly source: ConnectionEnd;
   /** The target end of the connection. */
@@ -29,7 +29,7 @@ export interface ValidateConnectionContext {
 }
 
 /** Callback that decides whether a connection is allowed. */
-export type ValidateConnection = (context: ValidateConnectionContext) => boolean;
+export type ValidateConnection = (context: ValidateConnectionParams) => boolean;
 
 /**
  * Builds a `ConnectionEnd` from a cell view and its magnet element.
@@ -148,7 +148,7 @@ export interface CanConnectOptions {
    */
   readonly allowRootConnection?: boolean | 'auto';
   /** Custom validation on top of the built-in rules. Runs only if built-in checks pass. */
-  readonly validate?: (context: ValidateConnectionContext) => boolean;
+  readonly validate?: (context: ValidateConnectionParams) => boolean;
 }
 
 /**