@atlaskit/editor-plugin-table 1.7.3 → 2.0.1

package/src/__tests__/unit/keymap.ts

@@ -8,7 +8,6 @@ import {
 } from '@atlaskit/editor-tables/utils';
 import { PluginKey } from 'prosemirror-state';
 
-import type { EditorAnalyticsAPI } from '@atlaskit/editor-common/analytics';
 import {
   createProsemirrorEditorFactory,
   LightEditorPlugin,
@@ -29,10 +28,6 @@ import {
 import { pmNodeBuilder } from '@atlaskit/editor-test-helpers/schema-element-builder';
 import defaultSchema from '@atlaskit/editor-test-helpers/schema';
 import sendKeyToPm from '@atlaskit/editor-test-helpers/send-key-to-pm';
-import {
-  CreateUIAnalyticsEvent,
-  UIAnalyticsEvent,
-} from '@atlaskit/analytics-next';
 import { uuid } from '@atlaskit/adf-schema';
 import { uuid as tablesUuid } from '@atlaskit/editor-tables';
 
@@ -42,8 +37,7 @@ import expandPlugin from '@atlaskit/editor-core/src/plugins/expand';
 import tasksDecisionsPlugin from '@atlaskit/editor-core/src/plugins/tasks-and-decisions';
 import selectionPlugin from '@atlaskit/editor-core/src/plugins/selection';
 import mediaPlugin from '@atlaskit/editor-core/src/plugins/media';
-import deprecatedAnalyticsPlugin from '@atlaskit/editor-core/src/plugins/analytics';
-import { analyticsPlugin } from '@atlaskit/editor-plugin-analytics';
+import type { analyticsPlugin } from '@atlaskit/editor-plugin-analytics';
 import listPlugin from '@atlaskit/editor-core/src/plugins/list';
 import blockTypePlugin from '@atlaskit/editor-core/src/plugins/block-type';
 import codeBlockPlugin from '@atlaskit/editor-core/src/plugins/code-block';
@@ -67,6 +61,16 @@ import { decorationsPlugin } from '@atlaskit/editor-plugin-decorations';
 
 const TABLE_LOCAL_ID = 'test-table-local-id';
 
+// We don't need to test if the analytics implementation works (tested elsewhere)
+// We just want to know if the action is called.
+const mockAttachPayload = jest.fn();
+const analyticsPluginFake = () => ({
+  name: 'analytics',
+  actions: {
+    attachAnalyticsEvent: mockAttachPayload.mockImplementation(() => () => {}),
+  },
+});
+
 describe('table keymap', () => {
   beforeAll(() => {
     uuid.setStatic(TABLE_LOCAL_ID);
@@ -78,27 +82,16 @@ describe('table keymap', () => {
     tablesUuid.setStatic(false);
   });
 
-  let editorAnalyticsAPIFake: EditorAnalyticsAPI = {
-    attachAnalyticsEvent: jest.fn().mockReturnValue(jest.fn()),
-  };
-  const createAnalyticsEvent: CreateUIAnalyticsEvent = jest.fn(
-    () => ({ fire() {} } as UIAnalyticsEvent),
-  );
-
   const createEditor = createProsemirrorEditorFactory();
   const preset = new Preset<LightEditorPlugin>()
     .add([featureFlagsPlugin, {}])
-    .add([analyticsPlugin, { createAnalyticsEvent }])
-    .add([deprecatedAnalyticsPlugin, { createAnalyticsEvent }])
+    .add([analyticsPluginFake as unknown as typeof analyticsPlugin, {}])
     .add(contentInsertionPlugin)
     .add(decorationsPlugin)
     .add(widthPlugin)
     .add(gridPlugin)
     .add(selectionPlugin)
-    .add([
-      tablePlugin,
-      { tableOptions: {}, editorAnalyticsAPI: editorAnalyticsAPIFake },
-    ])
+    .add([tablePlugin, { tableOptions: {} }])
     .add(expandPlugin)
     .add(tasksDecisionsPlugin)
     .add(panelPlugin)
@@ -604,7 +597,7 @@ describe('table keymap', () => {
     });
 
     it('should dispatch analytics event', () => {
-      expect(editorAnalyticsAPIFake.attachAnalyticsEvent).toBeCalledWith({
+      expect(mockAttachPayload).toBeCalledWith({
         action: 'inserted',
         actionSubject: 'document',
         actionSubjectId: 'table',

package/src/__tests__/unit/pm-plugins/table-resizing/event-handlers.ts

@@ -25,7 +25,6 @@ import { TextSelection, NodeSelection, EditorState } from 'prosemirror-state';
 import { EditorView } from 'prosemirror-view';
 import panelPlugin from '@atlaskit/editor-core/src/plugins/panel';
 import { widthPlugin } from '@atlaskit/editor-plugin-width';
-import type { EditorAnalyticsAPI } from '@atlaskit/editor-common/analytics';
 import {
   akEditorFullPageMaxWidth,
   akEditorDefaultLayoutWidth,
@@ -35,10 +34,17 @@ import featureFlagsPlugin from '@atlaskit/editor-plugin-feature-flags';
 import { contentInsertionPlugin } from '@atlaskit/editor-plugin-content-insertion';
 import { decorationsPlugin } from '@atlaskit/editor-plugin-decorations';
 
+// We don't need to test if the analytics implementation works (tested elsewhere)
+// We just want to know if the action is called.
+const mockAttachPayload = jest.fn();
+const analyticsPluginFake = () => ({
+  name: 'analytics',
+  actions: {
+    attachAnalyticsEvent: mockAttachPayload.mockImplementation(() => () => {}),
+  },
+});
+
 describe('table-resizing/event-handlers', () => {
-  const editorAnalyticsAPIFake: EditorAnalyticsAPI = {
-    attachAnalyticsEvent: jest.fn().mockReturnValue(() => jest.fn()),
-  };
   let editor: any;
   beforeEach(() => {
     const createEditor = createProsemirrorEditorFactory();
@@ -48,7 +54,7 @@ describe('table-resizing/event-handlers', () => {
         attachTo: document.body,
         preset: new Preset<LightEditorPlugin>()
           .add([featureFlagsPlugin, {}])
-          .add([analyticsPlugin, {}])
+          .add([analyticsPluginFake as unknown as typeof analyticsPlugin, {}])
           .add(contentInsertionPlugin)
           .add(decorationsPlugin)
           .add(widthPlugin)
@@ -56,7 +62,6 @@ describe('table-resizing/event-handlers', () => {
             tablePlugin,
             {
               tableOptions: { allowColumnResizing: true },
-              editorAnalyticsAPI: editorAnalyticsAPIFake,
             },
           ])
           .add(panelPlugin),
@@ -72,7 +77,7 @@ describe('table-resizing/event-handlers', () => {
 
       resizeColumn(view, 12, 150, 250);
 
-      expect(editorAnalyticsAPIFake.attachAnalyticsEvent).toHaveBeenCalledWith(
+      expect(mockAttachPayload).toHaveBeenCalledWith(
         expect.objectContaining({
           action: TABLE_ACTION.ATTEMPTED_TABLE_WIDTH_CHANGE,
           actionSubject: ACTION_SUBJECT.TABLE,

package/src/plugins/table/index.tsx

@@ -32,7 +32,6 @@ import { toolbarInsertBlockMessages as messages } from '@atlaskit/editor-common/
 
 import { IconTable } from '@atlaskit/editor-common/icons';
 
-import type { EditorAnalyticsAPI } from '@atlaskit/editor-common/analytics';
 import type { EditorSelectionAPI } from '@atlaskit/editor-common/selection';
 
 import { pluginConfig } from './create-plugin-config';
@@ -80,7 +79,6 @@ interface TablePluginOptions {
   // TODO these two need to be rethought
   fullWidthEnabled?: boolean;
   wasFullWidthEnabled?: boolean;
-  editorAnalyticsAPI?: EditorAnalyticsAPI;
   editorSelectionAPI?: EditorSelectionAPI;
   getEditorFeatureFlags?: GetEditorFeatureFlags;
 }
@@ -110,6 +108,7 @@ const tablesPlugin: NextEditorPlugin<
     };
     return api?.dependencies.width.sharedState.currentState() ?? defaultState;
   };
+  const editorAnalyticsAPI = api?.dependencies.analytics?.actions;
 
   return {
     name: 'table',
@@ -165,13 +164,8 @@ const tablesPlugin: NextEditorPlugin<
               wasFullWidthEnabled,
               breakoutEnabled,
               tableOptions,
-              editorAnalyticsAPI,
               getEditorFeatureFlags,
-            } =
-              options ||
-              ({
-                editorAnalyticsAPI: api?.dependencies.analytics?.actions,
-              } as TablePluginOptions);
+            } = options || ({} as TablePluginOptions);
             return createPlugin(
               dispatchAnalyticsEvent,
               dispatch,
@@ -191,12 +185,8 @@ const tablesPlugin: NextEditorPlugin<
         {
           name: 'tablePMColResizing',
           plugin: ({ dispatch }) => {
-            const {
-              fullWidthEnabled,
-              tableOptions,
-              editorAnalyticsAPI,
-              getEditorFeatureFlags,
-            } = options || ({} as TablePluginOptions);
+            const { fullWidthEnabled, tableOptions, getEditorFeatureFlags } =
+              options || ({} as TablePluginOptions);
             const { allowColumnResizing } = pluginConfig(tableOptions);
             return allowColumnResizing
               ? createFlexiResizingPlugin(
@@ -217,10 +207,7 @@ const tablesPlugin: NextEditorPlugin<
         {
           name: 'tableKeymap',
           plugin: () =>
-            keymapPlugin(
-              defaultGetEditorContainerWidth,
-              options?.editorAnalyticsAPI,
-            ),
+            keymapPlugin(defaultGetEditorContainerWidth, editorAnalyticsAPI),
         },
         {
           name: 'tableSelectionKeymap',
@@ -239,7 +226,7 @@ const tablesPlugin: NextEditorPlugin<
                 tr: Transaction;
                 reason: string;
               }) => {
-                options?.editorAnalyticsAPI?.attachAnalyticsEvent({
+                editorAnalyticsAPI?.attachAnalyticsEvent({
                   action: TABLE_ACTION.FIXED,
                   actionSubject: ACTION_SUBJECT.TABLE,
                   actionSubjectId: null,
@@ -374,7 +361,7 @@ const tablesPlugin: NextEditorPlugin<
                     !!resizingPluginState && !!resizingPluginState.dragging
                   }
                   stickyHeader={stickyHeader}
-                  editorAnalyticsAPI={options?.editorAnalyticsAPI}
+                  editorAnalyticsAPI={editorAnalyticsAPI}
                 />
               ) : null;
 
@@ -415,7 +402,7 @@ const tablesPlugin: NextEditorPlugin<
                       scrollableElement={popupsScrollableElement}
                       hasStickyHeaders={stickyHeader && stickyHeader.sticky}
                       dispatchAnalyticsEvent={dispatchAnalyticsEvent}
-                      editorAnalyticsAPI={options?.editorAnalyticsAPI}
+                      editorAnalyticsAPI={editorAnalyticsAPI}
                       getEditorContainerWidth={defaultGetEditorContainerWidth}
                     />
                   )}
@@ -426,7 +413,7 @@ const tablesPlugin: NextEditorPlugin<
                     targetCellPosition={targetCellPosition}
                     isOpen={Boolean(isContextualMenuOpen)}
                     pluginConfig={pluginConfig}
-                    editorAnalyticsAPI={options?.editorAnalyticsAPI}
+                    editorAnalyticsAPI={editorAnalyticsAPI}
                     getEditorContainerWidth={defaultGetEditorContainerWidth}
                     getEditorFeatureFlags={
                       options?.getEditorFeatureFlags ||
@@ -445,7 +432,7 @@ const tablesPlugin: NextEditorPlugin<
                       isNumberColumnEnabled={
                         tableNode && tableNode.attrs.isNumberColumnEnabled
                       }
-                      editorAnalyticsAPI={options?.editorAnalyticsAPI}
+                      editorAnalyticsAPI={editorAnalyticsAPI}
                     />
                   )}
                   {LayoutContent}
@@ -473,7 +460,7 @@ const tablesPlugin: NextEditorPlugin<
                 schema: state.schema,
               }),
             );
-            options?.editorAnalyticsAPI?.attachAnalyticsEvent({
+            editorAnalyticsAPI?.attachAnalyticsEvent({
               action: ACTION.INSERTED,
               actionSubject: ACTION_SUBJECT.DOCUMENT,
               actionSubjectId: ACTION_SUBJECT_ID.TABLE,
@@ -486,7 +473,7 @@ const tablesPlugin: NextEditorPlugin<
       ],
       floatingToolbar: getToolbarConfig(
         defaultGetEditorContainerWidth,
-        options?.editorAnalyticsAPI,
+        editorAnalyticsAPI,
         options?.getEditorFeatureFlags || defaultGetEditorFeatureFlags,
         () => editorViewRef.current,
       )(pluginConfig(options?.tableOptions)),

package/src/plugins/table/nodeviews/TableComponent.tsx

@@ -48,7 +48,6 @@ import {
 import type { TableOptions } from './types';
 import { updateOverflowShadows } from './update-overflow-shadows';
 import type { EventDispatcher } from '@atlaskit/editor-common/event-dispatcher';
-
 import memoizeOne from 'memoize-one';
 import { OverflowShadowsObserver } from './OverflowShadowsObserver';
 import { TableContainer } from './TableContainer';
@@ -151,7 +150,9 @@ class TableComponent extends React.Component<ComponentProps, TableState> {
        * We no longer use `containerWidth` as a variable to determine an update for table resizing (avoids unnecessary updates).
        * Instead we use the resize event to only trigger updates when necessary.
        */
-      window.addEventListener('resize', this.handleWindowResizeDebounced);
+      if (!getBooleanFF('platform.editor.custom-table-width')) {
+        window.addEventListener('resize', this.handleWindowResizeDebounced);
+      }
       this.handleTableResizingDebounced();
     }
 
@@ -175,9 +176,14 @@ class TableComponent extends React.Component<ComponentProps, TableState> {
     this.scaleTableDebounced.cancel();
     this.handleTableResizingDebounced.cancel();
     this.handleAutoSizeDebounced.cancel();
-    this.handleWindowResizeDebounced.cancel();
+    if (!getBooleanFF('platform.editor.custom-table-width')) {
+      this.handleWindowResizeDebounced.cancel();
+    }
 
-    if (this.props.allowColumnResizing) {
+    if (
+      !getBooleanFF('platform.editor.custom-table-width') &&
+      this.props.allowColumnResizing
+    ) {
       window.removeEventListener('resize', this.handleWindowResizeDebounced);
     }
 

package/src/plugins/table/nodeviews/TableContainer.tsx

@@ -14,6 +14,7 @@ import { calcTableWidth } from '@atlaskit/editor-common/styles';
 
 import { TableCssClassName as ClassName } from '../types';
 import { TableResizer } from './TableResizer';
+import { TABLE_MAX_WIDTH } from '../pm-plugins/table-resizing/utils';
 
 interface GetMarginLeftOpts {
   lineLength: number;
@@ -35,22 +36,21 @@ const getMarginLeft = ({ lineLength, tableWidth }: GetMarginLeftOpts) => {
 
 type InnerContainerProps = {
   className: string;
-  marginLeft: number | undefined;
-  width: number | 'inherit';
+  style?: {
+    width: number | 'inherit';
+    marginLeft: number | undefined;
+  };
   node: PMNode;
 };
 
 export const InnerContainer = forwardRef<
   HTMLDivElement,
   PropsWithChildren<InnerContainerProps>
->(({ marginLeft, className, width, node, children }, ref) => {
+>(({ className, style, node, children }, ref) => {
   return (
     <div
       ref={ref}
-      style={{
-        width,
-        marginLeft,
-      }}
+      style={style}
       className={className}
       data-number-column={node.attrs.isNumberColumnEnabled}
       data-layout={node.attrs.layout}
@@ -76,6 +76,7 @@ export const ResizableTableContainer = ({
   className,
   node,
   lineLength,
+  containerWidth,
   editorView,
   getPos,
   tableRef,
@@ -89,25 +90,32 @@ export const ResizableTableContainer = ({
         return;
       }
 
-      innerContainerRef.current.style.width = `${width}px`;
-
       const marginLeft = getMarginLeft({
         lineLength,
         tableWidth: width,
       });
 
-      containerRef.current.style.width = `${width}px`;
-      containerRef.current.style.marginLeft = `${marginLeft}px`;
+      if (marginLeft) {
+        containerRef.current.style.marginLeft = `${marginLeft}px`;
+      }
     },
     [lineLength],
   );
 
-  const width = getTableContainerWidth(node);
+  const tableWidth = getTableContainerWidth(node);
+
+  // 76 is currently an accepted padding value considering the spacing for resizer handle
+  const responsiveContainerWidth = containerWidth - 76;
+
+  const width = Math.min(tableWidth, responsiveContainerWidth);
+
   const marginLeft = getMarginLeft({
     lineLength,
     tableWidth: width,
   });
 
+  const maxResizerWidth = Math.min(responsiveContainerWidth, TABLE_MAX_WIDTH);
+
   return (
     <div
       style={{ marginLeft, width }}
@@ -116,6 +124,7 @@ export const ResizableTableContainer = ({
     >
       <TableResizer
         width={width}
+        maxWidth={maxResizerWidth}
         updateWidth={updateWidth}
         editorView={editorView}
         getPos={getPos}
@@ -126,8 +135,6 @@ export const ResizableTableContainer = ({
           ref={innerContainerRef}
           className={className}
           node={node}
-          width={width}
-          marginLeft={0}
         >
           {children}
         </InnerContainer>
@@ -188,11 +195,13 @@ export const TableContainer = ({
     <InnerContainer
       node={node}
       className={className}
-      width={tableWidth}
-      marginLeft={getMarginLeft({
-        lineLength: lineLength!,
-        tableWidth,
-      })}
+      style={{
+        width: tableWidth,
+        marginLeft: getMarginLeft({
+          lineLength: lineLength!,
+          tableWidth,
+        }),
+      }}
     >
       {children}
     </InnerContainer>

package/src/plugins/table/nodeviews/TableResizer.tsx

@@ -10,11 +10,11 @@ import {
   previewScaleTable,
   getColgroupChildrenLength,
   COLUMN_MIN_WIDTH,
-  TABLE_MAX_WIDTH,
 } from '../pm-plugins/table-resizing/utils';
 
 interface TableResizerProps {
   width: number;
+  maxWidth: number;
   updateWidth: (width: number) => void;
   editorView: EditorView;
   getPos: () => number | undefined;
@@ -27,6 +27,7 @@ const handles = { right: true };
 export const TableResizer = ({
   children,
   width,
+  maxWidth,
   updateWidth,
   editorView,
   getPos,
@@ -99,7 +100,7 @@ export const TableResizer = ({
       }}
       resizeRatio={2}
       minWidth={minColumnWidth}
-      maxWidth={TABLE_MAX_WIDTH}
+      maxWidth={maxWidth}
     >
       {children}
     </ResizerNext>

package/src/plugins/table/nodeviews/table.tsx

@@ -29,16 +29,22 @@ import { TableMap } from '@atlaskit/editor-tables/table-map';
 import TableComponent from './TableComponent';
 import { Props, TableOptions } from './types';
 import type { TableColumnOrdering } from '@atlaskit/adf-schema/steps';
+import { getBooleanFF } from '@atlaskit/platform-feature-flags';
+import { getTableContainerWidth } from '@atlaskit/editor-common/node-width';
 
 type ForwardRef = (node: HTMLElement | null) => void;
 
 const tableAttributes = (node: PmNode) => {
+  const style = getBooleanFF('platform.editor.custom-table-width')
+    ? `width: ${getTableContainerWidth(node)}px`
+    : undefined;
   return {
     'data-number-column': node.attrs.isNumberColumnEnabled,
     'data-layout': node.attrs.layout,
     'data-autosize': node.attrs.__autoSize,
     'data-table-local-id': node.attrs.localId || '',
     'data-table-width': node.attrs.width,
+    style,
   };
 };
 

package/src/plugins/table/pm-plugins/table-resizing/utils/scale-table.ts

@@ -5,6 +5,7 @@ import { tableCellMinWidth } from '@atlaskit/editor-common/styles';
 import { akEditorTableNumberColumnWidth } from '@atlaskit/editor-shared-styles';
 
 import type { DomAtPos } from 'prosemirror-utils';
+import { getBooleanFF } from '@atlaskit/platform-feature-flags';
 
 import { getTableWidth } from '../../../utils';
 import { getLayoutSize } from '../utils/misc';
@@ -152,7 +153,15 @@ export const previewScaleTable = (
 ) => {
   const { node, start, parentWidth } = options;
 
-  if (!tableRef || !hasTableBeenResized(node)) {
+  if (!tableRef) {
+    return;
+  }
+
+  if (getBooleanFF('platform.editor.custom-table-width') && parentWidth) {
+    tableRef.style.width = `${parentWidth}px`;
+  }
+
+  if (!hasTableBeenResized(node)) {
     return;
   }
 

package/tmp/api-report-tmp.d.ts

@@ -1,107 +0,0 @@
-## API Report File for "@atlaskit/editor-plugin-table"
-
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
-```ts
-
-import { AnalyticsEventPayload } from '@atlaskit/editor-common/analytics';
-import type { analyticsPlugin } from '@atlaskit/editor-plugin-analytics';
-import type { Command } from '@atlaskit/editor-common/types';
-import type { contentInsertionPlugin } from '@atlaskit/editor-plugin-content-insertion';
-import type { EditorAnalyticsAPI } from '@atlaskit/editor-common/analytics';
-import type { EditorSelectionAPI } from '@atlaskit/editor-common/selection';
-import type { GetEditorFeatureFlags } from '@atlaskit/editor-common/types';
-import type { NextEditorPlugin } from '@atlaskit/editor-common/types';
-import { TableLayout } from '@atlaskit/adf-schema';
-import type { widthPlugin } from '@atlaskit/editor-plugin-width';
-
-// @public (undocumented)
-type InsertTableAction = (analyticsPayload: AnalyticsEventPayload) => Command;
-
-// @public (undocumented)
-type PermittedLayoutsDescriptor = 'all' | TableLayout[];
-
-// @public (undocumented)
-interface PluginConfig {
-    // (undocumented)
-    advanced?: boolean;
-    // (undocumented)
-    allowAddColumnWithCustomStep?: boolean;
-    // (undocumented)
-    allowBackgroundColor?: boolean;
-    // (undocumented)
-    allowCellOptionsInFloatingToolbar?: boolean;
-    // (undocumented)
-    allowCollapse?: boolean;
-    // (undocumented)
-    allowColumnResizing?: boolean;
-    // (undocumented)
-    allowColumnSorting?: boolean;
-    // (undocumented)
-    allowControls?: boolean;
-    // (undocumented)
-    allowDistributeColumns?: boolean;
-    // (undocumented)
-    allowHeaderColumn?: boolean;
-    // (undocumented)
-    allowHeaderRow?: boolean;
-    // (undocumented)
-    allowMergeCells?: boolean;
-    // (undocumented)
-    allowNumberColumn?: boolean;
-    // (undocumented)
-    initialRenderOptimization?: boolean;
-    // (undocumented)
-    isHeaderRowRequired?: boolean;
-    // (undocumented)
-    mouseMoveOptimization?: boolean;
-    // (undocumented)
-    permittedLayouts?: PermittedLayoutsDescriptor;
-    // (undocumented)
-    stickyHeaders?: boolean;
-    // (undocumented)
-    stickyHeadersOptimization?: boolean;
-    // (undocumented)
-    tableCellOptimization?: boolean;
-    // (undocumented)
-    tableOverflowShadowsOptimization?: boolean;
-    // (undocumented)
-    tableRenderOptimization?: boolean;
-}
-
-// @public (undocumented)
-interface TablePluginOptions {
-    // (undocumented)
-    allowContextualMenu?: boolean;
-    // (undocumented)
-    breakoutEnabled?: boolean;
-    // (undocumented)
-    editorAnalyticsAPI?: EditorAnalyticsAPI;
-    // (undocumented)
-    editorSelectionAPI?: EditorSelectionAPI;
-    // (undocumented)
-    fullWidthEnabled?: boolean;
-    // (undocumented)
-    getEditorFeatureFlags?: GetEditorFeatureFlags;
-    // (undocumented)
-    tableOptions: PluginConfig;
-    // (undocumented)
-    wasFullWidthEnabled?: boolean;
-}
-
-// @public (undocumented)
-export const tablesPlugin: NextEditorPlugin<'table', {
-    pluginConfiguration: TablePluginOptions | undefined;
-    actions: {
-        insertTable: InsertTableAction;
-    };
-    dependencies: [
-    typeof analyticsPlugin,
-    typeof contentInsertionPlugin,
-    typeof widthPlugin
-    ];
-}>;
-
-// (No @packageDocumentation comment for this package)
-
-```