hs-uix 2.1.1 → 2.2.0

package/experimental.d.ts

@@ -0,0 +1 @@
+export * from "./src/experimental/index";

package/filter.d.ts

@@ -0,0 +1 @@
+export * from "./src/filter/index";

package/index.d.ts

@@ -1,12 +1,17 @@
 // Each component module prefixes its type names (DataTable*, Kanban*, Feed*,
-// Calendar*, FormBuilder*) and its value exports are unique, so `export *` is
-// collision-free and keeps this root barrel automatically in sync with every
-// type each component declares — no hand-maintained list to fall out of date.
+// Calendar*, FormBuilder*, and Filter*) and its value exports are unique, so
+// `export *` is collision-free and keeps this root barrel automatically in
+// sync with every type each component declares — no hand-maintained list to
+// fall out of date.
 export * from "./src/datatable/index";
 export * from "./src/kanban/index";
 export * from "./src/feed/index";
 export * from "./src/calendar/index";
 export * from "./src/form/index";
+export * from "./src/filter/index";
+// safe prefixes everything with Safe* / catalog-style ALL_CAPS names, so it's
+// also collision-free under export *.
+export * from "./src/safe/index";
 
 export {
   ActiveFilterChips,
@@ -16,10 +21,20 @@ export {
   CollectionFilterControl,
   CollectionSortSelect,
   CollectionToolbar,
+  compareHsDateValues,
   CrmLookupSelect,
+  CrmRecordPicker,
+  DATE_FILTER_OPERATORS,
+  DATE_RANGE_CUSTOM_VALUE,
+  DATE_ROLLING_UNIT_OPTIONS,
+  DateRangePicker,
   formatCollectionCount,
+  isValidDateRange,
+  presetToRange,
+  toHsDateValue,
   KeyValueList,
   SectionHeader,
+  SKELETON_FILL,
   Spinner,
   SPINNERS,
   SPINNER_NAMES,
@@ -55,6 +70,7 @@ export {
   DEFAULT_SVG_FONT_WEIGHT,
 } from "./common-components";
 export {
+  applyPatches,
   buildActiveFilterChips,
   buildCrmSearchConfig,
   buildOptions,
@@ -89,6 +105,8 @@ export {
 export type {
   AutoTagOptions,
   AutoTagVariant,
+  JsonPatchOp,
+  JsonPatchOperation,
   AutoStatusTagOptions,
   AutoStatusTagVariant,
   StatusTagSortComparatorOptions,
@@ -124,8 +142,32 @@ export type {
   CollectionSortSelectProps,
   CollectionToolbarProps,
   CrmLookupSelectProps,
+  CrmRecordPickerCreateConfig,
+  CrmRecordPickerCreateOptionRules,
+  CrmRecordPickerFieldAccessor,
+  CrmRecordPickerId,
+  CrmRecordPickerOption,
+  CrmRecordPickerOptionConfig,
+  CrmRecordPickerProps,
+  CrmRecordPickerRecord,
+  CrmRecordPickerSelection,
+  CrmRecordPickerValue,
   DateDirectionLabels,
   DatePresetOption,
+  DateRangePickerChangeMeta,
+  DateRangePickerDateValue,
+  DateRangePickerExplicitRangeValue,
+  DateRangePickerOperator,
+  DateRangePickerPresetOption,
+  DateRangePickerPresetValue,
+  DateRangePickerPresenceValue,
+  DateRangePickerProps,
+  DateRangePickerRangeValue,
+  DateRangePickerRollingDirection,
+  DateRangePickerRollingUnit,
+  DateRangePickerRollingValue,
+  DateRangePickerSingleDateValue,
+  DateRangePickerValue,
   KeyValueListItem,
   KeyValueListProps,
   SectionHeaderProps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hs-uix",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Production-ready UI components for HubSpot UI Extensions — DataTable, FormBuilder, and more",
   "license": "MIT",
   "main": "./dist/index.js",
@@ -37,6 +37,16 @@
       "import": "./dist/calendar.mjs",
       "require": "./dist/calendar.js"
     },
+    "./filter": {
+      "types": "./filter.d.ts",
+      "import": "./dist/filter.mjs",
+      "require": "./dist/filter.js"
+    },
+    "./experimental": {
+      "types": "./experimental.d.ts",
+      "import": "./dist/experimental.mjs",
+      "require": "./dist/experimental.js"
+    },
     "./common-components": {
       "types": "./common-components.d.ts",
       "import": "./dist/common-components.mjs",
@@ -46,6 +56,11 @@
       "types": "./utils.d.ts",
       "import": "./dist/utils.mjs",
       "require": "./dist/utils.js"
+    },
+    "./safe": {
+      "types": "./safe.d.ts",
+      "import": "./dist/safe.mjs",
+      "require": "./dist/safe.js"
     }
   },
   "files": [
@@ -56,8 +71,11 @@
     "kanban.d.ts",
     "feed.d.ts",
     "calendar.d.ts",
+    "filter.d.ts",
+    "experimental.d.ts",
     "common-components.d.ts",
     "utils.d.ts",
+    "safe.d.ts",
     "src/**/*.d.ts",
     "README.md"
   ],

package/safe.d.ts

@@ -0,0 +1 @@
+export * from "./src/safe/index";

package/src/calendar/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/hs-uix)](https://www.npmjs.com/package/hs-uix)
 [![license](https://img.shields.io/npm/l/hs-uix)](https://github.com/05bmckay/hs-uix/blob/main/LICENSE)
 
-A presentational calendar surface for HubSpot UI Extensions. Hand it an array of records plus an `eventFields` map and it renders a **Month**, **Week**, **Day**, or **Agenda** view with a Today / ‹ › / view-switcher toolbar, optional search + filters, and click-to-open event overlays (Popover, Modal, or Panel). Like Kanban and Feed, the calendar is data-driven and presentational — the caller owns fetching.
+A presentational calendar surface for HubSpot UI Extensions. Hand it an array of records plus an `eventFields` map and it renders a **Month**, **Week**, **Day**, **Agenda**, or **Resource** view with a Today / ‹ › / view-switcher toolbar, optional search + filters, click-to-open event overlays (Popover, Modal, or Panel), and an optional drag-free **reschedule** affordance. Like Kanban and Feed, the calendar is data-driven and presentational — the caller owns fetching *and persisting*: even a reschedule only **emits** the new `{ start, end }`, it never mutates the events you passed in.
 
 ```jsx
 import { Calendar } from "hs-uix/calendar";
@@ -36,7 +36,8 @@ const fields = {
 
 ## Features
 
-- Four stable views behind a `Select` switcher: **Month** (7-column day grid), **Week** / **Day** (hour-row time grid), and **Agenda** (day-grouped list)
+- Five views behind a `Select` switcher: **Month** (7-column day grid), **Week** / **Day** (hour-row time grid), **Agenda** (day-grouped list), and **Resource** (rows = owners/rooms/teams × the focused week's days — only offered when `resources` / `resourceField` is provided)
+- **Drag-free reschedule** (the platform has no drag-and-drop): `rescheduleOptions` adds preset buttons ("+1 hour", "+1 day", "Next week", custom shifts or accessors) plus a "Pick date" `DateInput` to the event-detail overlay; `onEventReschedule` emits the shifted `{ start, end }` with the event's duration preserved (DST-safe) — you persist, the Calendar never moves events itself
 - Controlled or uncontrolled `view` and `focusedDate`, with `onViewChange` / `onNavigate`
 - Date coercion for every shape a HubSpot field arrives in: `Date`, epoch ms (number **or** string), ISO string, or a `DateInput` value object (`{ year, month, date }`, 0-indexed month) — date-only strings are parsed as **local** midnight so events never land a day early
 - Multi-day events render across each day they touch; timed events show their start time
@@ -73,6 +74,7 @@ Requires `@hubspot/ui-extensions` >= 0.14.0 and `react` >= 18.0.0 as peer depend
 | `week` | An hour-row time grid for the focused week, plus an all-day band. | ± 1 week |
 | `day` | The single-day hour schedule (the same grid as week, one wide column) with an all-day band and a "now" current-hour marker. | ± 1 day |
 | `agenda` | The focused week's events grouped under day headers (time · title · owner rows). | ± 1 week |
+| `resource` | Rows = resources (owners / rooms / teams), columns = the focused week's days. Each cell stacks the same chips as a month cell, with the same "+N more" overflow popover. **Only joins the switcher when `resources` or `resourceField` is provided.** | ± 1 week |
 
 The view switcher is a `Select` (not `Tabs`) because the platform caches `Tabs` bodies and they won't re-render on data changes.
 
@@ -130,6 +132,67 @@ A rep's week in an hour-row grid, Monday start, 8 AM–6 PM, opening a Panel per
 />
 ```
 
+### Resource lanes (owners / rooms / teams)
+
+Rows = resources, columns = the focused week. `resourceField` (a key or accessor on **your** record) lanes each event; events whose id matches no declared resource get an appended derived lane (labeled from `resourceLabels` or the raw id), and events with **no** id land in a trailing "Unassigned" lane.
+
+```jsx
+<Calendar
+  events={meetings}
+  eventFields={{ id: "id", start: "start", end: "end", title: "title", color: "color" }}
+  defaultView="resource"
+  resources={[
+    { id: "u1", label: "Ana Souza" },
+    { id: "u2", label: "Ben Liu" },
+    { id: "room-a", label: "Conference Room A" },
+  ]}
+  resourceField="ownerId"            // or (meeting) => meeting.owner?.id
+  resourceLabels={{ "u3": "Cara Diaz" }} // labels for derived (undeclared) lanes
+  showUnassignedLane                 // default true; false omits id-less events
+  weekStartsOn={1}
+  hideWeekends
+/>
+```
+
+- Declared `resources` always render, in order, even with zero events — so a free room reads as *free*.
+- Ids are matched by `String(id)`, so a numeric `7` and a string `"7"` are the same lane.
+- The "Unassigned" lane renders only when it has events; relabel it via `labels.unassigned`.
+- The view appears in the switcher **only** when `resources` or `resourceField` is provided.
+
+### Drag-free reschedule
+
+The platform has no drag-and-drop, so rescheduling is explicit: `rescheduleOptions` adds preset buttons and a "Pick date" `DateInput` to the event-detail overlay. The Calendar computes the new range — **both** endpoints shifted, duration preserved — and **emits** it. You persist and pass updated `events` back in; the Calendar never mutates its own events (the same presentational contract as Kanban).
+
+```jsx
+// true → "+1 hour" / "+1 day" / "Next week" + the date picker:
+<Calendar
+  events={tasks}
+  eventFields={fields}
+  rescheduleOptions
+  onEventReschedule={async (raw, { start, end }, event) => {
+    await patchTask(raw.id, { start, end }); // you persist…
+    refetch();                               // …and feed updated events back in
+  }}
+/>
+
+// Custom presets — relative shifts, or accessors returning the new start:
+<Calendar
+  events={tasks}
+  eventFields={fields}
+  overlayMode="panel" // roomier home for the picker than the experimental popover
+  rescheduleOptions={[
+    { label: "+30 min", shift: { minutes: 30 } },
+    { label: "+2 days", shift: { days: 2 } },
+    { label: "Next sprint", shift: (event) => nextSprintStart(event.raw) },
+  ]}
+  onEventReschedule={persistRange}
+/>
+```
+
+DST semantics (tested against America/Chicago): day/week shifts are **calendar** shifts — a 9 AM meeting moved across the spring-forward weekend is still 9 AM, and a midnight-to-midnight all-day span stays anchored to midnight; hour/minute shifts are **exact clock durations** ("+1 hour" always moves the instant 60 real minutes). "Pick date…" keeps the event's original time-of-day. When the timezone layer is engaged, the math runs on your **original** instants (`event.sourceStart` / `sourceEnd`), not the converted display dates, so the emitted range stays in your data's time domain.
+
+A custom `renderEventDetail` replaces the whole overlay body, reschedule section included — wire your own buttons there if you override it.
+
 ### Server-driven data
 
 Fetch only the visible range. `onRangeChange` fires on mount and on every navigation / view change.
@@ -223,7 +286,7 @@ How it works: each event instant is converted to a "wall-clock" `Date` in the ac
 | `view` | `CalendarView` | — | Controlled current view. |
 | `defaultView` | `CalendarView` | `"month"` | Uncontrolled initial view. |
 | `onViewChange` | `(view) => void` | — | Fires when the view changes. |
-| `views` | `CalendarView[]` | all | Which views to expose in the switcher (month / week / day / agenda). |
+| `views` | `CalendarView[]` | all | Which views to expose in the switcher (month / week / day / agenda / resource — resource still requires `resources`/`resourceField`). |
 | `focusedDate` | `CalendarDateInput` | — | Controlled focused date. |
 | `defaultFocusedDate` | `CalendarDateInput` | today | Uncontrolled initial date. |
 | `onNavigate` | `(date, { view }) => void` | — | Fires on prev / next / today. |
@@ -234,6 +297,12 @@ How it works: each event instant is converted to a "wall-clock" `Date` in the ac
 | `monthEventMaxChars` | `number` | per-style, from column width | Max characters for a month-cell label before "…". Labels are truncated up front so every token truncates consistently (the tag's native truncation measures unreliably while the table is still sizing columns). |
 | `dayStartHour` | `number` | `8` | First hour row in week/day (0–23). |
 | `dayEndHour` | `number` | `20` | Last hour row in week/day (0–23). |
+| `resources` | `(id \| { id, label? })[]` | — | Declared resource lanes, in order. Always render, even when empty. Providing this (or `resourceField`) adds the `resource` view to the switcher. |
+| `resourceField` | `string \| (event) => id` | — | How to read an event's resource id from your record. `null` / `""` ⇒ unassigned. Ids matched by `String(id)`; undeclared ids get appended derived lanes. |
+| `resourceLabels` | `{ [id]: label }` | — | Labels for resources declared without one and for derived lanes. Falls back to `String(id)`. |
+| `showUnassignedLane` | `boolean` | `true` | Trailing "Unassigned" lane for id-less events (rendered only when non-empty). `false` omits those events from the resource view. |
+| `rescheduleOptions` | `true \| (option \| fn)[]` | — | Adds reschedule presets + a "Pick date" `DateInput` to the event overlay. `true` ⇒ "+1 hour" / "+1 day" / "Next week". Entries: `{ label, shift: { days?, weeks?, hours?, minutes? } }`, `{ label, shift: (event) => newStart }`, or a bare `(event) => newStart`. |
+| `onEventReschedule` | `(raw, { start, end }, event) => void` | — | Fires when a reschedule affordance is used. Both endpoints shifted, duration preserved (DST-safe), computed from your original instants. **You persist** — the Calendar never mutates its events. |
 | `timeZone` | `string` | — | Controlled IANA zone (e.g. `"America/Chicago"`). Setting it opts into the tz layer; all times/placement/grouping resolve here. |
 | `defaultTimeZone` | `string` | — | Uncontrolled initial zone. Opts into the tz layer; the layer itself starts at `"UTC"` if engaged without this. |
 | `onTimeZoneChange` | `(tz) => void` | — | Fires when the zone changes. |
@@ -277,10 +346,10 @@ How it works: each event instant is converted to a "wall-clock" `Date` in the ac
 Render callbacks (`renderEventDetail`, `onEventClick`, `renderDayCell`) receive the normalized event:
 
 ```ts
-{ key, id, start: Date | null, end: Date | null, title, subtitle, color, href, raw }
+{ key, id, start: Date | null, end: Date | null, sourceStart, sourceEnd, title, subtitle, color, href, raw }
 ```
 
-`raw` is your original record.
+`raw` is your original record. `start` / `end` are the dates the calendar *displays* (wall-clock converted when the timezone layer is engaged); `sourceStart` / `sourceEnd` are your **original** instants, which is what the reschedule math runs on.
 
 ---
 

package/src/calendar/index.d.ts

@@ -4,7 +4,7 @@ import type { ReactElement, ReactNode } from "react";
 // Primitives
 // ---------------------------------------------------------------------------
 
-export type CalendarView = "month" | "week" | "day" | "agenda";
+export type CalendarView = "month" | "week" | "day" | "agenda" | "resource";
 export type CalendarOverlayMode = "popover" | "modal" | "panel" | "none";
 export type CalendarFilterType = "select" | "multiselect" | "dateRange";
 
@@ -54,6 +54,12 @@ export interface CalendarNormalizedEvent<Event = Record<string, unknown>> {
   id: string | number | undefined;
   start: Date | null;
   end: Date | null;
+  /** The UN-converted start instant from your data (no timezone-layer wall-clock
+   * conversion). Reschedule math runs on this, so emitted dates stay in your
+   * data's time domain. */
+  sourceStart: Date | null;
+  /** The UN-converted end instant (mirrors `sourceStart` when the event has no end). */
+  sourceEnd: Date | null;
   title: ReactNode;
   subtitle: ReactNode;
   color: string | undefined;
@@ -61,6 +67,60 @@ export interface CalendarNormalizedEvent<Event = Record<string, unknown>> {
   raw: Event;
 }
 
+// ---------------------------------------------------------------------------
+// Resource / lane view
+// ---------------------------------------------------------------------------
+
+/** A declared resource lane: `{ id, label? }`, or a bare id. Declared lanes
+ * always render (in order), even with zero events. */
+export type CalendarResource =
+  | string
+  | number
+  | { id: string | number; label?: ReactNode };
+
+/** How to read an event's resource id: a key on the raw event, or an accessor.
+ * `null` / `undefined` / `""` mean unassigned. Ids are matched by `String(id)`. */
+export type CalendarResourceField<Event = Record<string, unknown>> =
+  | string
+  | ((event: Event) => string | number | null | undefined);
+
+// ---------------------------------------------------------------------------
+// Drag-free reschedule
+// ---------------------------------------------------------------------------
+
+/** A relative shift. Days/weeks are CALENDAR shifts (wall-clock time-of-day
+ * preserved on both endpoints, DST-safe); hours/minutes are exact clock
+ * durations. */
+export interface CalendarRescheduleShift {
+  days?: number;
+  weeks?: number;
+  hours?: number;
+  minutes?: number;
+}
+
+/** One reschedule affordance: a labeled relative shift, a labeled accessor
+ * returning the new start (any `CalendarDateInput` shape), or a bare accessor
+ * (labeled from `fn.name`, falling back to "Reschedule"). */
+export type CalendarRescheduleOption<Event = Record<string, unknown>> =
+  | {
+      label: string;
+      shift:
+        | CalendarRescheduleShift
+        | ((event: CalendarNormalizedEvent<Event>) => CalendarDateInput | null | undefined);
+    }
+  | {
+      label: string;
+      getStart: (event: CalendarNormalizedEvent<Event>) => CalendarDateInput | null | undefined;
+    }
+  | ((event: CalendarNormalizedEvent<Event>) => CalendarDateInput | null | undefined);
+
+/** The new range emitted by `onEventReschedule` — BOTH endpoints shifted, the
+ * event's duration/shape preserved (DST-safe). */
+export interface CalendarRescheduleRange {
+  start: Date;
+  end: Date;
+}
+
 export interface CalendarRange {
   start: Date;
   end: Date;
@@ -101,6 +161,10 @@ export interface CalendarLabels {
   errorMessage?: string;
   open?: string;
   allDay?: string;
+  reschedule?: string;
+  pickDate?: string;
+  unassigned?: string;
+  resource?: string;
 }
 
 export interface CalendarProps<Event = Record<string, unknown>> {
@@ -145,6 +209,36 @@ export interface CalendarProps<Event = Record<string, unknown>> {
   /** Last hour row in week/day view (0–23). Default 20. */
   dayEndHour?: number;
 
+  // Resource / lane view — rows = resources, columns = the focused week's days.
+  // The "resource" view only joins the view switcher when `resources` or
+  // `resourceField` is provided.
+  /** Declared lanes, in display order. Always render, even when empty. */
+  resources?: CalendarResource[];
+  /** How to read an event's resource id (key on the raw event, or accessor).
+   * Ids found in the data but never declared get appended derived lanes. */
+  resourceField?: CalendarResourceField<Event>;
+  /** `{ [id]: label }` lookup for resources declared without a label and for
+   * derived lanes. Falls back to `String(id)`. */
+  resourceLabels?: Record<string, ReactNode>;
+  /** Append a trailing "Unassigned" lane for events with no resource id
+   * (rendered only when non-empty). When false those events are omitted from
+   * the resource view. Default `true`. */
+  showUnassignedLane?: boolean;
+
+  // Drag-free reschedule — adds preset buttons + a "Pick date" DateInput to the
+  // default event-detail overlay. `true` = "+1 hour" / "+1 day" / "Next week".
+  // The Calendar EMITS the shifted range and never mutates its own events.
+  rescheduleOptions?: true | CalendarRescheduleOption<Event>[];
+  /** Fires when a reschedule affordance is used. `range` has BOTH endpoints
+   * shifted (duration preserved, DST-safe), computed from the event's original
+   * (`sourceStart`/`sourceEnd`) instants. Persist it and pass updated `events`
+   * back in — the Calendar will not move the event on its own. */
+  onEventReschedule?: (
+    raw: Event,
+    range: CalendarRescheduleRange,
+    event: CalendarNormalizedEvent<Event>
+  ) => void;
+
   // Timezone — OFF by default: with none of these props set, events render exactly
   // as provided (no conversion, browser-local). Opt in via `timeZone`,
   // `defaultTimeZone`, or `showTimeZoneSelect` and all times, grid placement, and

package/src/common-components/README.md

@@ -9,7 +9,9 @@ Reusable UI wrappers built on top of HubSpot UI Extensions primitives.
 - `AvatarStack` — overlapping circular avatars (letters or image URLs)
 - `Icon` — superset of HubSpot's native `<Icon>`: custom glyphs, any CSS color, pixel sizes
 - `CrmLookupSelect` — CRM-backed `Select` / `MultiSelect` with live, debounced search
+- `CrmRecordPicker` — multi-association record picker: search CRM records, select many, get ids AND records back, optional inline create
 - `CollectionToolbar`, `CollectionFilterControl`, `ActiveFilterChips`, `CollectionSortSelect`, `CollectionCount` — shared search/filter/sort/count primitives used by DataTable, Kanban, Feed, and Calendar
+- `DateRangePicker` — HubSpot-style date filter value control with preset, static-date, rolling, range, and presence operator layouts
 - `SectionHeader` — title + optional description row
 - `KeyValueList` — vertical list of label/value rows
 - `StyledText` — SVG-rendered text with rotation, custom colors, pill backgrounds
@@ -21,6 +23,7 @@ Plus utilities + constants:
 - `ICONS`, `ICON_NAMES`, `NATIVE_ICON_NAME_LIST`, `svgToIconEntry` — the custom icon registry and helpers behind `Icon`
 - `SPINNERS`, `SPINNER_NAMES` — spinner presets and registry
 - `HS_DATE_PRESETS`, `HS_DATE_DIRECTION_LABELS` — HubSpot's native quick-date preset list
+- `presetToRange`, `toHsDateValue`, `compareHsDateValues`, `isValidDateRange`, `DATE_FILTER_OPERATORS`, `DATE_ROLLING_UNIT_OPTIONS`, `DATE_RANGE_CUSTOM_VALUE` — date-filter constants and math behind `DateRangePicker`
 - `HS_FONT_FAMILY`, `HS_TEXT_COLOR`, `HS_SUBTLE_BG`, `HS_MUTED_TEXT`, `HS_NEUTRAL_CHIP` — style constants matching native HubSpot CSS
 
 ## Purpose
@@ -38,8 +41,10 @@ import {
   AvatarStack,
   Icon,
   CrmLookupSelect,
+  CrmRecordPicker,
   CollectionToolbar,
   CollectionSortSelect,
+  DateRangePicker,
   SectionHeader,
   KeyValueList,
   StyledText,
@@ -128,6 +133,76 @@ const activeChips = buildActiveFilterChips(filters, filterValues);
 
 ---
 
+## DateRangePicker
+
+HubSpot's CRM filter editor changes the value control based on the selected date operator. `DateRangePicker` follows that pattern: `is` renders a quick-preset `Select`, static comparisons render one date input, rolling comparisons render a number plus unit dropdown, `is between` renders two date inputs with a `to` separator, and known / unknown render no value input. Its `onChange` payload preserves the operator so server-side CRM search builders can distinguish preset, static-date, rolling, explicit-range, and presence filters.
+
+```jsx
+import { DateRangePicker } from "hs-uix/common-components";
+
+const [range, setRange] = useState({
+  operator: "InRollingDateRange",
+  preset: "today",
+});
+
+<DateRangePicker
+  label="Close date"
+  name="close-date"
+  value={range}
+  onChange={setRange}
+  clearable
+/>
+```
+
+Features:
+
+- **HubSpot-style operator values.** The built-in operators are `InRollingDateRange` (`is`), `Equal` (`is equal to`), `BeforeDateStaticOrDynamic` (`is before`), `AfterDateStaticOrDynamic` (`is after`), `InRange` (`is between`), `GreaterRolling` (`is more than`), `LessRolling` (`is less than`), `Known` (`is known`), and `NotKnown` (`is unknown`).
+- **Presets can still resolve to dates.** Picking "Last quarter" includes the computed `{ from, to }` bounds in `meta.range` via `presetToRange`.
+- **Compact date inputs by default.** Date inputs use the same no-label treatment as `FilterBuilder` for CRM-filter-style rows. Set `showDateLabels` to `true` to render labels.
+- **Only valid explicit ranges escape.** If an `InRange` edit would make `from > to`, the invalid half is held locally with an error message and `onChange` is NOT called until the user fixes either side.
+- **Controlled or uncontrolled** via `value` / `defaultValue` / `onChange`.
+- **Plain `{ from, to }` compatibility.** Passing the older range shape is treated as `operator: "InRange"`.
+
+| Prop | Type | Default | Notes |
+| ---- | ---- | ------- | ----- |
+| `value` | operator value | — | Controlled value. Use `{ operator: "InRollingDateRange", preset }`, `{ operator: "Equal", date }`, `{ operator: "BeforeDateStaticOrDynamic", date }`, `{ operator: "AfterDateStaticOrDynamic", date }`, `{ operator: "GreaterRolling", amount, unit, direction }`, `{ operator: "LessRolling", amount, unit, direction }`, `{ operator: "InRange", from, to }`, `{ operator: "Known" }`, `{ operator: "NotKnown" }`, or legacy `{ from, to }`. |
+| `defaultValue` | operator value | `{ operator: "InRollingDateRange", preset: "today" }` | Initial value for uncontrolled usage. |
+| `onChange` | `(value, meta) => void` | — | Fires with the normalized operator value. `meta` includes `{ operator, field?, preset, range? }`. |
+| `label` | `ReactNode` | — | Group label rendered above the control. |
+| `name` | `string` | `"date-range"` | Base for inner input names. |
+| `field` / `defaultField` | `string` | — | Controlled or uncontrolled selected CRM property when `showFieldSelect` is enabled. |
+| `onFieldChange` | `(field) => void` | — | Fires when the field dropdown changes. |
+| `showFieldSelect` | `boolean` | `false` | Render a CRM property dropdown before the operator and value controls. |
+| `fieldOptions` | array | `[]` | Options for the field dropdown, shaped like `{ label, value }`. |
+| `operator` / `defaultOperator` | date operator | — / `"InRollingDateRange"` | Controlled or uncontrolled operator. |
+| `showOperatorSelect` | `boolean` | `true` | Render the operator dropdown. |
+| `operatorOptions` | array | `DATE_FILTER_OPERATORS` | Override operator labels or available operators. |
+| `presets` | `boolean \| array` | `true` | `true` = `HS_DATE_PRESETS`; `false` = no preset Select; or a custom `{ label, value, getRange? }` array — `value` is a `presetToRange` key, or supply `getRange(now)` for fully custom presets. |
+| `rollingUnitOptions` | array | `DATE_ROLLING_UNIT_OPTIONS` | Options for the rolling amount unit/direction dropdown. |
+| `direction` | `"row" \| "column"` | `"row"` | Layout direction for the operator/value controls. |
+| `clearable` | `boolean` | `false` | Show a Clear link when the current operator has a non-empty value. |
+| `min` / `max` | date object | — | Passed through to both `DateInput`s. |
+| `fromLabel` / `toLabel` / `dateLabel` | `string` | `"Start date"` / `"End date"` / `"Date"` | Date input labels used when `showDateLabels` is true. |
+| `showDateLabels` | `boolean` | `false` | Render DateInput labels visibly instead of the compact no-label CRM-filter layout. |
+| `format` | `string` | `"medium"` | `DateInput` display format. |
+| `presetPlaceholder` | `string` | `"Enter value"` | Placeholder for the preset Select. |
+| `customPresetLabel` | `string` | `"Custom"` | Label for the appended Custom option. |
+| `clearLabel` | `ReactNode` | `"Clear"` | Clear link text. |
+| `invalidRangeMessage` | `string` | `"Start date must be on or before end date"` | Shown on the held invalid input. |
+| `readOnly` | `boolean` | `false` | Pass-through to all inner controls (also hides the Clear link). |
+| `gap` | `string` | `"xs"` row / `"sm"` column | Flex gap between controls. |
+| `gridColumnWidth` | `number` | `260` | Minimum column width for the field-enabled flexible AutoGrid layout. |
+
+### Pure helpers (`dateRangePresets.js`)
+
+- `presetToRange(presetKey, now?)` — translate an `HS_DATE_PRESETS` key into `{ from, to }` HubSpot date objects. Weeks run Sunday–Saturday; `7d`/`30d`/`90d` are rolling windows ending (and including) today; months/quarters/years are full calendar units. Returns `null` for unknown/`"custom"`/empty keys. Pass a fixed `now` Date for determinism.
+- `toHsDateValue(date)` — JS `Date` → `{ year, month, date }` (or `null`).
+- `compareHsDateValues(a, b)` — sort-style comparator; `null` sides compare as `0`.
+- `isValidDateRange(range)` — `true` when open-ended or `from <= to`.
+- `DATE_RANGE_CUSTOM_VALUE` — the `"custom"` sentinel used by the preset Select.
+
+---
+
 ## AvatarStack
 
 Overlapping circular avatars rendered as a single SVG via `<Image>`. Letters get colored circles with white initials; `http(s):` or `data:image/...` URIs get circular-clipped images. Extras beyond `maxVisible` collapse into a neutral `+N` chip.
@@ -344,6 +419,69 @@ import { CrmLookupSelect } from "hs-uix/common-components";
 
 ---
 
+## CrmRecordPicker
+
+The association picker. `CrmLookupSelect` answers "pick ONE record" — `CrmRecordPicker` answers "pick MANY, give me the records back, and let the user create one inline". Use it whenever you're managing a record's associations (contacts on a deal, companies on a ticket) or any selection where you need the full record objects, not just ids.
+
+What you get over a hand-rolled `MultiSelect` + `useCrmSearchOptions`:
+
+- **Selections never vanish.** A selected record stays visible as an option even when the live search page no longer contains it.
+- **ids AND records.** `onChange(ids, records)` hands back both — no second fetch to resolve what the user picked. `value` accepts ids, records, or a mix.
+- **`max` enforcement.** Picks beyond the cap are rejected (the existing selection is kept), and the create option hides at the cap.
+- **Guarded inline create.** With `allowCreate`, a settled search with no exact label match appends `Create "<term>"`; choosing it awaits `onCreate(term)`, selects the result, and merges it into the options. Double-fires are blocked while the create call is pending.
+
+```jsx
+import { CrmRecordPicker } from "hs-uix/common-components";
+
+<CrmRecordPicker
+  objectType="contact"
+  properties={["firstname", "lastname", "email"]}
+  label="Associated contacts"
+  labelField={(r) => `${r.firstname} ${r.lastname}`}
+  descriptionField="email"
+  value={contactIds}
+  onChange={(ids, records) => {
+    setContactIds(ids);
+    syncAssociations(records);
+  }}
+  max={10}
+  allowCreate={{
+    label: (term) => `Create contact "${term}"`,
+    onCreate: async (term) => {
+      const created = await hubspot.serverless("createContact", { parameters: { email: term } });
+      return created; // record object or its id — both work
+    },
+  }}
+/>
+```
+
+Single-select mode (`multi={false}`) behaves like `CrmLookupSelect` but keeps this component's richer API: `onChange(id, record)` with a scalar id (or `null` when cleared), plus `allowCreate` — which `CrmLookupSelect` doesn't have.
+
+### Props
+
+| Prop | Type | Default | Notes |
+| ---- | ---- | ------- | ----- |
+| `objectType` | string | — | CRM object to search (`"contact"`, `"company"`, `"deal"`, or any object type id/name). |
+| `properties` | `string[]` | — | Properties to fetch (drive labels/descriptions). |
+| `labelField` | string \| `(record) => unknown` | — | Option label: dotted property path or accessor. Falls back to `name`, `properties.name`, then `fallbackLabel`. |
+| `descriptionField` | string \| `(record) => unknown` | — | Option description (omitted when empty). |
+| `value` / `defaultValue` | array of ids and/or records (scalar when `multi={false}`) | — | Controlled / uncontrolled selection. Record objects seed the id→record registry. |
+| `onChange` | `(ids, records) => void` | — | Multi: arrays. Single: scalar id (or `null`) + record (or `null`). Never-seen ids come back as `{ objectId: id }` stubs. |
+| `multi` | boolean | `true` | `MultiSelect` vs `Select`. |
+| `max` | number | — | Selection cap. The pick that would exceed it is rejected. |
+| `allowCreate` | `false` \| `{ label?, onCreate }` | `false` | `onCreate: async (term) => recordOrId`. `label` is a string or `(term) => string`; default `Create "<term>"`. |
+| `filterMap` | `(filters, params) => filterGroups` | — | Scope the search with full HubSpot CRM search syntax (e.g. restrict to a pipeline). |
+| `pageLength` | number | `20` | Results fetched per query. |
+| `debounce` / `minSearchLength` | number | `300` / `0` | Search tuning. |
+| `fallbackLabel` | string | `"Untitled record"` | Label for records whose `labelField` resolves empty. |
+| `onSearchChange` | `(query) => void` | — | Observe the live search input. |
+| `format` / `baseConfig` | object | — | Advanced passthroughs to the CRM search config. |
+| `label`, `name`, `placeholder`, `description`, `tooltip`, `required`, `readOnly`, `error`, `validationMessage`, `variant` | — | — | Standard field props forwarded to the native select; any other props are spread through too. |
+
+The pure decision logic (option merging, max enforcement, create-option rules, id↔record mapping) is exported from `recordPickerCore.js` — `mergePickerOptions`, `enforceSelectionMax`, `shouldShowCreateOption`, `makeCreateOption`, `splitCreateSelection`, `normalizeRecordSelection`, `mapIdsToRecords`, `getRecordId`, `upsertRecords`, `CREATE_OPTION_VALUE` — if you're building a custom picker UI on the same rules.
+
+---
+
 ## HS_DATE_PRESETS
 
 HubSpot's native quick-date preset list — matches the Create date dropdown on the Deals board. Use as the `options` for a `select` filter on Kanban / DataTable so consumers don't have to retype the list.
@@ -362,7 +500,7 @@ filters={[
 ]}
 ```
 
-The preset values are stable identifiers (`"today"`, `"7d"`, `"this_quarter"`, etc.) — it's up to the consumer to translate them into actual date bounds (via `filterFn` on the filter config or server-side in `onFilterChange`).
+The preset values are stable identifiers (`"today"`, `"7d"`, `"this_quarter"`, etc.). To translate them into actual date bounds, use `presetToRange(presetKey, now?)` from this module (see [DateRangePicker](#daterangepicker)) — or do it yourself via `filterFn` on the filter config / server-side in `onFilterChange`.
 
 Also exports `HS_DATE_DIRECTION_LABELS` (`{ asc: "Ascending", desc: "Descending" }`) for pairing with direction-specific sort UIs.
 
@@ -379,6 +517,7 @@ Raw style tokens used internally by `StyledText` and `AvatarStack` so they match
 | `HS_SUBTLE_BG` | `#F5F8FA` | Tag `variant="subtle"` background |
 | `HS_MUTED_TEXT` | `#7C98B6` | Secondary / microcopy gray |
 | `HS_NEUTRAL_CHIP` | `#CBD6E2` | Neutral chip background (`+N` overflow) |
+| `SKELETON_FILL` | `#DFE3EB` | Skeleton placeholder gray |
 | `HS_TAG_SUBTLE_BORDER` | — | Border color for subtle-variant tag pills |
 | `HS_TAG_TEXT_COLOR` | — | Text color inside tag pills |
 | `HS_TAG_FONT_SIZE` | — | Font size (px) for tag pill text |

package/src/datatable/README.md

@@ -1020,7 +1020,6 @@ These come from HubSpot UI Extensions itself, not DataTable:
 | No pixel widths | `TableCell` `width` only accepts `"min"`, `"max"`, or `"auto"`. Numeric pixel values are silently ignored by HubSpot. |
 | Input alignment | HubSpot input components (Input, NumberInput, CurrencyInput, etc.) ignore parent `text-align` CSS. DataTable strips `align` when inputs are visible so headers and cells stay consistent. |
 | No multi-column sort | Only one column can be sorted at a time. |
-| No row expansion | No expand/collapse for individual row detail views. Row grouping works, but per-row expansion does not. |
 | No export | No built-in CSV/Excel export. You'd need to implement this in a serverless function. |
 | Validation on select/toggle/checkbox | `editValidate` only shows error UI on text-based inputs (text, number, currency, textarea, stepper). Select, toggle, and checkbox commit immediately and don't show `validationMessage`. |
 
@@ -1031,7 +1030,6 @@ These come from HubSpot UI Extensions itself, not DataTable:
 Planned for future releases:
 
 - Column visibility toggle so users can show/hide columns
-- Expandable rows with detail content below each row
 - Click-to-copy on individual cell values
 - Conditional formatting to color-code cells based on value rules
 - Per-column filter dropdowns in the header row