[CDX-336] Add visual filter support and replace filter option component by esezen · Pull Request #219 · Constructor-io/constructorio-ui-plp

esezen · 2026-03-18T10:24:52Z

Pull Request Checklist

Before you submit a pull request, please make sure you have to following:

I have added or updated TypeScript types for my changes, ensuring they are compatible with the existing codebase.
have added JSDoc comments to my TypeScript definitions for improved documentation.
have added tests that prove my fix is effective or that my feature works.
have made sure my PR is up-to-date with the main branch.

PR Type

What kind of change does this PR introduce?

Bugfix
Feature
Code style update (formatting, local variables)
Refactoring (no functional changes, no API changes)
Documentation content changes
TypeScript type definitions update
Other... Please describe:

Copilot

Pull request overview

This PR adds “visual filter” (swatch/image) rendering support for PLP facets and replaces the in-repo filter option row implementation with components from @constructor-io/constructorio-ui-components.

Changes:

Introduces visual-filter resolution helpers and per-facet visual rendering overrides (filterConfigs, callbacks).
Updates Filters/Groups rendering to use constructorio-ui-components (FilterOption, FilterOptionVisual) and wires visual props through hooks/components.
Adds/updates Storybook docs + fixtures and adds unit/component test coverage for the new visual behavior.

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/utils/visualFilterHelpers.ts	Adds helper logic for determining visual facets + resolving option visuals.
src/utils/index.ts	Re-exports the new visual filter helpers.
src/types.ts	Adds `FilterConfig` type for per-facet overrides.
src/styles.css	Imports base styles from `@constructor-io/constructorio-ui-components`.
src/hooks/useFilter.ts	Extends filter hook props/return with visual callbacks + per-facet config map.
src/components/Filters/FilterGroup.tsx	Computes `isVisual` per facet and passes visual props into option list rendering.
src/components/Filters/UseFilterOptionsList.tsx	Plumbs `isVisual` + visual resolver callbacks through the options list hook.
src/components/Filters/FilterOptionsList.tsx	Renders visual vs standard filter options using UI components + helper resolution.
src/components/Filters/FilterOptionsList.css	Removes CSS tied to the deleted in-repo option row component.
src/components/Filters/FilterOptionListRow.tsx	Deletes the custom option row component replaced by UI components.
src/components/Filters/Filters.tsx	Wires new visual props from `useFilter` into `FilterGroup` / render-props.
src/components/Groups/Groups.tsx	Replaces group option row rendering with UI component `FilterOption`.
src/components/CioPlpGrid/CioPlpGrid.tsx	Passes filter config props through to `Filters` in both desktop and modal layouts.
src/index.ts	Exports `UseFilterReturn` / `UseFilterProps` types from the package entrypoint.
src/stories/components/Filters/Filters.stories.tsx	Adds visual-filter story variants and mock facet option metadata.
src/stories/components/CioPlp/CioPlp.stories.tsx	Demonstrates passing visual filter callbacks via `filterConfigs`.
src/stories/components/CioPlp/Props.mdx	Documents the new visual filter-related config fields.
src/stories/hooks/UseFilter/UseFilterReturn.md	Documents new fields added to `UseFilterReturn`.
spec/utils/visualFilterHelpers.test.ts	Adds unit tests for the new visual filter helpers.
spec/components/Filters/Filters.test.jsx	Adds component tests verifying visual option rendering + overrides.
spec/local_examples/sampleFacets.json	Updates fixture values (“No Colour” → “No Color”).
spec/local_examples/apiSearchResponse.json	Updates fixture values (“No Colour” → “No Color”).
package.json	Adds `@constructor-io/constructorio-ui-components` dependency.
package-lock.json	Locks the new dependency and its transitive dependencies.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Adds “visual filter” rendering support (color/image swatches) to the Filters UI by introducing helper utilities and wiring new callbacks/config into the filter pipeline, while also replacing the bespoke filter option row with @constructor-io/constructorio-ui-components.

Changes:

