@elliemae/ds-left-navigation 3.80.0-next.6 → 3.80.0-next.60

package/dist/types/exported-related/Icon/index.d.ts

@@ -1,5 +1,9 @@
 import React from 'react';
 import { type SvgIconT } from '@elliemae/ds-icons';
+/**
+ * The styled component is created once per Icon() call, not per render:
+ * a new component type on every render would remount the icon and drop its focus.
+ */
 export declare const Icon: (IconComponent: React.ComponentType<{
     color: unknown;
     tabIndex: number;

package/dist/types/exported-related/conversion-utils/conversionConstants.d.ts

@@ -0,0 +1,20 @@
+import { ITEM_TYPES } from '../../constants/index.js';
+export declare const DRILLDOWN_TYPES: string[];
+export declare const LEAF_TYPES: string[];
+/**
+ * Reads only own entries, so ids and types like "constructor" or "toString" do not resolve to inherited members.
+ */
+export declare const getOwn: <T>(map: Record<string, T>, key: string) => T | undefined;
+/**
+ * The types a `HeaderComponent` can have and still be the tree header: a header, or a leaf when the header is only a link.
+ */
+export declare const HEADER_TYPES: string[];
+export declare const OUT_OF_THE_BOX_TYPES: string[];
+/**
+ * LeftNavigation renders no `CollapsedComponent` for these types (it forces it to null), so they were never in its rail.
+ */
+export declare const NO_RAIL_TYPES: string[];
+export declare const DROPPED_TYPE_CODES: {
+    readonly [ITEM_TYPES.LEFT_NAV_ITEM_HEADER]: readonly ["header-item-dropped", "Header items are not part of the list"];
+    readonly [ITEM_TYPES.LEFT_NAV_ITEM_SKELETON]: readonly ["skeleton-dropped", "Skeleton items are not supported"];
+};

package/dist/types/exported-related/conversion-utils/conversionHelpers.d.ts

@@ -0,0 +1,25 @@
+import { type DSLeftNavigationTreeT } from '@elliemae/ds-left-navigation-tree';
+import type { DSLeftNavigationT } from '../../react-desc-prop-types.js';
+import type { DSLeftNavBridgeT } from './types.js';
+type OldItemT = DSLeftNavigationT.GenericItemItemProps;
+type NewItemT = DSLeftNavigationTreeT.Item;
+type ReportT = DSLeftNavBridgeT.ReportMutableT;
+type ConvertListArgsT = {
+    list: readonly OldItemT[];
+    isRoot: boolean;
+    /** The dsIds (or the items themselves, when they have none) of the submenus and drilldowns being expanded, to stop a branch that contains itself. */
+    ancestors?: readonly (string | OldItemT)[];
+    report: ReportT;
+    childrenByParentId: DSLeftNavBridgeT.ChildrenByParentIdT;
+};
+/**
+ * LeftNavigation lists are flat: a section is a label and the items that follow it belong to it until the next section or separator.
+ * The tree holds the children of a section inside it, so the conversion groups them.
+ */
+export declare const convertList: (args: ConvertListArgsT) => NewItemT[];
+/**
+ * Returns null when the header cannot be carried over: a skeleton (the same policy as the items of the list), or a custom
+ * `Component` (no type, or a type that is not out of the box).
+ */
+export declare const convertHeader: (header: OldItemT, report: ReportT) => NewItemT | null;
+export {};

package/dist/types/exported-related/conversion-utils/convertItemOpts.d.ts

@@ -0,0 +1,22 @@
+import type { DSLeftNavigationTreeT } from '@elliemae/ds-left-navigation-tree';
+import type { DSLeftNavigationT } from '../../react-desc-prop-types.js';
+import type { DSLeftNavBridgeT } from './types.js';
+type OldItemT = DSLeftNavigationT.GenericItemItemProps;
+type NewItemOptsT = DSLeftNavigationTreeT.ItemOpts;
+type ReportT = DSLeftNavBridgeT.ReportMutableT;
+type ConvertItemOptsArgsT = {
+    item: OldItemT;
+    report: ReportT;
+    /**
+     * Leaves and drilldowns carry `RightComponent` and `labelRightSection`, the header only its `RightComponent`.
+     * Submenus and the header keep their right side only as the chevron, and the tree draws its own arrow, so it is dropped.
+     */
+    kind: 'leaf' | 'drilldown' | 'submenu' | 'header' | 'section';
+    /** The caller merges labelRightSection into the label (sections), so it is not lost. */
+    joinable?: boolean;
+};
+/**
+ * Builds the tree item options shared by every converted type and records what could not be carried over.
+ */
+export declare const convertItemOpts: (args: ConvertItemOptsArgsT) => NewItemOptsT;
+export {};

package/dist/types/exported-related/conversion-utils/getHumanReadableWarnings.d.ts

@@ -0,0 +1,7 @@
+import type { DSLeftNavBridgeT } from './types.js';
+/**
+ * given the report, it will return a human readable list of warnings
+ * @param report - The report to get the warnings from.
+ * @returns A list of human readable warnings.
+ */
+export declare const getHumanReadableWarnings: (report: DSLeftNavBridgeT.ReportMutableT) => string[];

package/dist/types/exported-related/conversion-utils/index.d.ts

@@ -0,0 +1,12 @@
+import type { DSLeftNavBridgeT } from './types.js';
+import type { DSLeftNavigationT } from '../../react-desc-prop-types.js';
+/**
+ * Converts LeftNavigation items to DSLeftNavigationTree items and reports what the tree cannot carry over.
+ * It is a migration aid, not a drop-in replacement: read `report.humanReadableWarnings` and `report.lostEntries`.
+ * @param items - The LeftNavigation items (the flat list shown by the body).
+ * @param options - Children of the submenus (`childrenByParentId`), and the `HeaderComponent` and `BodyHeaderComponent` props.
+ * @returns The converted items and the report. `HeaderComponent` becomes `convertedHeader`, a disclosure, and
+ * `convertedHeaderItems` is its content (the list under the header `dsId` in `childrenByParentId`) to pass as `items`
+ * while it is open. A header that is only a link goes to the front of `convertedItems` with `headerAsFirstLeaf`.
+ */
+export declare const checkAndConvertItems: (items: readonly DSLeftNavigationT.GenericItemItemProps[], options?: DSLeftNavBridgeT.OptionsT) => DSLeftNavBridgeT.ResultT;

package/dist/types/exported-related/conversion-utils/lostCodes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Single source of truth for the codes of what the conversion cannot carry over: the type, the empty report and the warnings derive from it.
+ */
+export declare const WARNING_PER_LOST_CODE: {
+    readonly 'submenu-without-children': "- Encountered submenu items without an entry in \"childrenByParentId\" - the tree needs the children in the data, the conversion created an empty parent";
+    readonly 'custom-component-dropped': "- Encountered items with a custom \"Component\" - a treeitem cannot hold arbitrary interactive content (WCAG 4.1.2), the conversion dropped them";
+    readonly 'skeleton-dropped': "- Encountered skeleton items - loading states are not part of the tree, the conversion dropped them";
+    readonly 'header-item-dropped': "- Encountered an item of type header inside \"items\" - the tree has one header disclosure, passed as \"HeaderComponent\", the conversion dropped it from the list";
+    readonly 'header-content-dropped': "- Encountered \"headerAsFirstLeaf\" together with a list for the header in \"childrenByParentId\" - a header that is the first item of the list has nothing to open, the conversion ignored that list. Drop \"headerAsFirstLeaf\" to keep the header as a disclosure with its content";
+    readonly 'header-without-content': "- Encountered a \"HeaderComponent\" without an entry in \"childrenByParentId\" - the tree header is a disclosure with nothing to open. If the header is only a link, pass \"headerAsFirstLeaf\" to make it the first item of the list";
+    readonly 'right-component-ctx': "- Encountered \"RightComponent\" on a leaf, drilldown or header, or a \"labelRightSection\" that is not text - the conversion kept it, but the tree only gives it \"{ item }\" and an empty \"ctx\", so it must not read \"ctx\". The \"item\" it receives is the converted tree item (another type, with only the options the tree keeps), so it must not read legacy fields either. The conversion does not inspect what it draws: remove buttons, menus or any other control inside it before rendering the converted data, a treeitem cannot hold them";
+    readonly 'body-header-dropped': "- Encountered \"BodyHeaderComponent\" - the tree shows the opened submenu as the parent of its children, the conversion ignored it";
+    readonly 'component-with-ctx-dropped': "- Encountered \"LeftComponent\" or \"BottomComponent\", or a \"RightComponent\" on a submenu or section - the tree has no place for them (parents draw their own arrow), the conversion dropped them";
+    readonly 'collapsed-component-ctx': "- Encountered \"CollapsedComponent\" - the conversion kept it as is, but the tree only gives it \"{ item }\" with the converted tree item (another type, with only the options the tree keeps), so it must not read \"ctx\" or legacy fields of the item";
+    readonly 'label-style-dropped': "- Encountered \"labelBold\" or \"labelColor\" - state conveyed only by weight or color fails WCAG 1.3.1 and 1.4.1, the conversion dropped them";
+    readonly 'label-truncate-to-wrap': "- Encountered \"labelOverflow: truncate\" - truncated labels need a hover tooltip (1.4.13) and hide text from users who zoom (1.4.10), the conversion uses \"wrap\"";
+    readonly 'aria-overrides-dropped': "- Encountered \"ariaLabel\", \"ariaRole\", \"ariaLive\", \"ariaExpanded\" or \"ariaDescribedBy\" - the tree computes its own names and states, the conversion dropped them";
+    readonly 'item-options-dropped': "- Encountered item options the tree does not have (selectable on a drilldown, focuseable, openable, closable, indent, skeletonVariant, labelDataTestId, any other key of itemOpts, or a non-text labelRightSection where it cannot be shown) - the conversion dropped them, see lostEntries for the list per item";
+    readonly 'section-in-nested-list-dropped': "- Encountered a section or separator inside a submenu or drilldown - the tree supports them only at the root level, the conversion dropped them";
+    readonly 'missing-id': "- Encountered items without a \"dsId\" - the tree finds every item by its \"dsId\", so each one needs its own; set it before using the converted items";
+    readonly 'duplicate-id': "- Encountered the same \"dsId\" on more than one item of the converted hierarchy - the tree finds items by \"dsId\" across all levels, so a repeated one overwrites the other's label and parent; give each item a unique \"dsId\" (LeftNavigation only needed it unique inside the list that is shown)";
+    readonly 'unknown-type-dropped': "- Encountered items with a type that is not out of the box, or a \"HeaderComponent\" that is not a header, link, text-label or with-date - the conversion dropped them";
+};

package/dist/types/exported-related/conversion-utils/report.d.ts

@@ -0,0 +1,3 @@
+import type { DSLeftNavBridgeT } from './types.js';
+export declare const createEmptyReport: () => DSLeftNavBridgeT.ReportMutableT;
+export declare const markLost: (report: DSLeftNavBridgeT.ReportMutableT, entry: DSLeftNavBridgeT.LostEntryT) => void;

package/dist/types/exported-related/conversion-utils/types.d.ts

@@ -0,0 +1,37 @@
+import type { DSLeftNavigationTreeT } from '@elliemae/ds-left-navigation-tree';
+import type { WARNING_PER_LOST_CODE } from './lostCodes.js';
+import type { DSLeftNavigationT } from '../../react-desc-prop-types.js';
+export declare namespace DSLeftNavBridgeT {
+    /**
+     * Each code is something LeftNavigation could do that the tree cannot carry over.
+     */
+    type LostCodeT = keyof typeof WARNING_PER_LOST_CODE;
+    type LostEntryT = {
+        code: LostCodeT;
+        dsId: string;
+        message: string;
+    };
+    type ReportMutableT = {
+        detectedLostsOnConversion: Record<LostCodeT, boolean>;
+        lostEntries: LostEntryT[];
+        humanReadableWarnings: string[];
+    };
+    /**
+     * LeftNavigation keeps the hierarchy outside of the data: a submenu has no children in its item, the consumer swaps `items` when the submenu is opened.
+     * This map gives the bridge the lists the consumer swaps in, keyed by the submenu dsId.
+     */
+    type ChildrenByParentIdT = Record<string, readonly DSLeftNavigationT.GenericItemItemProps[]>;
+    type OptionsT = {
+        childrenByParentId?: ChildrenByParentIdT;
+        HeaderComponent?: DSLeftNavigationT.GenericItemItemProps;
+        BodyHeaderComponent?: DSLeftNavigationT.GenericItemItemProps;
+        /** The header is only a link, with nothing to open: it becomes the first item of the list instead of a disclosure. */
+        headerAsFirstLeaf?: boolean;
+    };
+    type ResultT = {
+        convertedItems: DSLeftNavigationTreeT.Item[];
+        convertedHeader?: DSLeftNavigationTreeT.Item;
+        convertedHeaderItems?: DSLeftNavigationTreeT.Item[];
+        report: ReportMutableT;
+    };
+}

package/dist/types/exported-related/conversion-utils/validateIds.d.ts

@@ -0,0 +1,9 @@
+import type { DSLeftNavigationTreeT } from '@elliemae/ds-left-navigation-tree';
+import type { DSLeftNavBridgeT } from './types.js';
+type NewItemT = DSLeftNavigationTreeT.Item;
+/**
+ * The tree finds items by `dsId` across every level of the list it receives, LeftNavigation only needed them unique inside each list it showed.
+ * Reports the items without one and the ids that repeat, once per repeated id.
+ */
+export declare const reportIdProblems: (items: readonly NewItemT[], report: DSLeftNavBridgeT.ReportMutableT, extraIds?: readonly string[]) => void;
+export {};

package/dist/types/index.d.ts

@@ -1,6 +1,8 @@
 import { LeftNavigation } from './LeftNavigation.js';
 export default LeftNavigation;
 export { CHEVRON_BACK_DS_ID, DSLeftNavigationName, DSLeftNavigationSlots, FOOTER_DS_ID, FOOTER_MENU_CLOSE_DS_ID, ITEM_TYPES, LABEL_OVERFLOW, LEFT_NAVIGATION_DATA_TESTID, LEFT_NAVIGATION_REGION_FOCUSES, LEFT_NAVIGATION_SLOTS, MAP_ITEMS_TO_SKELETON, } from './constants/index.js';
+export { checkAndConvertItems } from './exported-related/conversion-utils/index.js';
+export type { DSLeftNavBridgeT } from './exported-related/conversion-utils/types.js';
 export { ChevronItem, Icon, ItemRenderer, Notifications, OpenWindow } from './exported-related/index.js';
 export { LeftNavigation, LeftNavigationWithSchema } from './LeftNavigation.js';
 export { DSLeftNavigationItemPropTypesSchema, DSLeftNavigationPropTypesSchema, LeftNavItemOptionsSchema, LeftNavItemPropsSchema, type DSLeftNavigationT, } from './react-desc-prop-types.js';

package/dist/types/react-desc-prop-types.d.ts

@@ -21,6 +21,7 @@ export declare namespace DSLeftNavigationT {
         dsLeftnavigationFooterMenuCollapse: () => object;
         dsLeftnavigationFooterSeparator: () => object;
         dsLeftnavigationHeaderArea: () => object;
+        dsLeftnavigationIcon: () => object;
         dsLeftnavigationItem: () => object;
         dsLeftnavigationItemBorderBottom: () => object;
         dsLeftnavigationItemChevronBack: () => object;
@@ -32,11 +33,14 @@ export declare namespace DSLeftNavigationT {
         dsLeftnavigationMessagesIcon: () => object;
         dsLeftnavigationNotificationsContainer: () => object;
         dsLeftnavigationNotificationsIcon: () => object;
+        dsLeftnavigationOpenWindowIcon: () => object;
         dsLeftnavigationRightContainer: () => object;
         dsLeftnavigationRoot: () => object;
         dsLeftnavigationSectionContainer: () => object;
         dsLeftnavigationSectionLabel: () => object;
         dsLeftnavigationSectionRightLabel: () => object;
+        dsLeftnavigationTruncatedLabel: () => object;
+        dsLeftnavigationTruncatedLabelTooltip: () => object;
         dsLeftnavigationVerticalSeparator: () => object;
     };
     type LabelOveflowT = 'wrap' | 'wrapAll' | 'truncate';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-left-navigation",
-  "version": "3.80.0-next.6",
+  "version": "3.80.0-next.60",
   "license": "MIT",
   "description": "ICE MT - Dimsum - Left Navigation",
   "files": [
@@ -36,20 +36,23 @@
     "typeSafety": false
   },
   "dependencies": {
-    "@elliemae/ds-floating-context": "3.80.0-next.6",
-    "@elliemae/ds-circular-progress-indicator": "3.80.0-next.6",
-    "@elliemae/ds-button-v2": "3.80.0-next.6",
-    "@elliemae/ds-grid": "3.80.0-next.6",
-    "@elliemae/ds-icons": "3.80.0-next.6",
-    "@elliemae/ds-props-helpers": "3.80.0-next.6",
-    "@elliemae/ds-system": "3.80.0-next.6",
-    "@elliemae/ds-skeleton": "3.80.0-next.6"
+    "@elliemae/ds-button-v2": "3.80.0-next.60",
+    "@elliemae/ds-circular-progress-indicator": "3.80.0-next.60",
+    "@elliemae/ds-floating-context": "3.80.0-next.60",
+    "@elliemae/ds-grid": "3.80.0-next.60",
+    "@elliemae/ds-icons": "3.80.0-next.60",
+    "@elliemae/ds-left-navigation-tree": "3.80.0-next.60",
+    "@elliemae/ds-props-helpers": "3.80.0-next.60",
+    "@elliemae/ds-skeleton": "3.80.0-next.60",
+    "@elliemae/ds-system": "3.80.0-next.60"
   },
   "devDependencies": {
+    "@elliemae/ds-monorepo-devops": "3.80.0-next.60",
+    "@elliemae/ds-test-utils": "3.80.0-next.60",
+    "@elliemae/ds-typescript-helpers": "3.80.0-next.60",
+    "@playwright/experimental-ct-react": "1.61.1",
     "jest": "^30.0.0",
-    "styled-components": "~5.3.11",
-    "@elliemae/ds-monorepo-devops": "3.80.0-next.6",
-    "@elliemae/ds-test-utils": "3.80.0-next.6"
+    "styled-components": "~5.3.11"
   },
   "peerDependencies": {
     "lodash-es": "^4.18.1",
@@ -58,7 +61,7 @@
     "styled-components": "~5.3.11"
   },
   "scripts": {
-    "test": "ds-monorepo-devops test --passWithNoTests --coverage=\"false\"",
+    "test": "playwright test -c ./playwright.config.mjs && ds-monorepo-devops test --passWithNoTests --coverage=\"false\"",
     "lint": "node ../../../scripts/lint.mjs --fix",
     "lint:strict": "node ../../../scripts/lint-strict.mjs",
     "dts": "node ../../../scripts/dts.mjs",