Merge pull request #2979 from jd239/feat/datatable-overlay-circular-l…

…oading-indicator [ic-data-table]: Added overlay for datatable circular loading indicator
mi6 · Jan 10, 2025 · e7b41a9 · e7b41a9
2 parents 1883aea + 2efe41f
commit e7b41a9
Show file tree

Hide file tree

Showing 12 changed files with 554 additions and 324 deletions.
diff --git a/packages/canary-docs/docs.json b/packages/canary-docs/docs.json
@@ -668,10 +668,10 @@
         },
         {
           "name": "loadingOptions",
-          "type": "{ appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; }",
+          "type": "{ appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; overlay?: boolean; }",
           "complexType": {
-            "original": "{\n    appearance?: IcThemeForegroundNoDefault;\n    description?: string;\n    label?: string;\n    labelDuration?: number;\n    max?: number;\n    min?: number;\n    progress?: number;\n    showBackground?: boolean;\n  }",
-            "resolved": "{ appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; }",
+            "original": "{\n    appearance?: IcThemeForegroundNoDefault;\n    description?: string;\n    label?: string;\n    labelDuration?: number;\n    max?: number;\n    min?: number;\n    progress?: number;\n    showBackground?: boolean;\n    overlay?: boolean;\n  }",
+            "resolved": "{ appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; overlay?: boolean; }",
             "references": {
               "IcThemeForegroundNoDefault": {
                 "location": "import",
@@ -686,7 +686,7 @@
           "docsTags": [],
           "values": [
             {
-              "type": "{ appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; }"
+              "type": "{ appearance?: IcThemeForegroundNoDefault; description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; overlay?: boolean; }"
             }
           ],
           "optional": true,
@@ -774,7 +774,7 @@
           "reflectToAttr": false,
           "docs": "Sets the props for the built-in pagination bar. If the `pagination-bar` slot is used then this prop is ignored.",
           "docsTags": [],
-          "default": "{\n    itemsPerPageOptions: [\n      { label: \"10\", value: \"10\" },\n      { label: \"25\", value: \"25\" },\n      { label: \"50\", value: \"50\" },\n    ],\n    rangeLabelType: \"page\",\n    type: \"simple\",\n    showItemsPerPageControl: true,\n    showGoToPageControl: true,\n    alignment: \"right\",\n    appearance: \"default\",\n    itemLabel: \"Item\",\n    pageLabel: \"Page\",\n    hideRangeLabel: false,\n    hideAllFromItemsPerPage: false,\n  }",
+          "default": "{\n    itemsPerPageOptions: [\n      { label: \"10\", value: \"10\" },\n      { label: \"25\", value: \"25\" },\n      { label: \"50\", value: \"50\" },\n    ],\n    rangeLabelType: \"page\",\n    type: \"simple\",\n    showItemsPerPageControl: true,\n    showGoToPageControl: true,\n    alignment: \"right\",\n    appearance: \"default\",\n    itemLabel: \"Item\",\n    pageLabel: \"Page\",\n    hideRangeLabel: false,\n    hideAllFromItemsPerPage: false,\n    setToFirstPageOnPaginationChange: false,\n  }",
           "values": [
             {
               "type": "IcPaginationBarOptions"
@@ -5593,7 +5593,7 @@
       "path": "../web-components/dist/types/utils/types.d.ts"
     },
     "src/utils/types.ts::IcPaginationBarOptions": {
-      "declaration": "export interface IcPaginationBarOptions {\n  itemsPerPageOptions?: { label: string; value: string }[];\n  rangeLabelType?: IcPaginationLabelTypes;\n  type?: IcPaginationTypes;\n  showItemsPerPageControl?: boolean;\n  showGoToPageControl?: boolean;\n  alignment?: IcPaginationAlignmentOptions;\n  appearance?: IcThemeForeground;\n  itemLabel?: string;\n  pageLabel?: string;\n  hideRangeLabel?: boolean;\n  hideAllFromItemsPerPage?: boolean;\n}",
+      "declaration": "export interface IcPaginationBarOptions {\n  itemsPerPageOptions?: { label: string; value: string }[];\n  rangeLabelType?: IcPaginationLabelTypes;\n  type?: IcPaginationTypes;\n  showItemsPerPageControl?: boolean;\n  showGoToPageControl?: boolean;\n  alignment?: IcPaginationAlignmentOptions;\n  appearance?: IcThemeForeground;\n  itemLabel?: string;\n  pageLabel?: string;\n  hideRangeLabel?: boolean;\n  hideAllFromItemsPerPage?: boolean;\n  setToFirstPageOnPaginationChange?: boolean;\n}",
       "docstring": "",
       "path": "src/utils/types.ts"
     },

diff --git a/packages/canary-react/src/component-tests/IcDataTable/IcDataTable.cy.tsx b/packages/canary-react/src/component-tests/IcDataTable/IcDataTable.cy.tsx
@@ -1163,6 +1163,107 @@ describe("IcDataTables", () => {
       },
     });
   });
+
+  it("should render a backdrop with circular loading indicator when loadingOption.overlay is set to true", () => {
+    mount(
+      <IcDataTable
+        columns={COLS}
+        data={DATA}
+        caption="Data tables"
+        loadingOptions={{
+          overlay: true,
+        }}
+      />
+    );
+    cy.checkHydrated(DATA_TABLE_SELECTOR);
+
+    cy.get(DATA_TABLE_SELECTOR).invoke("prop", "loading", true);
+
+    cy.findShadowEl(DATA_TABLE_SELECTOR, ".loading-overlay").should(
+      "be.visible"
+    );
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "tbody").should("be.visible");
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "ic-loading-indicator")
+      .shadow()
+      .find(".ic-loading-circular-outer")
+      .should("be.visible");
+
+    cy.get(DATA_TABLE_SELECTOR).invoke("prop", "data", LONG_DATA);
+
+    cy.wait(1000);
+
+    cy.findShadowEl(DATA_TABLE_SELECTOR, ".loading-overlay").should(
+      "be.not.exist"
+    );
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "tbody").should("be.visible");
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "ic-loading-indicator").should(
+      "not.exist"
+    );
+  });
+
+  it("should not render an overlay with circular loading indicator when loadingOption.overlay is set to false", () => {
+    mount(
+      <IcDataTable
+        columns={COLS}
+        data={DATA}
+        caption="Data tables"
+        loadingOptions={{
+          overlay: false,
+        }}
+      />
+    );
+    cy.checkHydrated(DATA_TABLE_SELECTOR);
+
+    cy.get(DATA_TABLE_SELECTOR).invoke("prop", "loading", true);
+
+    cy.findShadowEl(DATA_TABLE_SELECTOR, ".loading-overlay").should(
+      "not.exist"
+    );
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "tbody").should("not.exist");
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "ic-loading-indicator")
+      .shadow()
+      .find(".ic-loading-circular-outer")
+      .should("be.visible");
+  });
+
+  it("should render an overlay with circular loading indicator when loadingOption.overlay is set to true and no data is set", () => {
+    mount(
+      <IcDataTable
+        columns={COLS}
+        data={[]}
+        caption="Data tables"
+        loadingOptions={{
+          overlay: true,
+        }}
+      />
+    );
+    cy.checkHydrated(DATA_TABLE_SELECTOR);
+
+    cy.get(DATA_TABLE_SELECTOR).invoke("prop", "loading", true);
+
+    cy.findShadowEl(DATA_TABLE_SELECTOR, ".loading-overlay").should(
+      "be.visible"
+    );
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "tbody").should("not.exist");
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "ic-empty-state").should("be.visible");
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "ic-loading-indicator")
+      .shadow()
+      .find(".ic-loading-circular-outer")
+      .should("be.visible");
+
+    cy.get(DATA_TABLE_SELECTOR).invoke("prop", "data", LONG_DATA);
+
+    cy.wait(1000);
+
+    cy.findShadowEl(DATA_TABLE_SELECTOR, ".loading-overlay").should(
+      "not.exist"
+    );
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "tbody").should("be.visible");
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "ic-empty-state").should("not.exist");
+    cy.findShadowEl(DATA_TABLE_SELECTOR, "ic-loading-indicator").should(
+      "not.exist"
+    );
+  });
 });
 
 describe("IcDataTables with IcPaginationBar", () => {

diff --git a/packages/canary-react/src/stories/ic-data-table.stories.mdx b/packages/canary-react/src/stories/ic-data-table.stories.mdx
@@ -976,6 +976,8 @@ The loading indicator can be customised using the `loadingOptions` prop:
 - `label` sets the visual message
 - `labelDuration` is the number of milliseconds before the label changes
 - `showBackground` allows for a white background and grey border to help the indicator stand out
+- `overlay` renders a dark overlay over the previous data set while new data is loaded
+  - Setting `overlay` also sets `showBackground` to `true` so the loading indicator stands out against the dark overlay.
 
 If it needs to be determinate, use `max`, `min` and `progress`.
 
@@ -2194,6 +2196,7 @@ export const defaultArgs = {
   loadingMax: 100,
   loadingMin: 0,
   loadingProgress: 50, 
+  loadingOverlay: false,
   loadingShowBackground: false,
   minimumLoadingDisplayDuration: 1000,
   paginationAlignment: "right",
@@ -2317,7 +2320,8 @@ export const defaultArgs = {
           max: args.loadingMax,
           min: args.loadingMin,
           progress: args.loadingProgress,
-          showBackground: args.loadingShowBackground
+          showBackground: args.loadingShowBackground,
+          overlay: args.loadingOverlay
         }}
         minimumLoadingDisplayDuration={args.minimumLoadingDisplayDuration}
         paginationBarOptions={{

diff --git a/packages/canary-web-components/src/components.d.ts b/packages/canary-web-components/src/components.d.ts
@@ -121,6 +121,7 @@ export namespace Components {
     min?: number;
     progress?: number;
     showBackground?: boolean;
+    overlay?: boolean;
   };
         /**
           * Sets the maximum width of the data table. Can be set in `px`, `rem`, or `%`.
@@ -1097,6 +1098,7 @@ declare namespace LocalJSX {
     min?: number;
     progress?: number;
     showBackground?: boolean;
+    overlay?: boolean;
   };
         /**
           * Sets the maximum width of the data table. Can be set in `px`, `rem`, or `%`.

diff --git a/packages/canary-web-components/src/components/ic-data-table/ic-data-table.css b/packages/canary-web-components/src/components/ic-data-table/ic-data-table.css
@@ -318,6 +318,7 @@ td.table-density-spacious {
   left: calc(50% - 5.9741rem);
   opacity: 0;
   transition: opacity var(--ic-transition-duration-slow);
+  z-index: calc(var(--ic-z-index-dialog) - 1);
 }
 
 .loading.show-background {
@@ -384,6 +385,35 @@ td.table-density-spacious {
   grid-template-columns: auto auto;
 }
 
+.loading-overlay {
+  visibility: hidden;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: var(--ic-architectural-black);
+  z-index: calc(var(--ic-z-index-dialog) - 2);
+  opacity: 0;
+  transition: opacity var(--ic-transition-duration-slow);
+}
+
+.loading-overlay.show {
+  visibility: visible;
+  opacity: 0.6;
+}
+
+.sr-only {
+  position: absolute;
+  left: -9999px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .loading-overlay {
+    transition: none;
+  }
+}
+
 @media screen and (min-width: 577px) {
   .column-header-inner-container {
     display: flex;

diff --git a/...es/canary-web-components/src/components/ic-data-table/ic-data-table.stories.mdx b/...es/canary-web-components/src/components/ic-data-table/ic-data-table.stories.mdx
@@ -785,6 +785,8 @@ The loading indicator can be customised using the `loadingOptions` prop:
 - `label` sets the visual message
 - `labelDuration` is the number of milliseconds before the label changes
 - `showBackground` allows for a white background and grey border to help the indicator stand out
+- `overlay` renders a dark overlay over the previous data set while new data is loaded
+  - Setting `overlay` also sets `showBackground` to `true` so the loading indicator stands out against the dark overlay.
 
 If it needs to be determinate, use `max`, `min` and `progress`.