Introduces shouldRenderVisualFacet / resolveVisualOption helpers and threads new visual-filter config callbacks through useFilter → Filters → FilterGroup → FilterOptionsList.
Replaces the internal filter option row implementation with FilterOption / FilterOptionVisual components and imports the shared UI component stylesheet.
Updates Storybook docs/stories and adds tests covering visual filter behavior; bumps Node engine requirement and adds the UI components dependency.

Reviewed changes

Copilot reviewed 27 out of 28 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/utils/visualFilterHelpers.ts	Adds visual facet decision + option visual resolution helpers.
src/utils/index.ts	Re-exports the new visual filter helpers.
src/types.ts	Adds `FacetConfig` for per-facet overrides.
src/styles.css	Imports shared UI component styles globally.
src/hooks/useFilter.ts	Extends hook props/return to include visual filter callbacks/config.
src/hooks/useCioPlp.ts	Updates filterConfigs doc comment (removes “no configs yet”).
src/components/Filters/Filters.tsx	Passes visual filter config through render props + FilterGroup.
src/components/Filters/FilterGroup.tsx	Determines “visual facet” per facet and passes flags/callbacks down.
src/components/Filters/UseFilterOptionsList.tsx	Carries visual flags/callbacks through the options list hook.
src/components/Filters/FilterOptionsList.tsx	Renders `FilterOptionVisual` when visual data is available; otherwise `FilterOption`.
src/components/Filters/FilterOptionsList.css	Removes legacy option-row styling now owned by shared UI components.
src/components/Groups/Groups.tsx	Uses shared `FilterOption` component instead of local row component.
src/components/CioPlpGrid/CioPlpGrid.tsx	Threads `filterConfigs` into `Filters` in the grid.
src/index.ts	Exports `UseFilterReturn` / `UseFilterProps` types.
src/stories/*/	Adds/updates stories + docs demonstrating visual filters and new config props.
spec/utils/visualFilterHelpers.test.ts	Adds unit tests for the new helper utilities.
spec/components/Filters/Filters.test.jsx	Adds integration-ish tests for visual filter rendering.
spec/local_examples/*.json	Normalizes “No Colour” → “No Color” in fixtures.
package.json / package-lock.json	Adds `@constructor-io/constructorio-ui-components`, broadens license allowlist, bumps Node engine to >=20.
.nvmrc	Removes pinned Node version file.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

esezen

Self review

esezen · 2026-03-18T11:26:21Z

+  getVisualImageUrl?: (option: PlpFacetOption) => string | undefined;
+  getVisualColorHex?: (option: PlpFacetOption) => string | undefined;
+  isVisualFilterFn?: (facet: PlpFacet) => boolean;
+  perFacetConfigs?: Record<string, FacetConfig>;


I don't love perFacetConfigs and I initially made this filterConfigs but we have a top level prop with the same name so I switched back

…port-to-filters

HHHindawy

Thanks for working on this, it looks great!

I just left you a couple of comments that are open for discussion if needed 🙏

HHHindawy · 2026-04-03T15:48:04Z

Looks like the License Check failed

* [CDX-285] Add support for default collapsing of individual filter groups * [CDX-285] Add sample facets with default collapsing metadata * [CDX-285] refactor & simplify filter group collapse logic in tests and components * [CDX-285] test: wrap FilterGroup component in CioPlp for API key context * [CDX-285] feat: implement per-facet configuration for collapsing filter groups * [CDX-285] fix: add missing comma in Filters.tsx for proper syntax * [CDX-285] feat: refactor color facet logic and update visual filter configurations * [CDX-285] feat: enhance filter collapsing logic and add color constants * [CDX-285] feat: update filter collapsing configuration to use defaultCollapsed instead of renderCollapsed * [CDX-285] feat: enhance defaultCollapsed documentation and implement custom collapse behavior for facets --------- Co-authored-by: Enes Kutay SEZEN <eneskutaysezen@gmail.com>

Copilot

Pull request overview

This PR introduces “visual filter” rendering (color swatches / image thumbnails) and adds configurable collapsed-by-default behavior for facet groups, while also replacing the in-repo filter option row component with shared UI components from @constructor-io/constructorio-ui-components.

Changes:

Add visual facet/option resolution helpers and wire them through useFilter → Filters → FilterGroup → FilterOptionsList.
Add facet collapse behavior driven by per-facet config, facet metadata, or a global default.
Replace filter/group option rows with shared UI components and import shared component styles; bump Node engine and add the new dependency.

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/utils/visualFilterHelpers.ts	Adds helpers to determine visual facet rendering and resolve visual option payloads.
src/utils/itemFieldGetters.ts	Adds `getIsCollapsedFacetField` getter (metadata-based collapse).
src/utils/index.ts	Re-exports `visualFilterHelpers`.
src/types.ts	Adds `FacetConfig` and extends `ItemFieldGetters` with `getIsCollapsedFacetField`.
src/styles.css	Imports shared UI components stylesheet before existing imports.
src/stories/utils/colorConstants.ts	Adds story-only color name → hex map constants.
src/stories/hooks/UseFilter/UseFilterReturn.md	Documents new `useFilter` return fields (visual + collapse).
src/stories/components/Filters/Filters.stories.tsx	Adds stories demonstrating visual filters and collapsed facets.
src/stories/components/Filters/Code Examples.mdx	Documents `filterConfigs` (collapse + visual filters) with examples.
src/stories/components/CioPlpGrid/Code Examples.mdx	Documents passing `filterConfigs` through `CioPlpGrid`.
src/stories/components/CioPlp/Props.mdx	Updates prop docs for new filter configs and collapsed getter.
src/stories/components/CioPlp/Code Examples.mdx	Adds `filterConfigs` usage example and minor formatting tweaks.
src/stories/components/CioPlp/CioPlp.stories.tsx	Demonstrates default visual filter callbacks via `filterConfigs`.
src/index.ts	Exports `UseFilterReturn` / `UseFilterProps` types.
src/hooks/useFilter.ts	Adds visual filter callbacks, `perFacetConfigs`, and `getIsCollapsed` resolver.
src/hooks/useCioPlp.ts	Updates `filterConfigs` doc comment and continues to pass configs into `useFilter`.
src/components/Groups/Groups.tsx	Replaces option row with shared `FilterOption` component (checkbox hidden).
src/components/Filters/UseFilterOptionsList.tsx	Threads visual/checkbox props through the filter options list hook.
src/components/Filters/Filters.tsx	Passes visual configs + computed collapse default down to `FilterGroup`.
src/components/Filters/FilterOptionsList.tsx	Renders shared `FilterOption`/`FilterOptionVisual` based on resolved visuals.
src/components/Filters/FilterOptionsList.css	Removes old checkbox styles; keeps a small backward-compat label fix.
src/components/Filters/FilterOptionListRow.tsx	Removes the legacy in-repo option row component.
src/components/Filters/FilterGroup.tsx	Adds initial collapsed state + visual rendering + checkbox position per facet.
src/components/CioPlpGrid/CioPlpGrid.tsx	Passes `filterConfigs` through to `Filters`; updates doc comment.
spec/utils/visualFilterHelpers.test.ts	Unit tests for visual facet/option helper priority logic.
spec/local_examples/sampleFacetsWithCollapsedMetadata.json	Adds sample facets fixture with `cio_render_collapsed`.
spec/local_examples/sampleFacets.json	Normalizes “No Colour” → “No Color” in sample facet fixture.
spec/local_examples/apiSearchResponse.json	Normalizes “No Colour” → “No Color” in sample API fixture.
spec/hooks/useFilter/useFilter.test.js	Adds tests for `getIsCollapsed` priority and custom getter behavior.
spec/components/Filters/Filters.test.jsx	Adds visual filter and collapse behavior tests; minor assertion fixes.
spec/components/Filters/Filters.server.test.jsx	Adds SSR tests for default collapsed/expanded behavior.
spec/components/Filters/FilterGroup.test.jsx	Adds tests for `FilterGroup` honoring `defaultCollapsed`.
spec/components/CioPlp/CioPlp.test.jsx	Adds client tests for `filterConfigs.defaultCollapsed`.
package.json	Adds UI components dependency, bumps Node engine, updates license allowlist.
package-lock.json	Locks new dependency tree and reflects Node engine bump.
.nvmrc	Removes the repo’s Node version file.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Alexey-Pavlov

Thank you for working on this! It looks great! Left just a few minor comments here and there

Alexey-Pavlov · 2026-04-09T14:09:51Z

-.cio-filter-option-count {
-  color: #999;
-  margin-left: 8px;
+/* Backwards compatibility temporary fix - will be removed in the next major version */


