@l3mpire/ui 2.21.1 → 2.23.0

package/USAGE.md

@@ -963,6 +963,49 @@ 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", ... },
+```
+
+**Enum options with icons + intent dots:** `options` accepts either strings (backwards-compatible) or objects `{ value, label?, icon?, intent? }`. Set `icon` to render a FontAwesome icon left of the label; set `intent` (`primary` / `success` / `warning` / `critical` / `neutral`) to render a colored dot instead. The icon also appears as an adornment on the chip when the value is selected, so users recognize the option at a glance. Applied in the value popover, the `InteractiveFilterChip`, and `AdvancedRow`.
+
+```tsx
+// Channel-type enum — icons everywhere
+{
+  id: "task_type",
+  label: "Task type",
+  type: "enum",
+  options: [
+    { value: "call",     label: "Call",     icon: faPhoneOutline },
+    { value: "email",    label: "Email",    icon: faEnvelopeOutline },
+    { value: "linkedin", label: "LinkedIn", icon: faLinkedinOutline },
+    "Manual", // plain string still works
+  ],
+  // ...
+}
+
+// Status-type enum — intent dots
+{
+  id: "task_status",
+  label: "Status",
+  type: "enum",
+  options: [
+    { value: "todo",        label: "To do",       intent: "neutral" },
+    { value: "in_progress", label: "In progress", intent: "primary" },
+    { value: "done",        label: "Done",        intent: "success" },
+    { value: "blocked",     label: "Blocked",     intent: "warning" },
+    { value: "cancelled",   label: "Cancelled",   intent: "critical" },
+  ],
+  // ...
+}
+```
+
 **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

@@ -726,6 +726,22 @@ interface DynamicOption {
     label: string;
     description?: string;
 }
+/**
+ * Visual intent for a colored dot next to an enum option. Used when no icon is
+ * provided — e.g. status-style enums where color carries the semantic meaning.
+ */
+type EnumOptionIntent = "primary" | "success" | "warning" | "critical" | "neutral";
+/**
+ * An enum option value. Plain strings are kept for backwards compatibility —
+ * the string is used as both the value and the label. Object form lets you
+ * attach an icon, a custom label, or a colored dot (via `intent`).
+ */
+type EnumOption = string | {
+    value: string;
+    label?: string;
+    icon?: _l3mpire_icons.IconDefinition;
+    intent?: EnumOptionIntent;
+};
 interface PropertyDefinition {
     id: string;
     label: string;
@@ -733,7 +749,14 @@ interface PropertyDefinition {
     icon: _l3mpire_icons.IconDefinition;
     group: string;
     groupLabel: string;
-    options?: 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?: EnumOption[];
     /**
      * Dynamic/smart options rendered at the top of the value selector with a
      * divider. Only used for enum, tags, and relation types. The app resolves
@@ -875,7 +898,7 @@ interface ValueInputProps {
     value: FilterValue;
     onChange: (value: FilterValue) => void;
     onSubmit?: () => void;
-    options?: string[];
+    options?: EnumOption[];
     /** Dynamic/smart entries rendered at the top with a divider. */
     dynamicOptions?: DynamicOption[];
     className?: string;

package/dist/index.d.ts

@@ -726,6 +726,22 @@ interface DynamicOption {
     label: string;
     description?: string;
 }
+/**
+ * Visual intent for a colored dot next to an enum option. Used when no icon is
+ * provided — e.g. status-style enums where color carries the semantic meaning.
+ */
+type EnumOptionIntent = "primary" | "success" | "warning" | "critical" | "neutral";
+/**
+ * An enum option value. Plain strings are kept for backwards compatibility —
+ * the string is used as both the value and the label. Object form lets you
+ * attach an icon, a custom label, or a colored dot (via `intent`).
+ */
+type EnumOption = string | {
+    value: string;
+    label?: string;
+    icon?: _l3mpire_icons.IconDefinition;
+    intent?: EnumOptionIntent;
+};
 interface PropertyDefinition {
     id: string;
     label: string;
@@ -733,7 +749,14 @@ interface PropertyDefinition {
     icon: _l3mpire_icons.IconDefinition;
     group: string;
     groupLabel: string;
-    options?: 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?: EnumOption[];
     /**
      * Dynamic/smart options rendered at the top of the value selector with a
      * divider. Only used for enum, tags, and relation types. The app resolves
@@ -875,7 +898,7 @@ interface ValueInputProps {
     value: FilterValue;
     onChange: (value: FilterValue) => void;
     onSubmit?: () => void;
-    options?: string[];
+    options?: EnumOption[];
     /** Dynamic/smart entries rendered at the top with a divider. */
     dynamicOptions?: DynamicOption[];
     className?: string;