@l3mpire/ui 2.21.0 → 2.22.0

package/USAGE.md

@@ -937,7 +937,7 @@ import {
 | `FilterBar` / `FilterBarLeft` / `FilterBarRight` | Layout container |
 | `SortButton` | Sort by dropdown (field list + asc/desc) |
 | `FilterBarButton` | "Filters" trigger with optional badge count |
-| `FilterChip` | Presentational segmented chip |
+| `FilterChip` | Presentational segmented chip (value segment truncates at 160px with tooltip on overflow) |
 | `InteractiveFilterChip` | FilterChip with per-segment popovers (property, operator, value, kebab) |
 | `PropertySelector` | 2-level popover: categories → properties with search |
 | `AdvancedChip` | Split button "Advanced filters (N)" + close (outlined neutral) |
@@ -963,6 +963,16 @@ import {
 
 **Advanced filter shortcut:** the PropertySelector footer shows an "Advanced filter · N rule(s)" item. Clicking it closes the property selector and opens the advanced popover directly in its initial empty state — where the user picks the first property inline via a "Where | [Select property ▾]" draft row. When no advanced filters exist yet, clicking this shortcut makes the AdvancedChip appear with the popover already open; closing without adding a filter removes the chip automatically.
 
+**Pinned groups (hoist a group to root):** mark a property group as "primary" so its properties render flat at the top of the `PropertySelector` popover — no category click needed. Set `groupPinned: true` on any property and the entire group is hoisted; remaining groups stay nested as categories below. Search works across everything (pinned + nested). The popover has a max-height and the "Advanced filter" footer stays sticky at the bottom when the list scrolls. The same flattening is applied in `AdvancedRow`'s property-swap popover and in `InteractiveFilterChip`'s swap popover.
+
+```tsx
+{ id: "status",   label: "Status",   type: "enum", icon: faCircleOutline, group: "task", groupLabel: "Task", groupPinned: true, ... },
+{ id: "priority", label: "Priority", type: "enum", icon: faFlagOutline,   group: "task", groupLabel: "Task", groupPinned: true, ... },
+{ id: "due_date", label: "Due date", type: "date", icon: faCalendarOutline, group: "task", groupLabel: "Task", groupPinned: true, ... },
+// Other groups stay nested — click "Contact" to see its properties.
+{ id: "contact_name", label: "Contact name", type: "text", icon: faUserOutline, group: "contact", groupLabel: "Contact", ... },
+```
+
 **Dynamic options ("Me", "Unassigned", …):** enum/tags/relation properties accept a `dynamicOptions` array. Each entry is `{ value, label, description?, icon? }` and is rendered at the top of the SingleSelect / MultiSelect dropdown with a divider separating it from the regular options. The `value` is a sentinel string stored on `FilterCondition.value` — the DS only renders, the consuming app resolves it at query time (e.g. `"__me__"` → `currentUser.id`). This keeps session/business logic out of the DS while still getting a consistent visual treatment.
 
 ```tsx

package/dist/index.d.mts

@@ -733,6 +733,13 @@ interface PropertyDefinition {
     icon: _l3mpire_icons.IconDefinition;
     group: string;
     groupLabel: string;
+    /**
+     * When true, this property's entire group is hoisted to the root of the
+     * PropertySelector popover (no category click needed). All properties in the
+     * same group share this behavior — setting it on any one property pins the
+     * whole group. Useful for "primary" groups that hold the most-used filters.
+     */
+    groupPinned?: boolean;
     options?: string[];
     /**
      * Dynamic/smart options rendered at the top of the value selector with a

package/dist/index.d.ts

@@ -733,6 +733,13 @@ interface PropertyDefinition {
     icon: _l3mpire_icons.IconDefinition;
     group: string;
     groupLabel: string;
+    /**
+     * When true, this property's entire group is hoisted to the root of the
+     * PropertySelector popover (no category click needed). All properties in the
+     * same group share this behavior — setting it on any one property pins the
+     * whole group. Useful for "primary" groups that hold the most-used filters.
+     */
+    groupPinned?: boolean;
     options?: string[];
     /**
      * Dynamic/smart options rendered at the top of the value selector with a