Merge pull request #3008 from jd239/feat/v3-datatable-loading-overlay

[(V3 cherry-pick): ic-data-table]: Added overlay for datatable circular loading indicator
mi6 · Jan 13, 2025 · f9ca113 · f9ca113
2 parents 35e6c24 + 10179dc
commit f9ca113
Show file tree

Hide file tree

Showing 13 changed files with 541 additions and 69 deletions.
diff --git a/packages/canary-docs/docs.json b/packages/canary-docs/docs.json
@@ -705,10 +705,10 @@
         },
         {
           "name": "loadingOptions",
-          "type": "{ description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; }",
+          "type": "{ description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; overlay?: boolean; }",
           "complexType": {
-            "original": "{\n    description?: string;\n    label?: string;\n    labelDuration?: number;\n    max?: number;\n    min?: number;\n    progress?: number;\n    showBackground?: boolean;\n    monochrome?: boolean;\n  }",
-            "resolved": "{ description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; }",
+            "original": "{\n    description?: string;\n    label?: string;\n    labelDuration?: number;\n    max?: number;\n    min?: number;\n    progress?: number;\n    showBackground?: boolean;\n    monochrome?: boolean;\n    overlay?: boolean;\n  }",
+            "resolved": "{ description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; overlay?: boolean; }",
             "references": {}
           },
           "mutable": false,
@@ -717,7 +717,7 @@
           "docsTags": [],
           "values": [
             {
-              "type": "{ description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; }"
+              "type": "{ description?: string; label?: string; labelDuration?: number; max?: number; min?: number; progress?: number; showBackground?: boolean; monochrome?: boolean; overlay?: boolean; }"
             }
           ],
           "optional": true,

diff --git a/packages/canary-react/src/component-tests/IcDataTable/IcDataTable.cy.tsx b/packages/canary-react/src/component-tests/IcDataTable/IcDataTable.cy.tsx
@@ -1177,6 +1177,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
@@ -975,6 +975,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`.
 
@@ -2207,6 +2209,7 @@ export const defaultArgs = {
   loadingMax: 100,
   loadingMin: 0,
   loadingProgress: 50, 
+  loadingOverlay: false,
   loadingShowBackground: false,
   minimumLoadingDisplayDuration: 1000,
   paginationItemsPerPageOptions: [
@@ -2318,7 +2321,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
@@ -119,6 +119,7 @@ export namespace Components {
     progress?: number;
     showBackground?: boolean;
     monochrome?: boolean;
+    overlay?: boolean;
   };
         /**
           * Sets the maximum width of the data table. Can be set in `px`, `rem`, or `%`.
@@ -838,6 +839,7 @@ declare namespace LocalJSX {
     progress?: number;
     showBackground?: boolean;
     monochrome?: 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
@@ -338,6 +338,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 {
@@ -424,6 +425,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-data-table-loading-indicator-overlay-background);
+  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
@@ -816,6 +816,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`.