Suggested change

/* Backwards compatibility temporary fix - will be removed in the next major version */

/* TODO: Backwards compatibility temporary fix - will be removed in the next major version */

Sometimes, as a lowly WebStorm user who doesn't use Vim, TODOs really save me. When I try to commit something with a TODO, WebStorm stops the commit and gives me a chance to think twice about whether I actually want to do something about it, haha

@Alexey-Pavlov I'm down to make it a "TODO" but I would like to keep the original message. I don't think we will add the line-height to ui-components we would just remove this line and accept a slightly shift in the UI in the next major version. Wdyt?

Co-authored-by: Aleksei Pavlov <pavlov.aleksey.m@gmail.com>

Alexey-Pavlov

LGTM!

…port-to-filters

constructor-claude-bedrock

Code Review

This PR adds visual filter support (color swatches / image thumbnails) and replaces the internal FilterOptionListRow component with FilterOption/FilterOptionVisual from @constructor-io/constructorio-ui-components, while also adding per-facet and global collapse controls. The feature work is solid and well-tested, but there are several important issues to address before merge.

Inline comments: 7 discussions added

Overall Assessment: ⚠️ Needs Work

constructor-claude-bedrock · 2026-05-06T21:55:29Z

  ],
  "engines": {
-    "node": ">=14"
+    "node": ">=20"


Important Issue: The minimum Node.js engine requirement was bumped from >=14 to >=20 without any mention in the PR description or a migration/changelog note. This is a breaking change for consumers of this library who are on Node 14–19. The .nvmrc file was also deleted without a replacement (e.g., .nvmrc pointing to v20). If this bump is intentional, it should be called out in the PR description and a corresponding changelog/release-notes entry added. If it was unintentional, revert to the previous version.

@Alexey-Pavlov @HHHindawy this actually seems quite important. I looked at the previous threads and it seems like we bumped it because components-ui is tagged at a higher node version. Did we discuss the implications if we bump this?

constructor-claude-bedrock · 2026-05-06T21:55:29Z

+    sliderStep,
+    facetSliderSteps,
+    isHiddenFilterFn,
+    getVisualImageUrl,


Important Issue: getVisualImageUrl, getVisualColorHex, isVisualFilterFn, and perFacetConfigs are passed through UseFilterReturn unchanged (they are simply forwarded from props). This means the useFilter hook does not actually own or validate these values — it acts purely as a pass-through for presentational concerns. These visual rendering callbacks do not belong in a data/state hook. They should be passed directly from Filters props to FilterGroup, rather than flowing through useFilter → UseFilterReturn → Filters → FilterGroup. Mixing presentation configuration into the data hook makes both harder to understand and test independently, and unnecessarily widens the public UseFilterReturn API surface.

esezen added 3 commits March 18, 2026 13:13

Implementation

f760985

Stories and tests

c39b90e

Lint

b19e2f8

esezen requested review from HHHindawy and Mudaafi as code owners March 18, 2026 10:24

Copilot AI review requested due to automatic review settings March 18, 2026 10:24

Copilot started reviewing on behalf of esezen March 18, 2026 10:25 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

Comment thread package.json

Comment thread src/hooks/useFilter.ts Outdated

Comment thread package.json

This comment has been minimized.

Sign in to view

esezen added 3 commits March 18, 2026 13:49

Change node target

70009b4

Update license check

0939fa1

Rename filterConfigs

2dd8aaa

esezen requested a review from Copilot March 18, 2026 10:52

Copilot started reviewing on behalf of esezen March 18, 2026 10:52 View session

Copilot AI reviewed Mar 18, 2026

View reviewed changes

Comment thread src/utils/visualFilterHelpers.ts Outdated

Comment thread src/components/Filters/FilterOptionsList.tsx

Comment thread package.json

This comment has been minimized.

Sign in to view

Potential fix for pull request finding

7884e69

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

This comment has been minimized.

Sign in to view

esezen added 2 commits March 18, 2026 14:24

Address comments

a713d11

Lint

2455bfd

esezen commented Mar 18, 2026

View reviewed changes

esezen requested a review from a team March 18, 2026 11:31

This comment was marked as outdated.

Sign in to view

esezen added 3 commits March 19, 2026 22:23

Fix line height issue

4d13498

Update lock

6d38cae

Merge branch 'main' into cdx-336-plp-ui-feature-add-visual-filter-sup…

779ffd1

…port-to-filters

Alexey-Pavlov mentioned this pull request Mar 19, 2026

[CDX-285] Allow default collapsing of individual filter groups #212

Merged

12 tasks

This comment was marked as outdated.

Sign in to view

Update license check

3ed42ee

HHHindawy reviewed Apr 3, 2026

View reviewed changes

esezen added 3 commits April 6, 2026 14:46

update license check

f2887b8

Address comments

b3155a5

Update docs

a6a1c70

This comment was marked as outdated.

Sign in to view

esezen requested a review from HHHindawy April 6, 2026 12:01

HHHindawy previously approved these changes Apr 7, 2026

View reviewed changes

esezen dismissed HHHindawy’s stale review via 19ff36c April 7, 2026 14:36

esezen requested a review from Copilot April 7, 2026 14:37

Copilot started reviewing on behalf of esezen April 7, 2026 14:37 View session

esezen added the do not merge Do not merge label Apr 7, 2026

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Comment thread src/components/Filters/FilterGroup.tsx

Comment thread src/hooks/useCioPlp.ts

Comment thread src/components/CioPlpGrid/CioPlpGrid.tsx

This comment was marked as outdated.

Sign in to view

Alexey-Pavlov requested changes Apr 9, 2026

View reviewed changes

Update src/components/Filters/FilterGroup.tsx

01ca663

Co-authored-by: Aleksei Pavlov <pavlov.aleksey.m@gmail.com>

esezen requested a review from a team as a code owner April 9, 2026 16:21

esezen and others added 4 commits April 9, 2026 19:21

Update src/components/Filters/FilterOptionsList.tsx

939bb70

Co-authored-by: Aleksei Pavlov <pavlov.aleksey.m@gmail.com>

Update src/components/Filters/UseFilterOptionsList.tsx

44715f6

Co-authored-by: Aleksei Pavlov <pavlov.aleksey.m@gmail.com>

Update src/components/Filters/UseFilterOptionsList.tsx

077fd06

Co-authored-by: Aleksei Pavlov <pavlov.aleksey.m@gmail.com>

Update src/stories/components/CioPlp/Props.mdx

eded493

Co-authored-by: Aleksei Pavlov <pavlov.aleksey.m@gmail.com>

This comment was marked as outdated.

Sign in to view

Address comments

4ea25b4

Alexey-Pavlov previously approved these changes Apr 9, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

Merge branch 'main' into cdx-336-plp-ui-feature-add-visual-filter-sup…

cbbb0b8

…port-to-filters

Mudaafi dismissed Alexey-Pavlov’s stale review via cbbb0b8 May 6, 2026 21:51

constructor-claude-bedrock Bot reviewed May 6, 2026

View reviewed changes

Alexey-Pavlov approved these changes May 7, 2026

View reviewed changes

	/* Backwards compatibility temporary fix - will be removed in the next major version */
	/* TODO: Backwards compatibility temporary fix - will be removed in the next major version */

Conversation

esezen commented Mar 18, 2026 • edited by Mudaafi Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Checklist

PR Type

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

esezen left a comment

Choose a reason for hiding this comment

Uh oh!

esezen Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

HHHindawy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

HHHindawy commented Apr 3, 2026

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Alexey-Pavlov left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Alexey-Pavlov Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

esezen Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

Alexey-Pavlov left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

constructor-claude-bedrock Bot left a comment

esezen commented Mar 18, 2026 •

edited by Mudaafi

Loading

Alexey-Pavlov Apr 9, 2026 •

edited

Loading