Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Gdgt 2472 loader (#80586)

Jakub Chodorowiczc433278e066d
diff --git a/.loki/reference/chrome_laptop_Components_Feedback_Loader_Default.png b/.loki/reference/chrome_laptop_Components_Feedback_Loader_Default.png
new file mode 100644
index 00000000000..e04e7108f11
Binary files /dev/null and b/.loki/reference/chrome_laptop_Components_Feedback_Loader_Default.png differ
diff --git a/.loki/reference/chrome_laptop_Components_Feedback_Loader_Overview.png b/.loki/reference/chrome_laptop_Components_Feedback_Loader_Overview.png
new file mode 100644
index 00000000000..a7ec7a69f25
Binary files /dev/null and b/.loki/reference/chrome_laptop_Components_Feedback_Loader_Overview.png differ
diff --git a/.storybook/main.ts b/.storybook/main.ts
index f3c6cc3037e..751a1821c38 100644
--- a/.storybook/main.ts
+++ b/.storybook/main.ts
@@ -1,14 +1,16 @@
import path from "path";
import type { StorybookConfig } from "@storybook/react-webpack5";
-const appConfig = require("../rspack.main.config.js");
-const webpack = require("webpack");
+import remarkGfm from "remark-gfm";
+
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
+const webpack = require("webpack");
const { CSS_CONFIG } = require("../frontend/build/shared/rspack/css-config");
const {
SIDE_EFFECT_FREE_RULE,
} = require("../frontend/build/shared/rspack/side-effect-free-modules");
+const appConfig = require("../rspack.main.config.js");
const mainAppStories = [
"../frontend/**/*.mdx",
@@ -35,7 +37,22 @@ const config: StorybookConfig = {
],
addons: [
"@storybook/addon-webpack5-compiler-babel",
- "@storybook/addon-essentials",
+ {
+ name: "@storybook/addon-essentials",
+ options: {
+ docs: false,
+ },
+ },
+ {
+ name: "@storybook/addon-docs",
+ options: {
+ mdxPluginOptions: {
+ mdxCompileOptions: {
+ remarkPlugins: [remarkGfm],
+ },
+ },
+ },
+ },
"@storybook/addon-interactions",
"@storybook/addon-links",
"@storybook/addon-a11y",
diff --git a/bun.lock b/bun.lock
index 6a604c4209a..53f6ab81e14 100644
--- a/bun.lock
+++ b/bun.lock
@@ -195,6 +195,7 @@
"@stardazed/streams-text-encoding": "^1.0.2",
"@storybook/addon-a11y": "^8.5.0",
"@storybook/addon-actions": "^8.5.0",
+ "@storybook/addon-docs": "^8.5.0",
"@storybook/addon-essentials": "^8.5.0",
"@storybook/addon-interactions": "^8.5.0",
"@storybook/addon-links": "^8.5.0",
diff --git a/frontend/src/metabase/ui/components/feedback/Loader/Loader.config.ts b/frontend/src/metabase/ui/components/feedback/Loader/Loader.config.ts
new file mode 100644
index 00000000000..acb6d061e71
--- /dev/null
+++ b/frontend/src/metabase/ui/components/feedback/Loader/Loader.config.ts
@@ -0,0 +1,42 @@
+import { Loader, type MantineThemeOverride, getSize, rem } from "@mantine/core";
+
+import S from "./Loader.module.css";
+
+export const LOADER_SIZES = {
+ xs: 12,
+ sm: 14,
+ md: 16,
+ lg: 18,
+ xl: 22,
+} as const;
+
+export type LoaderNamedSize = keyof typeof LOADER_SIZES;
+
+/** Labels only use two text sizes, so they stay consistent across loader sizes. */
+export const LOADER_LABEL_SIZES = {
+ xs: "sm",
+ sm: "sm",
+ md: "md",
+ lg: "md",
+ xl: "md",
+} as const satisfies Record<LoaderNamedSize, "sm" | "md">;
+
+export function isLoaderNamedSize(size: unknown): size is LoaderNamedSize {
+ return typeof size === "string" && size in LOADER_SIZES;
+}
+
+export const loaderOverrides: MantineThemeOverride["components"] = {
+ Loader: Loader.extend({
+ classNames: {
+ root: S.root,
+ },
+ vars: (_theme, { size = "md", color }) => ({
+ root: {
+ "--loader-size": isLoaderNamedSize(size)
+ ? rem(LOADER_SIZES[size])
+ : getSize(size, "loader-size"),
+ "--loader-color": color ? undefined : "var(--mb-color-icon-brand)",
+ },
+ }),
+ }),
+};
diff --git a/frontend/src/metabase/ui/components/feedback/Loader/Loader.mdx b/frontend/src/metabase/ui/components/feedback/Loader/Loader.mdx
index e5dbc48ca7c..46d43710605 100644
--- a/frontend/src/metabase/ui/components/feedback/Loader/Loader.mdx
+++ b/frontend/src/metabase/ui/components/feedback/Loader/Loader.mdx
@@ -1,29 +1,37 @@
-import { Fragment } from "react";
-import { Canvas, Story, Meta } from "@storybook/blocks";
-import { Grid, Text } from "metabase/ui";
-import { Loader } from "./";
+import { Canvas, Meta } from "@storybook/blocks";
import * as LoaderStories from "./Loader.stories";
<Meta of={LoaderStories} />
# Loader
-Our themed wrapper around [Mantine Loader](https://v6.mantine.dev/core/loader/).
+Our themed wrapper around [Mantine Loader](https://mantine.dev/core/loader/).
## Docs
-- [Figma File](https://www.figma.com/file/NUXRUa9Ot3HvgC1WwIA4UH/Loader?type=design&node-id=1-96&mode=design&t=yaNljw178EFJeU7k-0)
-- [Mantine Loader Docs](https://v6.mantine.dev/core/loader/)
+- [Figma File](https://www.figma.com/design/qYbAmJHUJ2Tkb01WFegUKp/Component-Library?node-id=278-16192)
+- [Mantine Loader Docs](https://mantine.dev/core/loader/)
+
+## Sizes
+
+| `size` | Diameter | Ring width | Label text |
+| ------ | -------- | ---------- | ---------- |
+| `xs` | 12px | 1.5px | `sm` |
+| `sm` | 14px | 1.75px | `sm` |
+| `md` | 16px | 2px | `md` |
+| `lg` | 18px | 2px | `md` |
+| `xl` | 22px | 2.5px | `md` |
+
+`md` is the default. Raw numbers and CSS lengths still work as an escape hatch, and fall back to the `md` label text size.
## Caveats
-- Only use the `oval` variant unless otherwise called out
-- Prefer usage of loader sizes less than `xl` unless specifically called out
+`oval` (the default) is the only type Figma specs, and `dots` is the sole alternative the design system offers. Mantine's `bars` is not part of the API.
## Examples
<Canvas of={LoaderStories.Default} />
-### Sizes
+### Overview
-<Canvas of={LoaderStories.Sizes} />
+<Canvas of={LoaderStories.Overview} />
diff --git a/frontend/src/metabase/ui/components/feedback/Loader/Loader.module.css b/frontend/src/metabase/ui/components/feedback/Loader/Loader.module.css
new file mode 100644
index 00000000000..a61cdb75684
--- /dev/null
+++ b/frontend/src/metabase/ui/components/feedback/Loader/Loader.module.css
@@ -0,0 +1,9 @@
+/* overrides to match Figma designs */
+
+.root[data-size="lg"]::after {
+ border-width: 2px;
+}
+
+.root[data-size="xl"]::after {
+ border-width: 2.5px;
+}
diff --git a/frontend/src/metabase/ui/components/feedback/Loader/Loader.stories.tsx b/frontend/src/metabase/ui/components/feedback/Loader/Loader.stories.tsx
index 6fdcdb9afdf..4115a5e6268 100644
--- a/frontend/src/metabase/ui/components/feedback/Loader/Loader.stories.tsx
+++ b/frontend/src/metabase/ui/components/feedback/Loader/Loader.stories.tsx
@@ -1,8 +1,16 @@
import { Fragment } from "react";
-import { Grid, Text } from "metabase/ui";
+import { Box, Loader, type LoaderProps } from "metabase/ui";
+import {
+ StoryJsx,
+ StorySection,
+ StoryShowcase,
+} from "metabase/ui/stories/showcase";
+import { getObjectKeys } from "metabase/utils/objects";
-import { Loader } from "./";
+import { LOADER_SIZES } from "./Loader.config";
+
+const SIZES = getObjectKeys(LOADER_SIZES);
const args = {
size: "md",
@@ -10,26 +18,11 @@ const args = {
const argTypes = {
size: {
- options: ["xs", "sm", "md", "lg", "xl"],
+ options: SIZES,
control: { type: "inline-radio" },
},
};
-const SizeTemplate = () => (
- <Grid w="10rem" columns={2} align="center">
- {argTypes.size.options.map((size) => (
- <Fragment key={size}>
- <Grid.Col span={1}>
- <Text fw="bold">{size}</Text>
- </Grid.Col>
- <Grid.Col span={1}>
- <Loader size={size} />
- </Grid.Col>
- </Fragment>
- ))}
- </Grid>
-);
-
export default {
title: "Components/Feedback/Loader",
component: Loader,
@@ -37,8 +30,80 @@ export default {
argTypes,
};
-export const Default = {};
+export const Default = {
+ render: (args: LoaderProps) => <Loader {...args} />,
+};
+
+const grid2Columns = {
+ display: "grid",
+ gridTemplateColumns: "1fr 1fr",
+ columnGap: "2rem",
+ rowGap: "1rem",
+ alignItems: "center",
+ justifyItems: "start",
+ padding: "1rem 0",
+} as const;
+
+const grid3Columns = {
+ ...grid2Columns,
+ gridTemplateColumns: "1fr 1fr 1fr",
+} as const;
-export const Sizes = {
- render: SizeTemplate,
+const OverviewTemplate = () => (
+ <StoryShowcase title="Loader">
+ <StorySection title="Sizes" description="The default size is “md”.">
+ <Box style={grid3Columns}>
+ {SIZES.map((size) => (
+ <Fragment key={size}>
+ <StoryJsx>{`<Loader size="${size}" />`}</StoryJsx>
+ <StoryJsx>{`${LOADER_SIZES[size]}px`}</StoryJsx>
+ <Loader size={size} />
+ </Fragment>
+ ))}
+ </Box>
+ </StorySection>
+
+ <StorySection title="Types">
+ <Box style={grid2Columns}>
+ <StoryJsx>{`<Loader type="oval" />`}</StoryJsx>
+ <Loader type="oval" />
+ <StoryJsx>{`<Loader type="dots" />`}</StoryJsx>
+ <Loader type="dots" />
+ </Box>
+ </StorySection>
+
+ <StorySection
+ title="Color"
+ description="Defaults to the icon-brand token. An explicit color prop overrides it."
+ >
+ <Box style={grid2Columns}>
+ <StoryJsx>{`<Loader />`}</StoryJsx>
+ <Loader />
+ <StoryJsx>{`<Loader color="text-secondary" />`}</StoryJsx>
+ <Loader color="text-secondary" />
+ </Box>
+ </StorySection>
+
+ <StorySection
+ title="Label"
+ description="Renders the loader stacked above a caption. The caption uses “sm” text for the xs and sm loaders, and “md” text for the rest."
+ >
+ <Box style={grid2Columns}>
+ {SIZES.map((size) => (
+ <Fragment key={size}>
+ <StoryJsx>{`<Loader size="${size}" label="Loading…" />`}</StoryJsx>
+ <Loader size={size} label="Loading…" />
+ </Fragment>
+ ))}
+ </Box>
+ </StorySection>
+ </StoryShowcase>
+);
+
+export const Overview = {
+ render: OverviewTemplate,
+ args: { theme: "light" },
+ parameters: {
+ controls: { include: ["theme"] },
+ },
};
diff --git a/frontend/src/metabase/ui/components/feedback/Loader/Loader.tsx b/frontend/src/metabase/ui/components/feedback/Loader/Loader.tsx
index cd4dc2ec086..f4b2eb05024 100644
--- a/frontend/src/metabase/ui/components/feedback/Loader/Loader.tsx
+++ b/frontend/src/metabase/ui/components/feedback/Loader/Loader.tsx
@@ -1,16 +1,11 @@
import type { LoaderProps as MantineLoaderProps } from "@mantine/core";
-import { Loader as MantineLoader, Stack, Text, getSize } from "@mantine/core";
+import { Loader as MantineLoader, Stack, Text } from "@mantine/core";
import type React from "react";
-const SIZES: Record<string, string> = {
- xs: "1rem",
- sm: "1.25rem",
- md: "1.5rem",
- lg: "2rem",
- xl: "3.5rem",
-};
+import { LOADER_LABEL_SIZES, isLoaderNamedSize } from "./Loader.config";
-interface LoaderProps extends MantineLoaderProps {
+export interface LoaderProps extends Omit<MantineLoaderProps, "type"> {
+ type?: "oval" | "dots";
label?: string;
"data-testid"?: string;
}
@@ -33,22 +28,16 @@ export const Loader = ({
return <CustomLoader label={label} />;
}
+ const labelSize = isLoaderNamedSize(size) ? LOADER_LABEL_SIZES[size] : "md";
+
return label ? (
<Stack justify="center" align="center" gap="sm" mt="xl">
- <MantineLoader
- {...props}
- data-testid={dataTestId}
- size={getSize(SIZES[size] ?? size)}
- />
- <Text c="text-disabled" size="xl">
+ <MantineLoader {...props} data-testid={dataTestId} size={size} />
+ <Text c="text-disabled" size={labelSize}>
{label}
</Text>
</Stack>
) : (
- <MantineLoader
- {...props}
- data-testid={dataTestId}
- size={getSize(SIZES[size] ?? size)}
- />
+ <MantineLoader {...props} data-testid={dataTestId} size={size} />
);
};
diff --git a/frontend/src/metabase/ui/components/feedback/Loader/Loader.unit.spec.tsx b/frontend/src/metabase/ui/components/feedback/Loader/Loader.unit.spec.tsx
index f970ba892e2..ec0162f92ab 100644
--- a/frontend/src/metabase/ui/components/feedback/Loader/Loader.unit.spec.tsx
+++ b/frontend/src/metabase/ui/components/feedback/Loader/Loader.unit.spec.tsx
@@ -1,54 +1,188 @@
import { MantineProvider } from "@mantine/core";
import { render, screen } from "@testing-library/react";
-import { Loader, setCustomLoader } from "./Loader";
+import { Loader, type LoaderProps, setCustomLoader } from "./Loader";
+import { loaderOverrides } from "./Loader.config";
-const renderWithProvider = (component: React.ReactElement) => {
- return render(<MantineProvider>{component}</MantineProvider>);
+type SetupOpts = LoaderProps & {
+ withTheme?: boolean;
};
+function setup({ withTheme = false, ...props }: SetupOpts = {}) {
+ const theme = withTheme ? { components: loaderOverrides } : undefined;
+
+ function wrap(loaderProps: LoaderProps) {
+ return (
+ <MantineProvider theme={theme}>
+ <Loader {...loaderProps} />
+ </MantineProvider>
+ );
+ }
+
+ const { rerender } = render(wrap(props));
+
+ function rerenderLoader(nextProps: LoaderProps = props) {
+ return rerender(wrap(nextProps));
+ }
+
+ return { rerender: rerenderLoader };
+}
+
+function getLoader() {
+ return screen.getByTestId("loading-indicator");
+}
+
+function getLoaderVar(name: string) {
+ return getLoader().style.getPropertyValue(name);
+}
+
+function CustomLoader() {
+ return <div data-testid="custom-loader">Custom Loader</div>;
+}
+
describe("Loader", () => {
beforeEach(() => {
setCustomLoader(undefined);
});
it("renders default Mantine Loader when no custom loader is set", () => {
- renderWithProvider(<Loader data-testid="loader" />);
+ setup();
- const loader = screen.getByTestId("loader");
- expect(loader).toBeInTheDocument();
- expect(loader).toHaveClass("mantine-Loader-root");
+ expect(getLoader()).toBeInTheDocument();
+ expect(getLoader()).toHaveClass("mantine-Loader-root");
});
it("renders custom loader when one is set", () => {
- const CustomLoader = () => (
- <div data-testid="custom-loader">Custom Loader</div>
- );
-
setCustomLoader(CustomLoader);
- renderWithProvider(<Loader />);
+ setup();
expect(screen.getByTestId("custom-loader")).toBeInTheDocument();
- expect(screen.queryByTestId("loader")).not.toBeInTheDocument();
+ expect(screen.queryByTestId("loading-indicator")).not.toBeInTheDocument();
});
it("switches back to default loader when custom loader is cleared", () => {
- const CustomLoader = () => (
- <div data-testid="custom-loader">Custom Loader</div>
- );
-
setCustomLoader(CustomLoader);
- const { rerender } = renderWithProvider(<Loader data-testid="loader" />);
+ const { rerender } = setup();
expect(screen.getByTestId("custom-loader")).toBeInTheDocument();
setCustomLoader(undefined);
- rerender(
- <MantineProvider>
- <Loader data-testid="loader" />
- </MantineProvider>,
- );
+ rerender();
expect(screen.queryByTestId("custom-loader")).not.toBeInTheDocument();
- expect(screen.getByTestId("loader")).toBeInTheDocument();
+ expect(getLoader()).toBeInTheDocument();
+ });
+
+ describe("testid", () => {
+ it("defaults to loading-indicator", () => {
+ setup();
+
+ expect(getLoader()).toBeInTheDocument();
+ });
+
+ it("can be overridden", () => {
+ setup({ "data-testid": "custom-testid" });
+
+ expect(screen.getByTestId("custom-testid")).toBeInTheDocument();
+ expect(screen.queryByTestId("loading-indicator")).not.toBeInTheDocument();
+ });
+ });
+
+ describe("size", () => {
+ it.each([
+ ["xs", "0.75rem"],
+ ["sm", "0.875rem"],
+ ["md", "1rem"],
+ ["lg", "1.125rem"],
+ ["xl", "1.375rem"],
+ ] as const)("resolves %s to %s", (size, expected) => {
+ setup({ withTheme: true, size });
+
+ expect(getLoaderVar("--loader-size")).toBe(
+ `calc(${expected} * var(--mantine-scale))`,
+ );
+ });
+
+ it("defaults to md", () => {
+ setup({ withTheme: true });
+
+ expect(getLoaderVar("--loader-size")).toBe(
+ "calc(1rem * var(--mantine-scale))",
+ );
+ });
+
+ it("passes unnamed sizes through to Mantine", () => {
+ setup({ withTheme: true, size: 48 });
+
+ expect(getLoaderVar("--loader-size")).toBe(
+ "calc(3rem * var(--mantine-scale))",
+ );
+ });
+
+ it("sets data-size for named sizes, so the ring override can match", () => {
+ setup({ withTheme: true, size: "lg" });
+
+ expect(getLoader()).toHaveAttribute("data-size", "lg");
+ });
+
+ it("sets no data-size for numeric sizes", () => {
+ setup({ withTheme: true, size: 48 });
+
+ expect(getLoader()).not.toHaveAttribute("data-size");
+ });
+ });
+
+ describe("color", () => {
+ it("defaults to the icon-brand token", () => {
+ setup({ withTheme: true });
+
+ expect(getLoaderVar("--loader-color")).toBe("var(--mb-color-icon-brand)");
+ });
+
+ it("is overridden by an explicit color prop", () => {
+ setup({ withTheme: true, color: "text-secondary" });
+
+ expect(getLoaderVar("--loader-color")).toBe("text-secondary");
+ });
+ });
+
+ describe("label", () => {
+ function getLabelFontSize(label: string) {
+ return screen.getByText(label).style.getPropertyValue("--text-fz");
+ }
+
+ it("renders the label alongside the loader", () => {
+ setup({ label: "Loading…" });
+
+ expect(screen.getByText("Loading…")).toBeInTheDocument();
+ expect(getLoader()).toBeInTheDocument();
+ });
+
+ it.each([
+ ["xs", "sm"],
+ ["sm", "sm"],
+ ["md", "md"],
+ ["lg", "md"],
+ ["xl", "md"],
+ ] as const)(
+ "sizes the label of a %s loader with the %s token",
+ (size, expected) => {
+ setup({ label: "Loading…", size });
+
+ expect(getLabelFontSize("Loading…")).toBe(
+ `var(--mantine-font-size-${expected})`,
+ );
+ },
+ );
+
+ it.each([48, "3rem"])(
+ "falls back to the md label size for unnamed loader size %p",
+ (size) => {
+ setup({ label: "Loading…", size });
+
+ expect(getLabelFontSize("Loading…")).toBe(
+ "var(--mantine-font-size-md)",
+ );
+ },
+ );
});
});
diff --git a/frontend/src/metabase/ui/components/feedback/Loader/index.ts b/frontend/src/metabase/ui/components/feedback/Loader/index.ts
index b2165a8664c..83a82f58456 100644
--- a/frontend/src/metabase/ui/components/feedback/Loader/index.ts
+++ b/frontend/src/metabase/ui/components/feedback/Loader/index.ts
@@ -1,2 +1,3 @@
export { Loader, setCustomLoader } from "./Loader";
-export type { LoaderProps } from "@mantine/core";
+export type { LoaderProps } from "./Loader";
+export { loaderOverrides } from "./Loader.config";
diff --git a/frontend/src/metabase/ui/theme.ts b/frontend/src/metabase/ui/theme.ts
index 221d0ea7f58..9fa3a2f70f3 100644
--- a/frontend/src/metabase/ui/theme.ts
+++ b/frontend/src/metabase/ui/theme.ts
@@ -30,6 +30,7 @@ import {
inputOverrides,
kbdOverrides,
listOverrides,
+ loaderOverrides,
menuOverrides,
modalOverrides,
monthPickerOverrides,
@@ -174,6 +175,7 @@ export const getThemeOverrides = (
...fileInputOverrides,
...inputOverrides,
...kbdOverrides,
+ ...loaderOverrides,
...menuOverrides,
...modalOverrides,
...monthPickerOverrides,
diff --git a/loki.config.js b/loki.config.js
index b9103d2553c..8ee384ef79a 100644
--- a/loki.config.js
+++ b/loki.config.js
@@ -16,6 +16,7 @@ module.exports = {
"^Components/overlays/Tooltip",
"^Components/Documents",
"^Components/Feedback/Alert",
+ "^Components/Feedback/Loader Overview",
"^Components/Ask Before Using/Chip Overview",
"^Components/Data display/Badge Sizes and variants",
"^Components/Navigation/NavLink Overview",
diff --git a/package.json b/package.json
index f27a15d19e1..eeb6e859304 100644
--- a/package.json
+++ b/package.json
@@ -204,6 +204,7 @@
"@stardazed/streams-text-encoding": "^1.0.2",
"@storybook/addon-a11y": "^8.5.0",
"@storybook/addon-actions": "^8.5.0",
+ "@storybook/addon-docs": "^8.5.0",
"@storybook/addon-essentials": "^8.5.0",
"@storybook/addon-interactions": "^8.5.0",
"@storybook/addon-links": "^8.5.0",