@trackunit/filters-filter-bar 1.14.29 → 1.14.31

package/index.cjs.js

@@ -1380,7 +1380,42 @@ const HierarchicalCheckboxFilter = ({ filterDefinition, filterBarActions, option
 };
 
 /**
- * The FilterBar component serves as a wrapper for managing filters.
+ * FilterBar renders a horizontal bar of user-configurable filters. Each filter is defined via a `FilterBarDefinition`
+ * record (mapping filter keys to filter definitions such as checkbox, radio, date range, or min/max), and the bar's
+ * state is managed by the `useFilterBar` hook which returns the required `filterBarConfig` and `filterBarDefinition` props.
+ *
+ * Filters can be grouped into categories, starred for quick access, shown directly in the bar, or hidden programmatically.
+ * Filter state is automatically persisted to local storage.
+ *
+ * ### When to use
+ * Use FilterBar when a page needs user-driven filtering over a data set — for example, filtering an asset list by brand, model, status, or date range.
+ *
+ * ### When not to use
+ * Do not use FilterBar for a single search input — use `Search`.
+ * Do not use FilterBar for sorting controls — use the `Table` component's built-in sort functionality.
+ *
+ * @example Basic filter bar setup
+ * ```tsx
+ * import { FilterBar, useFilterBar, FilterBarDefinition } from "@trackunit/filters-filter-bar";
+ *
+ * const filterBarDefinition = {
+ *   brand: {
+ *     filterKey: "brand",
+ *     type: "stringArray",
+ *     group: "METADATA",
+ *     title: "Brand",
+ *     valueAsText: (values) => values,
+ *     component: (props) => <DefaultCheckboxFilter {...props} loading={false} options={brandOptions} />,
+ *   },
+ * } satisfies FilterBarDefinition;
+ *
+ * const AssetFilters = () => {
+ *   const filterBar = useFilterBar({ name: "assetFilters", filterBarDefinition });
+ *   return <FilterBar {...filterBar} />;
+ * };
+ * ```
+ * @param {FilterBarProps} props - The props for the FilterBar component
+ * @returns {ReactElement} FilterBar component
  */
 const FilterBar = ({ hiddenFilters, className, filterBarDefinition, filterBarConfig, compact = true, allowShowFiltersDirectly = true, title, }) => {
     return (jsxRuntime.jsx(FiltersMenu, { allowShowFiltersDirectly: allowShowFiltersDirectly, className: className, compact: compact, "data-testid": `${filterBarConfig.name}-filterbar`, filterBarConfig: filterBarConfig, filterBarDefinition: filterBarDefinition, hiddenFilters: hiddenFilters, title: title }));

package/index.esm.js

@@ -1378,7 +1378,42 @@ const HierarchicalCheckboxFilter = ({ filterDefinition, filterBarActions, option
 };
 
 /**
- * The FilterBar component serves as a wrapper for managing filters.
+ * FilterBar renders a horizontal bar of user-configurable filters. Each filter is defined via a `FilterBarDefinition`
+ * record (mapping filter keys to filter definitions such as checkbox, radio, date range, or min/max), and the bar's
+ * state is managed by the `useFilterBar` hook which returns the required `filterBarConfig` and `filterBarDefinition` props.
+ *
+ * Filters can be grouped into categories, starred for quick access, shown directly in the bar, or hidden programmatically.
+ * Filter state is automatically persisted to local storage.
+ *
+ * ### When to use
+ * Use FilterBar when a page needs user-driven filtering over a data set — for example, filtering an asset list by brand, model, status, or date range.
+ *
+ * ### When not to use
+ * Do not use FilterBar for a single search input — use `Search`.
+ * Do not use FilterBar for sorting controls — use the `Table` component's built-in sort functionality.
+ *
+ * @example Basic filter bar setup
+ * ```tsx
+ * import { FilterBar, useFilterBar, FilterBarDefinition } from "@trackunit/filters-filter-bar";
+ *
+ * const filterBarDefinition = {
+ *   brand: {
+ *     filterKey: "brand",
+ *     type: "stringArray",
+ *     group: "METADATA",
+ *     title: "Brand",
+ *     valueAsText: (values) => values,
+ *     component: (props) => <DefaultCheckboxFilter {...props} loading={false} options={brandOptions} />,
+ *   },
+ * } satisfies FilterBarDefinition;
+ *
+ * const AssetFilters = () => {
+ *   const filterBar = useFilterBar({ name: "assetFilters", filterBarDefinition });
+ *   return <FilterBar {...filterBar} />;
+ * };
+ * ```
+ * @param {FilterBarProps} props - The props for the FilterBar component
+ * @returns {ReactElement} FilterBar component
  */
 const FilterBar = ({ hiddenFilters, className, filterBarDefinition, filterBarConfig, compact = true, allowShowFiltersDirectly = true, title, }) => {
     return (jsx(FiltersMenu, { allowShowFiltersDirectly: allowShowFiltersDirectly, className: className, compact: compact, "data-testid": `${filterBarConfig.name}-filterbar`, filterBarConfig: filterBarConfig, filterBarDefinition: filterBarDefinition, hiddenFilters: hiddenFilters, title: title }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/filters-filter-bar",
-  "version": "1.14.29",
+  "version": "1.14.31",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,15 +14,15 @@
     "zod": "^3.23.8",
     "@trackunit/iris-app-api": "1.14.43",
     "@trackunit/react-core-hooks": "1.12.27",
-    "@trackunit/react-filter-components": "1.13.28",
-    "@trackunit/react-date-and-time-components": "1.16.28",
+    "@trackunit/react-filter-components": "1.13.30",
+    "@trackunit/react-date-and-time-components": "1.16.30",
     "@trackunit/shared-utils": "1.13.43",
-    "@trackunit/react-form-components": "1.14.25",
+    "@trackunit/react-form-components": "1.14.27",
     "@trackunit/iris-app-runtime-core-api": "1.12.24",
     "@trackunit/geo-json-utils": "1.11.43",
     "@trackunit/i18n-library-translation": "1.12.28",
     "@trackunit/css-class-variance-utilities": "1.11.43",
-    "@trackunit/react-components": "1.17.22",
+    "@trackunit/react-components": "1.17.24",
     "@tanstack/react-router": "1.114.29"
   },
   "module": "./index.esm.js",

package/src/lib/FilterBar.d.ts

@@ -33,7 +33,42 @@ interface FilterBarProps<TFilterBarDefinition extends FilterBarDefinition> {
     allowShowFiltersDirectly?: boolean;
 }
 /**
- * The FilterBar component serves as a wrapper for managing filters.
+ * FilterBar renders a horizontal bar of user-configurable filters. Each filter is defined via a `FilterBarDefinition`
+ * record (mapping filter keys to filter definitions such as checkbox, radio, date range, or min/max), and the bar's
+ * state is managed by the `useFilterBar` hook which returns the required `filterBarConfig` and `filterBarDefinition` props.
+ *
+ * Filters can be grouped into categories, starred for quick access, shown directly in the bar, or hidden programmatically.
+ * Filter state is automatically persisted to local storage.
+ *
+ * ### When to use
+ * Use FilterBar when a page needs user-driven filtering over a data set — for example, filtering an asset list by brand, model, status, or date range.
+ *
+ * ### When not to use
+ * Do not use FilterBar for a single search input — use `Search`.
+ * Do not use FilterBar for sorting controls — use the `Table` component's built-in sort functionality.
+ *
+ * @example Basic filter bar setup
+ * ```tsx
+ * import { FilterBar, useFilterBar, FilterBarDefinition } from "@trackunit/filters-filter-bar";
+ *
+ * const filterBarDefinition = {
+ *   brand: {
+ *     filterKey: "brand",
+ *     type: "stringArray",
+ *     group: "METADATA",
+ *     title: "Brand",
+ *     valueAsText: (values) => values,
+ *     component: (props) => <DefaultCheckboxFilter {...props} loading={false} options={brandOptions} />,
+ *   },
+ * } satisfies FilterBarDefinition;
+ *
+ * const AssetFilters = () => {
+ *   const filterBar = useFilterBar({ name: "assetFilters", filterBarDefinition });
+ *   return <FilterBar {...filterBar} />;
+ * };
+ * ```
+ * @param {FilterBarProps} props - The props for the FilterBar component
+ * @returns {ReactElement} FilterBar component
  */
 export declare const FilterBar: <TFilterBarDefinition extends FilterBarDefinition>({ hiddenFilters, className, filterBarDefinition, filterBarConfig, compact, allowShowFiltersDirectly, title, }: FilterBarProps<TFilterBarDefinition>) => ReactElement;
 export {};