hs-uix 2.1.0 → 2.2.0

package/src/feed/index.d.ts

@@ -7,6 +7,7 @@ export type FeedFilterType = "select" | "multiselect" | "dateRange";
 export type FeedSortDirection = "asc" | "desc" | "ascending" | "descending";
 export type FeedStatusVariant = "default" | "info" | "success" | "warning" | "danger";
 export type FeedTagVariant = "default" | "info" | "success" | "warning" | "error";
+export type FeedNewItemsBehavior = "immediate" | "pill";
 
 export interface FeedOption<T = string | number | boolean> {
   label: string;
@@ -74,6 +75,8 @@ export interface FeedItem {
   avatarSize?: string | number;
   icon?: ReactNode | string;
   iconName?: string;
+  /** Icon color: native enum (`alert`/`warning`/`success`/`inherit`) or any CSS color (renders via the SVG fallback). */
+  iconColor?: string;
   href?: string | { url: string; external?: boolean };
   meta?: ReactNode | ReactNode[];
   metadata?: ReactNode | ReactNode[];
@@ -141,6 +144,10 @@ export interface FeedLabels {
   errorTitle?: string;
   errorMessage?: string;
   itemCount?: (shown: number, total: number, label: string) => string;
+  /** "Show N new items" pill label (string or count-aware function). */
+  newItems?: string | ((count: number) => string);
+  /** Text inside the info Tag marking recently arrived items. */
+  newItemTag?: string;
 }
 
 export interface FeedTabOption<T = string | number | boolean> {
@@ -193,6 +200,80 @@ export interface FeedRecordLabel {
   plural?: string;
 }
 
+export interface FeedTypePreset {
+  /** Native HubSpot icon name (verified against the native whitelist for the built-in presets). */
+  icon?: string;
+  /** Icon color: native enum (`alert`/`warning`/`success`/`inherit`) or any CSS color. */
+  color?: string;
+  /** Display label used as `typeLabel` when the item has none. */
+  label?: ReactNode;
+  /** StatusTag variant applied when the item has no status variant of its own. */
+  statusVariant?: FeedStatusVariant;
+}
+
+export type FeedTypePresets = Record<string, FeedTypePreset>;
+
+/**
+ * Built-in presets for HubSpot's standard activity types (`call`, `email`,
+ * `incoming_email`, `forwarded_email`, `meeting`, `note`, `task`, `sms`,
+ * `whatsapp`, `linkedin_message`, `postal_mail`, `conversation`).
+ */
+export declare const DEFAULT_FEED_TYPE_PRESETS: FeedTypePresets;
+
+/** Resolve the preset for a type value (exact, lowercase, then snake_case lookup). */
+export declare function lookupTypePreset(
+  type: unknown,
+  presets?: FeedTypePresets | null
+): FeedTypePreset | null;
+
+/** Merge a type preset UNDER an item (item-level values win). Returns the same reference when nothing changes. */
+export declare function applyTypePreset<Row = FeedItem>(
+  item: Row,
+  typePresets?: FeedTypePresets | null
+): Row;
+
+export interface FeedPartitionOptions<Row = FeedItem> {
+  /** Ids already rendered — updates to these never buffer. */
+  knownIds?: Set<string | number> | null;
+  /** Id accessor; defaults to `item.id ?? item.key ?? index`. */
+  getId?: (item: Row, index: number) => string | number | undefined;
+}
+
+export interface FeedPartitionResult<Row = FeedItem> {
+  visible: Row[];
+  buffered: Row[];
+  visibleIds: Array<string | number | undefined>;
+  bufferedIds: Array<string | number | undefined>;
+  /** New monotonic watermark over VISIBLE items only (epoch ms), or null. */
+  newestTs: number | null;
+}
+
+/** Pure live-buffer kernel: split items into visible vs newer-than-watermark buffered. */
+export declare function partitionNewItems<Row = FeedItem>(
+  prevNewestTs: number | null | undefined,
+  items: Row[] | null | undefined,
+  getTs: (item: Row) => unknown,
+  options?: FeedPartitionOptions<Row>
+): FeedPartitionResult<Row>;
+
+export interface FeedFlushResult<Row = FeedItem> {
+  /** Buffered items first, then the previously visible items. */
+  items: Row[];
+  flushed: Row[];
+  /** New watermark across ALL merged items (epoch ms), or null. */
+  newestTs: number | null;
+}
+
+/** Pure flush: merge the buffer into the visible list and compute the new watermark. */
+export declare function flushBuffer<Row = FeedItem>(
+  visible: Row[] | null | undefined,
+  buffered: Row[] | null | undefined,
+  getTs: (item: Row) => unknown
+): FeedFlushResult<Row>;
+
+/** Coerce Date | epoch number | parseable string | { year, month, date } to epoch ms (or null). */
+export declare function toTimestampMs(value: unknown): number | null;
+
 export interface FeedProps<Row = FeedItem> {
   items?: Row[];
   fields?: FeedField<Row>[];
@@ -274,6 +355,28 @@ export interface FeedProps<Row = FeedItem> {
   collapsedIds?: (string | number)[];
   onCollapsedIdsChange?: (next: (string | number)[]) => void;
   showCollapseToggle?: boolean;
+  /**
+   * Real-time append behavior for items that arrive NEWER than the
+   * previously-newest visible timestamp. "immediate" (default) renders them
+   * right away; "pill" holds them in a buffer behind a centered
+   * "Show N new items" Button until clicked. Updates to already-visible items
+   * (matched by key) are never buffered.
+   */
+  newItemsBehavior?: FeedNewItemsBehavior;
+  /** Called with the released items when the "Show N new items" pill is clicked. */
+  onNewItemsFlush?: (items: Row[]) => void;
+  /**
+   * Window in ms during which flushed/freshly-prepended items carry an info
+   * Tag "New" marker. `false` (default) disables the marker. The initial load
+   * is never marked.
+   */
+  highlightNew?: number | false;
+  /**
+   * Per-type display defaults merged UNDER item values (item wins):
+   * `{ [type]: { icon, color, label, statusVariant } }`. Pass `true` to use
+   * DEFAULT_FEED_TYPE_PRESETS. Lookup by `item.type` is case-insensitive.
+   */
+  typePresets?: FeedTypePresets | boolean | null;
 }
 
 export declare function Feed<Row = FeedItem>(props: FeedProps<Row>): ReactNode;

package/src/filter/README.md

@@ -0,0 +1,148 @@
+# FilterBuilder (hs-uix/filter)
+
+The HubSpot list/workflow segment-builder pattern as one component: nested AND/OR groups of property → operator → value rows. If your extension needs "show me deals where amount > 10k AND (stage is X OR stage is Y)", this is the component — stop hand-rolling three Selects in a Flex row with an ad-hoc state shape. The tree it emits converts directly to HubSpot CRM search `filterGroups` via `toCrmSearchFilterGroups`.
+
+Renders entirely with native components: `Select` / `MultiSelect` / `Input` / `NumberInput` / `DateInput` rows inside `Flex`, nested groups in `Tile`. Every action is a `Button` carrying HubSpot's segment-builder iconography — add (`+`) for "Add filter" / "Add filter group", a remove (`x`) icon button on each condition row, and copy / trash icon buttons on each group header for clone / delete.
+
+## Quick Start
+
+```jsx
+import { useState } from "react";
+import { FilterBuilder, toCrmSearchFilterGroups, validateTree } from "hs-uix/filter";
+
+const PROPERTIES = [
+  { name: "dealname", label: "Deal name", type: "string" },
+  { name: "amount", label: "Amount", type: "number" },
+  { name: "closedate", label: "Close date", type: "date" },
+  {
+    name: "dealstage",
+    label: "Stage",
+    type: "enum",
+    options: [
+      { label: "Appointment", value: "appointmentscheduled" },
+      { label: "Qualified", value: "qualifiedtobuy" },
+    ],
+  },
+  { name: "hs_is_closed", label: "Is closed", type: "bool" },
+];
+
+const SegmentEditor = () => {
+  const [tree, setTree] = useState();
+
+  const runSearch = () => {
+    if (!tree || !validateTree(tree, PROPERTIES).valid) return;
+    const { filterGroups } = toCrmSearchFilterGroups(tree);
+    // → hubspot.fetch CRM search body: { filterGroups, properties: [...], ... }
+  };
+
+  return <FilterBuilder properties={PROPERTIES} defaultValue={tree} onChange={setTree} />;
+};
+```
+
+## The filter tree (public contract)
+
+```js
+{
+  type: "group",
+  operator: "AND" | "OR",
+  filters: [
+    { type: "condition", property: "amount", operator: "BETWEEN", value: 1000, highValue: 5000 },
+    { type: "group", operator: "OR", filters: [ /* nested */ ] },
+  ],
+}
+```
+
+- The root is always a group. An empty root means "no filters".
+- Conditions carry `value` (scalar, or array for `IN` / `NOT_IN`) and `highValue` (only `BETWEEN`). `HAS_PROPERTY` / `NOT_HAS_PROPERTY` carry no value.
+- Paths into the tree are index arrays: `[]` is the root, `[1, 0]` is the root's second child's first child.
+
+## Operators per property type (CRM search names)
+
+| Type | Operators | Value editor |
+|---|---|---|
+| `string` | `EQ`, `NEQ`, `CONTAINS_TOKEN`, `NOT_CONTAINS_TOKEN`, `HAS_PROPERTY`, `NOT_HAS_PROPERTY` | `Input` |
+| `number` | `EQ`, `NEQ`, `GT`, `GTE`, `LT`, `LTE`, `BETWEEN`, `HAS_PROPERTY`, `NOT_HAS_PROPERTY` | `NumberInput` (× 2 for `BETWEEN`) |
+| `date` / `datetime` | same as `number`, labeled "is after" / "is before" | `DateInput` (× 2 for `BETWEEN`) |
+| `enum` | `IN`, `NOT_IN`, `HAS_PROPERTY`, `NOT_HAS_PROPERTY` | `MultiSelect` over the property's `options` |
+| `bool` | `EQ` | `Select` (True / False → `"true"` / `"false"`) |
+
+`HAS_PROPERTY` / `NOT_HAS_PROPERTY` render no value editor. The native `DateInput` is date-only, so `datetime` properties get day precision in the UI.
+
+## Features
+
+- Controlled (`value` + `onChange`) or uncontrolled (`defaultValue`) tree state
+- Nested groups to `maxDepth` (default 2 — root plus one level, matching HubSpot's builder)
+- Per-group AND/OR toggle rendered between rows; changing any separator updates the whole group
+- Nested groups get a numbered heading ("Group 1", "Group 2", …) with clone (copy icon) and delete (trash icon) buttons, matching HubSpot's builder
+- Property changes keep the operator when still valid for the new type, otherwise reset it; values are always cleared
+- Operator changes keep values whose shape still fits (scalar→scalar, `IN`↔`NOT_IN`)
+- Removing a group's last row prunes the now-empty group (root always survives)
+- `readOnly` mode renders the tree without add/remove/edit affordances
+- Every behavioral rule lives in pure, exported, unit-tested helpers (`filterTree.js`)
+
+## `toCrmSearchFilterGroups(tree, options?)`
+
+Converts the tree to the HubSpot CRM search shape — `{ filterGroups: [{ filters: [...] }] }`, where filters in a group are ANDed and the groups are ORed.
+
+```js
+toCrmSearchFilterGroups({
+  type: "group", operator: "AND", filters: [
+    { type: "condition", property: "amount", operator: "GT", value: 1000 },
+    { type: "group", operator: "OR", filters: [
+      { type: "condition", property: "dealstage", operator: "IN", value: ["a"] },
+      { type: "condition", property: "hs_is_closed", operator: "EQ", value: "false" },
+    ] },
+  ],
+});
+// → { filterGroups: [
+//      { filters: [{ propertyName: "amount", operator: "GT", value: 1000 }, { propertyName: "dealstage", operator: "IN", values: ["a"] }] },
+//      { filters: [{ propertyName: "amount", operator: "GT", value: 1000 }, { propertyName: "hs_is_closed", operator: "EQ", value: "false" }] },
+//    ] }
+```
+
+**Flattening rules.** The tree is expanded to disjunctive normal form, so nesting at ANY depth converts — `A AND (B OR C)` distributes to `[A,B] | [A,C]`, ORs nested under ORs flatten, and `(A OR B) AND (C OR D)` becomes the 4-group cartesian product. The cost is combinatorial: every OR nested under an AND **multiplies** filterGroups and duplicates the sibling conditions into each one.
+
+**Limits.** CRM search rejects more than 5 filterGroups, 6 filters per group, or 18 filters total. When the expansion exceeds a limit, this **throws** with a descriptive message instead of sending a request that will 400. Tune via `maxGroups` / `maxFiltersPerGroup` / `maxTotalFilters`, or pass `enforceLimits: false`.
+
+**Value coercion** (default on, disable with `coerceValues: false`): `DateInput` value objects (`{ year, month, date }`) become epoch-ms numbers (local midnight, matching the `hs-uix/utils` dateRange helpers); booleans become `"true"` / `"false"` strings. Pre-convert and pass numbers/strings yourself if you need different semantics (e.g. UTC midnight).
+
+Empty nested groups throw — run `validateTree` first and gate your search button on `valid`.
+
+## Props
+
+### `<FilterBuilder />`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `properties` | `FilterProperty[]` | — | Required. `{ name, label?, type?, options? }`; `type` defaults to `"string"`; `enum` needs `options`. |
+| `value` | `FilterGroupNode` | — | Controlled tree. |
+| `defaultValue` | `FilterGroupNode` | empty AND group | Initial tree for uncontrolled mode. |
+| `onChange` | `(tree) => void` | — | Fired with the full new tree after every edit. |
+| `maxDepth` | `number` | `2` | Max group nesting; root counts as 1. `1` disables "Add filter group". |
+| `labels` | `FilterBuilderLabels` | built-in copy | Overrides for `addFilter`, `addGroup`, `remove`, `removeGroup`, `cloneGroup`, `group`, `and`, `or`, `property`, `operator`, `value`, `values`, `between`, `empty`, `true`, `false`. `remove` / `removeGroup` / `cloneGroup` are screen-reader text on the icon buttons; `group` prefixes group headings. |
+| `operatorLabels` | `Record<operator, string>` | — | Per-operator label overrides for the operator dropdowns. |
+| `readOnly` | `boolean` | `false` | Render without edit affordances. |
+| `namePrefix` | `string` | `"filter-builder"` | Prefix for native input `name`s; set when rendering two builders on one surface. |
+| `...rest` | — | — | Spread onto the root `Flex`. |
+
+### Pure helpers (all exported from `hs-uix/filter`)
+
+| Export | Signature | Notes |
+|---|---|---|
+| `FILTER_OPERATORS` | `Record<type, operator[]>` | The operator sets per property type. |
+| `getOperatorOptions` | `(type, labelOverrides?) => { label, value }[]` | Select-ready operator options; date types get before/after phrasing. |
+| `operatorExpectsValue` / `operatorExpectsHighValue` / `operatorExpectsValues` | `(operator) => boolean` | Value-arity rules. |
+| `createCondition` | `(property?, operator?, value?, highValue?) => node` | `value`/`highValue` keys only present when provided. |
+| `createGroup` | `(operator?, filters?) => node` | Defaults to an empty AND group. |
+| `isGroupNode` / `isConditionNode` | `(node) => boolean` | Type guards. |
+| `getNodeAtPath` | `(tree, path) => node \| undefined` | Lenient read. |
+| `addFilter` | `(tree, groupPath, node) => tree` | Immutable append; throws if the path isn't a group. |
+| `updateFilter` | `(tree, path, patch \| fn) => tree` | Object patch merges; function patch replaces the node. |
+| `removeFilter` | `(tree, path, { pruneEmptyGroups? }) => tree` | Throws on the root path; prune cascades upward but never removes the root. |
+| `duplicateFilter` | `(tree, path) => tree` | Deep-clones the node at `path` (condition or group) and inserts the copy right after it. Throws on the root path. |
+| `countConditions` | `(node) => number` | Conditions only; groups don't count. |
+| `changeConditionProperty` | `(condition, propertyDef) => condition` | Keeps a still-valid operator, clears values. |
+| `changeConditionOperator` | `(condition, operator) => condition` | Keeps shape-compatible values. |
+| `validateTree` | `(tree, properties?) => { valid, errors: [{ path, message }] }` | Empty root is valid; empty nested groups are not. |
+| `conditionToCrmFilter` | `(condition, { coerceValues? }) => crmFilter` | One condition → `{ propertyName, operator, value/values/highValue }`. |
+| `toCrmSearchFilterGroups` | `(tree, options?) => { filterGroups }` | DNF expansion + limit enforcement (see above). |

package/src/filter/index.d.ts

@@ -0,0 +1,221 @@
+import type { ReactNode } from "react";
+
+export type FilterPropertyType = "string" | "number" | "date" | "datetime" | "enum" | "bool";
+
+export type FilterOperator =
+  | "EQ"
+  | "NEQ"
+  | "CONTAINS_TOKEN"
+  | "NOT_CONTAINS_TOKEN"
+  | "GT"
+  | "GTE"
+  | "LT"
+  | "LTE"
+  | "BETWEEN"
+  | "IN"
+  | "NOT_IN"
+  | "HAS_PROPERTY"
+  | "NOT_HAS_PROPERTY";
+
+export type FilterGroupOperator = "AND" | "OR";
+
+/** Path into nested `filters` arrays. `[]` is the root group, `[1, 0]` is the root's second child's first child. */
+export type FilterTreePath = number[];
+
+export interface FilterPropertyOption {
+  label: string;
+  value: string | number | boolean;
+}
+
+export interface FilterProperty {
+  name: string;
+  label?: string;
+  /** Defaults to "string". Enum properties need `options`. */
+  type?: FilterPropertyType;
+  options?: FilterPropertyOption[];
+}
+
+export interface FilterConditionNode {
+  type: "condition";
+  property: string;
+  /** "" while the user has not picked an operator yet. */
+  operator: FilterOperator | "";
+  /** Scalar for most operators; array for IN / NOT_IN; absent for HAS_PROPERTY / NOT_HAS_PROPERTY. */
+  value?: unknown;
+  /** Upper bound, BETWEEN only. */
+  highValue?: unknown;
+}
+
+export interface FilterGroupNode {
+  type: "group";
+  operator: FilterGroupOperator;
+  filters: FilterNode[];
+}
+
+export type FilterNode = FilterConditionNode | FilterGroupNode;
+
+export interface FilterBuilderLabels {
+  addFilter?: string;
+  addGroup?: string;
+  /** Screen-reader text on the condition row's remove (x) icon button. */
+  remove?: string;
+  /** Screen-reader text on the group header's delete (trash) icon button. */
+  removeGroup?: string;
+  /** Screen-reader text on the group header's clone (copy) icon button. */
+  cloneGroup?: string;
+  /** Group heading prefix — rendered as "Group 1", "Group 2", … */
+  group?: string;
+  and?: string;
+  or?: string;
+  property?: string;
+  operator?: string;
+  value?: string;
+  values?: string;
+  between?: string;
+  empty?: string;
+  true?: string;
+  false?: string;
+}
+
+export interface FilterValidationError {
+  path: FilterTreePath;
+  message: string;
+}
+
+export interface FilterValidationResult {
+  valid: boolean;
+  errors: FilterValidationError[];
+}
+
+export interface FilterCrmSearchFilter {
+  propertyName: string;
+  operator: FilterOperator;
+  value?: string | number | boolean;
+  highValue?: string | number | boolean;
+  values?: Array<string | number | boolean>;
+}
+
+export interface FilterCrmSearchFilterGroups {
+  filterGroups: Array<{ filters: FilterCrmSearchFilter[] }>;
+}
+
+export interface FilterToCrmSearchOptions {
+  /** Max filterGroups after DNF expansion (default 5, the CRM search limit). */
+  maxGroups?: number;
+  /** Max filters per filterGroup (default 6). */
+  maxFiltersPerGroup?: number;
+  /** Max filters across all groups (default 18). */
+  maxTotalFilters?: number;
+  /** Set false to skip limit checks (default true). */
+  enforceLimits?: boolean;
+  /** Set false to pass values through without DateInput→epoch-ms / boolean→string coercion (default true). */
+  coerceValues?: boolean;
+}
+
+export interface FilterConditionToCrmOptions {
+  coerceValues?: boolean;
+}
+
+export interface FilterRemoveOptions {
+  /** Also remove ancestor groups left empty by the removal (root is never pruned). */
+  pruneEmptyGroups?: boolean;
+}
+
+export interface FilterBuilderProps {
+  properties: FilterProperty[];
+  /** Controlled tree value. */
+  value?: FilterGroupNode | null;
+  /** Initial tree for uncontrolled mode. */
+  defaultValue?: FilterGroupNode | null;
+  onChange?: (tree: FilterGroupNode) => void;
+  /** Max group nesting depth; root counts as 1 (default 2). */
+  maxDepth?: number;
+  labels?: FilterBuilderLabels;
+  /** Per-operator label overrides for the operator dropdowns. */
+  operatorLabels?: Partial<Record<FilterOperator, string>>;
+  readOnly?: boolean;
+  /** Prefix for native input `name`s; set when rendering two builders on one surface. */
+  namePrefix?: string;
+  /** Remaining props are spread onto the root Flex. */
+  [key: string]: unknown;
+}
+
+export declare const FILTER_OPERATORS: Record<FilterPropertyType, FilterOperator[]>;
+
+export declare function getOperatorOptions(
+  type?: FilterPropertyType | string,
+  labelOverrides?: Partial<Record<FilterOperator, string>>
+): Array<{ label: string; value: FilterOperator }>;
+
+export declare function operatorExpectsValue(operator?: string): boolean;
+export declare function operatorExpectsHighValue(operator?: string): boolean;
+export declare function operatorExpectsValues(operator?: string): boolean;
+
+export declare function isGroupNode(node: unknown): node is FilterGroupNode;
+export declare function isConditionNode(node: unknown): node is FilterConditionNode;
+
+export declare function createCondition(
+  property?: string,
+  operator?: FilterOperator | "",
+  value?: unknown,
+  highValue?: unknown
+): FilterConditionNode;
+
+export declare function createGroup(
+  operator?: FilterGroupOperator,
+  filters?: FilterNode[]
+): FilterGroupNode;
+
+export declare function getNodeAtPath(tree: FilterNode, path: FilterTreePath): FilterNode | undefined;
+
+export declare function addFilter(
+  tree: FilterGroupNode,
+  path: FilterTreePath,
+  node: FilterNode
+): FilterGroupNode;
+
+export declare function updateFilter(
+  tree: FilterGroupNode,
+  path: FilterTreePath,
+  patch: Partial<FilterConditionNode> | Partial<FilterGroupNode> | ((node: FilterNode) => FilterNode)
+): FilterGroupNode;
+
+export declare function removeFilter(
+  tree: FilterGroupNode,
+  path: FilterTreePath,
+  options?: FilterRemoveOptions
+): FilterGroupNode;
+
+export declare function duplicateFilter(
+  tree: FilterGroupNode,
+  path: FilterTreePath
+): FilterGroupNode;
+
+export declare function countConditions(node: FilterNode): number;
+
+export declare function changeConditionProperty(
+  condition: FilterConditionNode,
+  property: FilterProperty | string
+): FilterConditionNode;
+
+export declare function changeConditionOperator(
+  condition: FilterConditionNode,
+  operator: FilterOperator | ""
+): FilterConditionNode;
+
+export declare function validateTree(
+  tree: FilterNode,
+  properties?: FilterProperty[]
+): FilterValidationResult;
+
+export declare function conditionToCrmFilter(
+  condition: FilterConditionNode,
+  options?: FilterConditionToCrmOptions
+): FilterCrmSearchFilter;
+
+export declare function toCrmSearchFilterGroups(
+  tree: FilterGroupNode,
+  options?: FilterToCrmSearchOptions
+): FilterCrmSearchFilterGroups;
+
+export declare function FilterBuilder(props: FilterBuilderProps): ReactNode;