Explain locked Channel rows and empty filter panels (#6883)

* Explain locked Channel rows and empty filter panels

* Replace list-page docs subtitles with TopNav help icons

Gift cards now share the Products card layout; search placeholders use sentence-case example copy

* Add changeset

* Use Macaw flex token strings so typecheck passes

Author: mirekm

.changeset/filter-hints-and-list-chrome.md

@@ -0,0 +1,7 @@
+---
+"saleor-dashboard": patch
+---
+
+Clarify list filters and search.
+
+Auto-added Channel and Currency rows now show why they are required. Empty filter panels say “No filters”. List pages put docs behind a help icon instead of a subtitle.

locale/defaultMessages.json

@@ -623,6 +623,10 @@
   "0HBlkO": {
     "string": "Search channels"
   },
+  "0HZg9/": {
+    "context": "tooltip on the add-preset button in list headers",
+    "string": "Save filters and search as preset"
+  },
   "0I+Z8l": {
     "context": "stock exceeded dialog description",
     "string": "{count, plural, one {# item exceeds available stock.} other {# items exceed available stock.}} Go back to adjust quantities, or fulfill anyway to oversell."
@@ -1592,6 +1596,10 @@
     "context": "gift card tag field label",
     "string": "Card tag"
   },
+  "4IVdnm": {
+    "context": "Empty state when the filter panel or modal has no conditions",
+    "string": "No filters"
+  },
   "4IawKc": {
     "context": "onboarding step description",
     "string": "Go to all orders where you can create an fulfilment and refund and review corresponding statuses. View the order in GraphQL"
@@ -3184,6 +3192,9 @@
     "context": "dialog content",
     "string": "{counter,plural,one{Are you sure you want to unassign this product?} other{Are you sure you want to unassign {displayQuantity} products?}}"
   },
+  "AHOQr2": {
+    "string": "Search products..."
+  },
   "AJF7N5": {
     "context": "scope note for model type tab grouping help tooltip",
     "string": "Browser-only display — does not rename, merge, or change your model types or data."
@@ -3393,10 +3404,6 @@
   "B52Em/": {
     "string": "Address line 1"
   },
-  "B5KI59": {
-    "context": "Empty filters text",
-    "string": "Add filter to start"
-  },
   "B77MSl": {
     "context": "empty state for variant attributes on a product type",
     "string": "No variant options yet"
@@ -5646,10 +5653,6 @@
     "context": "export scope option disabled when list has no active filters",
     "string": "Apply filters or search on the list to enable this option."
   },
-  "JDvxO6": {
-    "context": "search gift card placeholder",
-    "string": "Search Gift Cards (e.g. by code, email, user name)"
-  },
   "JE0TAx": {
     "context": "section name",
     "string": "Values"
@@ -6467,6 +6470,10 @@
     "context": "column title used by/customer",
     "string": "Used by"
   },
+  "MKCw7u": {
+    "context": "Tooltip on the info icon before a locked Channel or Currency filter listing the filters that require it",
+    "string": "Needed for filtering on {fields}"
+  },
   "MKTuIa": {
     "context": "voucher percentage channel input aria label",
     "string": "Percentage for {channelName}"
@@ -7528,6 +7535,10 @@
   "Q8Qw5B": {
     "string": "Description"
   },
+  "Q8RwBy": {
+    "context": "search gift card placeholder; examples, not an exhaustive list",
+    "string": "Search by code, email, user name, etc..."
+  },
   "Q8wHwJ": {
     "string": "Deleted collection"
   },
@@ -7835,6 +7846,10 @@
   "RaQzn2": {
     "string": "Rule created"
   },
+  "RalDnV": {
+    "context": "empty state when the list has no saved presets yet",
+    "string": "Saved presets will appear here"
+  },
   "RaycYK": {
     "context": "button",
     "string": "Save"
@@ -11378,9 +11393,6 @@
   "eVrDft": {
     "string": "No value"
   },
-  "eW36Jx": {
-    "string": "Saved search queries will appear here"
-  },
   "eWV760": {
     "string": "Attribute with this slug already exists"
   },
@@ -12950,9 +12962,6 @@
     "context": "column header",
     "string": "Slug"
   },
-  "kIvvax": {
-    "string": "Search Products..."
-  },
   "kJQczl": {
     "context": "sales section name",
     "string": "Sales"
@@ -15348,9 +15357,6 @@
     "context": "button",
     "string": "Assign product"
   },
-  "scTuDZ": {
-    "string": "Save search as preset"
-  },
   "sdA14A": {
     "context": "Status label when object is published in a channel",
     "string": "Published"

src/components/ConditionalFilter/UI/ConstraintReasonHint.stories.tsx

@@ -0,0 +1,71 @@
+import { Box, Text } from "@saleor/macaw-ui-next";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { ConstraintReasonHint } from "./ConstraintReasonHint";
+
+const meta: Meta<typeof ConstraintReasonHint> = {
+  title: "ConditionalFilter / ConstraintReasonHint",
+  component: ConstraintReasonHint,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ConstraintReasonHint>;
+
+const FilterRowChrome = ({ fields }: { fields: string[] }): JSX.Element => (
+  <Box
+    __width="560px"
+    padding={4}
+    display="grid"
+    __gridTemplateColumns="auto minmax(0, 1fr)"
+    columnGap={2}
+    rowGap={3}
+    alignItems="start"
+    backgroundColor="default1"
+    borderRadius={2}
+  >
+    <Text size={2} color="default2" paddingTop={1.5}>
+      where
+    </Text>
+    <Box display="flex" alignItems="center" gap={2}>
+      <Box paddingX={2} paddingY={1} borderRadius={2} backgroundColor="default2" __minWidth="120px">
+        <Text size={3}>Price</Text>
+      </Box>
+      <Box paddingX={2} paddingY={1} borderRadius={2} backgroundColor="default2">
+        <Text size={3}>is</Text>
+      </Box>
+      <Box paddingX={2} paddingY={1} borderRadius={2} backgroundColor="default2" flexGrow="1">
+        <Text size={3}>10</Text>
+      </Box>
+    </Box>
+    <Text size={2} color="default2" paddingTop={1.5}>
+      and
+    </Text>
+    <Box display="flex" alignItems="center" gap={2}>
+      <ConstraintReasonHint fields={fields} />
+      <Box paddingX={2} paddingY={1} borderRadius={2} backgroundColor="default2" __minWidth="120px">
+        <Text size={3}>Channel</Text>
+      </Box>
+      <Box paddingX={2} paddingY={1} borderRadius={2} backgroundColor="default2">
+        <Text size={3}>is</Text>
+      </Box>
+      <Box paddingX={2} paddingY={1} borderRadius={2} backgroundColor="default2" flexGrow="1">
+        <Text size={3} color="default2">
+          Select channel
+        </Text>
+      </Box>
+    </Box>
+  </Box>
+);
+
+export const Price: Story = {
+  render: () => <FilterRowChrome fields={["Price"]} />,
+};
+
+export const Several: Story = {
+  render: () => <FilterRowChrome fields={["Price", "Is published", "Is available"]} />,
+};
+
+export const Currency: Story = {
+  render: () => <FilterRowChrome fields={["Current balance"]} />,
+};

src/components/ConditionalFilter/UI/ConstraintReasonHint.test.tsx

@@ -0,0 +1,50 @@
+import Wrapper from "@test/wrapper";
+import { render, screen } from "@testing-library/react";
+
+import { ConstraintReasonHint } from "./ConstraintReasonHint";
+
+describe("ConstraintReasonHint", () => {
+  it("exposes a single dependent field on the icon", () => {
+    // Arrange // Act
+    render(
+      <Wrapper>
+        <ConstraintReasonHint fields={["Price"]} />
+      </Wrapper>,
+    );
+
+    // Assert
+    expect(
+      screen.getByRole("button", { name: "Needed for filtering on Price" }),
+    ).toBeInTheDocument();
+  });
+
+  it("joins several dependent fields", () => {
+    // Arrange // Act
+    render(
+      <Wrapper>
+        <ConstraintReasonHint fields={["Price", "Is published", "Is available"]} />
+      </Wrapper>,
+    );
+
+    // Assert
+    expect(
+      screen.getByRole("button", {
+        name: "Needed for filtering on Price, Is published, and Is available",
+      }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders nothing without dependents", () => {
+    // Arrange // Act
+    render(
+      <Wrapper>
+        <ConstraintReasonHint fields={[]} />
+      </Wrapper>,
+    );
+
+    // Assert
+    expect(
+      screen.queryByRole("button", { name: /Needed for filtering on/ }),
+    ).not.toBeInTheDocument();
+  });
+});

src/components/ConditionalFilter/UI/ConstraintReasonHint.tsx

@@ -0,0 +1,52 @@
+import { iconSize, iconStrokeWidthBySize } from "@dashboard/components/icons";
+import { Box, Tooltip } from "@saleor/macaw-ui-next";
+import { Info } from "lucide-react";
+import { useIntl } from "react-intl";
+
+import { constraintReasonMessages } from "./constraintReasonMessages";
+
+interface ConstraintReasonHintProps {
+  fields: string[];
+  testId?: string;
+}
+
+export const ConstraintReasonHint = ({
+  fields,
+  testId,
+}: ConstraintReasonHintProps): JSX.Element | null => {
+  const intl = useIntl();
+
+  if (fields.length === 0) {
+    return null;
+  }
+
+  const list = new Intl.ListFormat(intl.locale, { type: "conjunction" }).format(fields);
+  const label = intl.formatMessage(constraintReasonMessages.neededFor, { fields: list });
+
+  return (
+    <Tooltip>
+      <Tooltip.Trigger>
+        <Box
+          as="button"
+          type="button"
+          display="flex"
+          alignItems="center"
+          cursor="pointer"
+          padding={0}
+          borderWidth={0}
+          backgroundColor="transparent"
+          color="default2"
+          flexShrink="0"
+          aria-label={label}
+          data-test-id={testId}
+        >
+          <Info size={iconSize.small} strokeWidth={iconStrokeWidthBySize.small} aria-hidden />
+        </Box>
+      </Tooltip.Trigger>
+      <Tooltip.Content side="bottom" align="start">
+        <Tooltip.Arrow />
+        {label}
+      </Tooltip.Content>
+    </Tooltip>
+  );
+};

src/components/ConditionalFilter/UI/Filters.test.tsx

@@ -0,0 +1,84 @@
+import Wrapper from "@test/wrapper";
+import { render, screen } from "@testing-library/react";
+
+import { FilterEventEmitter } from "./EventEmitter";
+import { Filters } from "./Filters";
+import { type Row } from "./types";
+
+const intersectionObserverMock = (): { observe: () => null; unobserve: () => null } => ({
+  observe: (): null => null,
+  unobserve: (): null => null,
+});
+
+window.IntersectionObserver = jest.fn().mockImplementation(intersectionObserverMock);
+
+const locale = {
+  WHERE: "Where",
+  AND: "And",
+};
+
+const channelRow = (dependsOn: string[]): Row => ({
+  value: { label: "Channel", value: "channel", type: "channel" },
+  isAttribute: false,
+  constraint: { dependsOn, removable: false, disabled: ["left", "condition"] },
+  condition: {
+    options: [],
+    selected: {
+      value: "",
+      conditionValue: { type: "text", label: "is", value: "input-1" },
+    },
+  },
+});
+
+const filterRow = (value: string, label: string): Row => ({
+  value: { label, value, type: value },
+  isAttribute: false,
+  condition: {
+    options: [],
+    selected: {
+      value: "",
+      conditionValue: { type: "number", label: "is", value: "input-2" },
+    },
+  },
+});
+
+const renderFilters = (value: Array<Row | string>): void => {
+  render(
+    <Wrapper>
+      <Filters value={value} leftOptions={[]} emitter={new FilterEventEmitter()} locale={locale} />
+    </Wrapper>,
+  );
+};
+
+const follows = (earlier: HTMLElement, later: HTMLElement): boolean =>
+  (earlier.compareDocumentPosition(later) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
+
+describe("Filters constraint hint", () => {
+  it("squeezes the info icon in before Channel on the same row as And", () => {
+    // Arrange // Act
+    renderFilters([filterRow("price", "Price"), "AND", channelRow(["price"])]);
+
+    // Assert
+    const and = screen.getByText("And");
+    const hint = screen.getByTestId("constraint-reason-2");
+    const channel = screen.getByTestId("left-2");
+
+    expect(hint).toHaveAccessibleName("Needed for filtering on Price");
+    expect(follows(and, hint)).toBe(true);
+    expect(follows(hint, channel)).toBe(true);
+  });
+
+  it("places the icon before a leading Channel selector", () => {
+    // Arrange // Act
+    renderFilters([channelRow(["price"]), "AND", filterRow("price", "Price")]);
+
+    // Assert
+    const where = screen.getByText("Where");
+    const hint = screen.getByTestId("constraint-reason-0");
+    const channel = screen.getByTestId("left-0");
+
+    expect(hint).toHaveAccessibleName("Needed for filtering on Price");
+    expect(follows(where, hint)).toBe(true);
+    expect(follows(hint, channel)).toBe(true);
+  });
+});