@l3mpire/ui 2.12.0 → 2.14.0

package/USAGE.md

@@ -941,7 +941,10 @@ import {
 | `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) |
-| `AdvancedPopover` | Popover with Where/And/Or rows, property/operator selects, inline value input |
+| `AdvancedPopover` | Popover with Where/And/Or rows + nested groups, property/operator/value selects |
+| `AdvancedRow` | Single condition row (property + operator + type-aware value popover + actions) |
+| `AdvancedGroup` | Nested group container with shared connector and inline property selector |
+| `FilterNodeActions` | Kebab menu shared by rows and groups (Duplicate / Turn into group↔filter / Delete) |
 | `SaveViewButton` | Split button (Save view + dropdown chevron) |
 | `SummaryChip` | Minimal mode: "Filters (N)" with interactive popover |
 
@@ -954,8 +957,35 @@ import {
 
 **And/Or toggle:** each row in the advanced popover has an independent And/Or toggle button. The choice is **persisted on each `FilterCondition` as `logicOperator: "and" | "or"`** (defaults to `"and"` when undefined), so it survives remounts and can be serialized.
 
+**Nested groups:** the advanced popover supports arbitrarily-nested `FilterGroup` nodes via `FilterNode = FilterCondition | FilterGroup`. Each row's kebab menu (`FilterNodeActions`) lets users **Duplicate**, **Turn into group** / **Turn into filter**, or **Delete**. Groups share a single connector (`Where`/`And`/`Or`) for all their children and render an inline `PropertySelector` to add new conditions. Tree mutations go through the immutable `updateNodeInTree` / `removeNodeFromTree` / `insertAfterInTree` / `replaceNodeInTree` helpers in `utils`.
+
+**Type-aware value inputs:** every `AdvancedRow` value slot renders the same `<ValueInput>` used by `InteractiveFilterChip` — text → text input, number → number / range, date → calendar, enum/tags → single/multi select with `dynamicOptions` support, etc. The trigger button shows the formatted current value (via `formatFilterValue`) and a `+N` badge for multi-selections (via `getBadgeCount`).
+
 **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.
 
+**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
+{
+  id: "contact_owner",
+  label: "Contact owner",
+  type: "enum",
+  icon: faUserOutline,
+  group: "contact",
+  groupLabel: "Contact",
+  options: ["Quentin", "Simon", "Philippe"],
+  dynamicOptions: [
+    {
+      value: "__me__",
+      label: "Me",
+      description: "This value is dynamically applied to the current user",
+      icon: faBoltOutline,
+    },
+    { value: "__deactivated__", label: "All deactivated and removed owners", icon: faBoltOutline },
+  ],
+}
+```
+
 | Utility | Purpose |
 |---|---|
 | `OPERATORS_BY_TYPE` | Operators for each DataType |
@@ -963,6 +993,13 @@ import {
 | `createFilterWithDefaults(propertyId, type)` | Creates FilterCondition with default operator |
 | `isNoValueOperator(op)` | True for is empty / is not empty / is true / is false |
 | `getValueInputType(type, op)` | Returns the input component name for a type+operator combo |
+| `formatFilterValue(value)` | Stringifies a `FilterValue` for display (handles Date, ranges, arrays, booleans) |
+| `getBadgeCount(value)` | Returns `+N` count for multi-value selections, `undefined` otherwise |
+| `createEmptyGroup()` / `isFilterGroup(node)` | Tree helpers for nested groups |
+| `wrapInGroup(condition)` / `unwrapGroup(group)` | Convert between condition and single-child group |
+| `duplicateNode(node)` | Deep clone a node tree with fresh UUIDs |
+| `updateNodeInTree` / `removeNodeFromTree` / `insertAfterInTree` / `replaceNodeInTree` | Immutable tree mutations by id |
+| `countConditions(nodes)` | Count all leaf conditions in a tree |
 
 ---
 

package/dist/index.d.mts

@@ -676,12 +676,28 @@ declare const FilterChip: React.ForwardRefExoticComponent<FilterChipProps & Reac
 type DataType = "text" | "number" | "date" | "enum" | "tags" | "boolean" | "relation";
 type TextOperator = "contains" | "does not contain" | "is" | "is not" | "starts with" | "ends with" | "is empty" | "is not empty";
 type NumberOperator = "=" | "≠" | ">" | "<" | "≥" | "≤" | "is between" | "is empty" | "is not empty";
-type DateOperator = "is" | "is before" | "is after" | "is on or before" | "is on or after" | "is between" | "is relative" | "is empty" | "is not empty";
+type DateOperator = "is" | "is before" | "is after" | "is on or before" | "is on or after" | "is between" | "is empty" | "is not empty";
 type EnumOperator = "is" | "is not" | "is any of" | "is none of" | "is empty" | "is not empty";
 type TagsOperator = "contains" | "does not contain" | "contains any of" | "contains all of" | "is empty" | "is not empty";
 type BooleanOperator = "is true" | "is false";
 type RelationOperator = "is" | "is not" | "is any of" | "is none of" | "is empty" | "is not empty";
 type OperatorType = TextOperator | NumberOperator | DateOperator | EnumOperator | TagsOperator | BooleanOperator | RelationOperator;
+/**
+ * A "smart" / dynamic option shown at the top of a relation or enum selector
+ * (e.g. "Me", "My team", "Unassigned"). The value is a sentinel string that
+ * the consuming app resolves at query time (e.g. `__me__` → `currentUser.id`).
+ *
+ * The design system only handles the rendering (icon + label + description +
+ * divider above the regular options). Resolving the sentinels is an app
+ * concern.
+ */
+interface DynamicOption {
+    /** Sentinel value stored on FilterCondition.value (e.g. "__me__"). */
+    value: string;
+    label: string;
+    description?: string;
+    icon?: _l3mpire_icons.IconDefinition;
+}
 interface PropertyDefinition {
     id: string;
     label: string;
@@ -690,6 +706,12 @@ interface PropertyDefinition {
     group: string;
     groupLabel: string;
     options?: string[];
+    /**
+     * 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
+     * the sentinel values at query time.
+     */
+    dynamicOptions?: DynamicOption[];
     relationConfig?: {
         entity: string;
         displayProperty: string;
@@ -701,15 +723,27 @@ type FilterValue = string | number | boolean | Date | [number, number] | [Date,
 type LogicOperator = "and" | "or";
 interface FilterCondition {
     id: string;
+    /** Optional discriminator. Defaults to "condition" when absent. */
+    type?: "condition";
     propertyId: string;
     operator: OperatorType | null;
     value: FilterValue;
-    /** Logic connector to the previous filter. Defaults to "and". */
+    /** Logic connector to the previous sibling. Defaults to "and". */
+    logicOperator?: LogicOperator;
+}
+interface FilterGroup {
+    id: string;
+    type: "group";
+    /** Logic connector to the previous sibling. Defaults to "and". */
     logicOperator?: LogicOperator;
+    children: FilterNode[];
 }
+/** A filter node is either a single condition or a group of nested nodes. */
+type FilterNode = FilterCondition | FilterGroup;
 interface FilterState {
     basicFilters: FilterCondition[];
-    advancedFilters: FilterCondition[];
+    /** Supports nested groups. Each node is either a condition or a group. */
+    advancedFilters: FilterNode[];
     sort: {
         field: string;
         direction: "asc" | "desc";
@@ -814,6 +848,8 @@ interface ValueInputProps {
     onChange: (value: FilterValue) => void;
     onSubmit?: () => void;
     options?: string[];
+    /** Dynamic/smart entries rendered at the top with a divider. */
+    dynamicOptions?: DynamicOption[];
     className?: string;
 }
 declare const ValueInput: React.FC<ValueInputProps>;
@@ -914,13 +950,15 @@ interface AdvancedRowProps {
     onUpdate: (condition: FilterCondition) => void;
     onPropertyChange: (property: PropertyDefinition) => void;
     onDelete: () => void;
+    onDuplicate?: () => void;
+    onTurnIntoGroup?: () => void;
 }
 declare const AdvancedRow: React.FC<AdvancedRowProps>;
 
 interface AdvancedPopoverProps {
-    filters: FilterCondition[];
+    filters: FilterNode[];
     properties: PropertyDefinition[];
-    onFiltersChange: (filters: FilterCondition[]) => void;
+    onFiltersChange: (filters: FilterNode[]) => void;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     children?: React.ReactNode;
@@ -929,14 +967,12 @@ declare const AdvancedPopover: React.FC<AdvancedPopoverProps>;
 
 interface SummaryChipProps {
     count: number;
-    filters: FilterCondition[];
+    filters: FilterNode[];
     properties: PropertyDefinition[];
-    onFiltersChange: (filters: FilterCondition[]) => void;
+    onFiltersChange: (filters: FilterNode[]) => void;
     onClearAll: () => void;
-    /** Custom trigger element. When omitted, renders the default "Filters (N)" button. */
     children?: React.ReactNode;
     className?: string;
-    /** Controlled open state. */
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
 }

package/dist/index.d.ts

@@ -676,12 +676,28 @@ declare const FilterChip: React.ForwardRefExoticComponent<FilterChipProps & Reac
 type DataType = "text" | "number" | "date" | "enum" | "tags" | "boolean" | "relation";
 type TextOperator = "contains" | "does not contain" | "is" | "is not" | "starts with" | "ends with" | "is empty" | "is not empty";
 type NumberOperator = "=" | "≠" | ">" | "<" | "≥" | "≤" | "is between" | "is empty" | "is not empty";
-type DateOperator = "is" | "is before" | "is after" | "is on or before" | "is on or after" | "is between" | "is relative" | "is empty" | "is not empty";
+type DateOperator = "is" | "is before" | "is after" | "is on or before" | "is on or after" | "is between" | "is empty" | "is not empty";
 type EnumOperator = "is" | "is not" | "is any of" | "is none of" | "is empty" | "is not empty";
 type TagsOperator = "contains" | "does not contain" | "contains any of" | "contains all of" | "is empty" | "is not empty";
 type BooleanOperator = "is true" | "is false";
 type RelationOperator = "is" | "is not" | "is any of" | "is none of" | "is empty" | "is not empty";
 type OperatorType = TextOperator | NumberOperator | DateOperator | EnumOperator | TagsOperator | BooleanOperator | RelationOperator;
+/**
+ * A "smart" / dynamic option shown at the top of a relation or enum selector
+ * (e.g. "Me", "My team", "Unassigned"). The value is a sentinel string that
+ * the consuming app resolves at query time (e.g. `__me__` → `currentUser.id`).
+ *
+ * The design system only handles the rendering (icon + label + description +
+ * divider above the regular options). Resolving the sentinels is an app
+ * concern.
+ */
+interface DynamicOption {
+    /** Sentinel value stored on FilterCondition.value (e.g. "__me__"). */
+    value: string;
+    label: string;
+    description?: string;
+    icon?: _l3mpire_icons.IconDefinition;
+}
 interface PropertyDefinition {
     id: string;
     label: string;
@@ -690,6 +706,12 @@ interface PropertyDefinition {
     group: string;
     groupLabel: string;
     options?: string[];
+    /**
+     * 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
+     * the sentinel values at query time.
+     */
+    dynamicOptions?: DynamicOption[];
     relationConfig?: {
         entity: string;
         displayProperty: string;
@@ -701,15 +723,27 @@ type FilterValue = string | number | boolean | Date | [number, number] | [Date,
 type LogicOperator = "and" | "or";
 interface FilterCondition {
     id: string;
+    /** Optional discriminator. Defaults to "condition" when absent. */
+    type?: "condition";
     propertyId: string;
     operator: OperatorType | null;
     value: FilterValue;
-    /** Logic connector to the previous filter. Defaults to "and". */
+    /** Logic connector to the previous sibling. Defaults to "and". */
+    logicOperator?: LogicOperator;
+}
+interface FilterGroup {
+    id: string;
+    type: "group";
+    /** Logic connector to the previous sibling. Defaults to "and". */
     logicOperator?: LogicOperator;
+    children: FilterNode[];
 }
+/** A filter node is either a single condition or a group of nested nodes. */
+type FilterNode = FilterCondition | FilterGroup;
 interface FilterState {
     basicFilters: FilterCondition[];
-    advancedFilters: FilterCondition[];
+    /** Supports nested groups. Each node is either a condition or a group. */
+    advancedFilters: FilterNode[];
     sort: {
         field: string;
         direction: "asc" | "desc";
@@ -814,6 +848,8 @@ interface ValueInputProps {
     onChange: (value: FilterValue) => void;
     onSubmit?: () => void;
     options?: string[];
+    /** Dynamic/smart entries rendered at the top with a divider. */
+    dynamicOptions?: DynamicOption[];
     className?: string;
 }
 declare const ValueInput: React.FC<ValueInputProps>;
@@ -914,13 +950,15 @@ interface AdvancedRowProps {
     onUpdate: (condition: FilterCondition) => void;
     onPropertyChange: (property: PropertyDefinition) => void;
     onDelete: () => void;
+    onDuplicate?: () => void;
+    onTurnIntoGroup?: () => void;
 }
 declare const AdvancedRow: React.FC<AdvancedRowProps>;
 
 interface AdvancedPopoverProps {
-    filters: FilterCondition[];
+    filters: FilterNode[];
     properties: PropertyDefinition[];
-    onFiltersChange: (filters: FilterCondition[]) => void;
+    onFiltersChange: (filters: FilterNode[]) => void;
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     children?: React.ReactNode;
@@ -929,14 +967,12 @@ declare const AdvancedPopover: React.FC<AdvancedPopoverProps>;
 
 interface SummaryChipProps {
     count: number;
-    filters: FilterCondition[];
+    filters: FilterNode[];
     properties: PropertyDefinition[];
-    onFiltersChange: (filters: FilterCondition[]) => void;
+    onFiltersChange: (filters: FilterNode[]) => void;
     onClearAll: () => void;
-    /** Custom trigger element. When omitted, renders the default "Filters (N)" button. */
     children?: React.ReactNode;
     className?: string;
-    /** Controlled open state. */
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
 }