hs-uix 2.1.1 → 2.2.0

package/README.md

@@ -26,6 +26,7 @@ import {
   CollectionToolbar,
 } from "hs-uix/common-components";
 import { CrmDataTable, CrmKanban, formatCurrency, formatDate } from "hs-uix/utils";
+import { SafeIcon, SafeEmptyState, SafeDataTable } from "hs-uix/safe";
 
 // or import everything from the root
 import { DataTable, FormBuilder, Kanban, Feed, Calendar, Icon } from "hs-uix";
@@ -43,8 +44,9 @@ Requires `react` >= 18.0.0 and `@hubspot/ui-extensions` >= 0.14.0 as peer depend
 | **Feed** | Activity feed / timeline with a standard item shape, date grouping, load-more pagination, and HubSpot-native item regions | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/feed/README.md) |
 | **Calendar** | Presentational month/week/day/agenda calendar with search, filters, date navigation, event overlays, and experimental Gantt view | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/calendar/README.md) |
 | **Common Components** | Thin visual wrappers and shared collection primitives — `Icon`, `AutoTag`, `AutoStatusTag`, `AvatarStack`, `CrmLookupSelect`, `CollectionToolbar`, `CollectionFilterControl`, `CollectionSortSelect`, `CollectionCount`, and more | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/common-components/README.md) |
+| **Safe wrappers** | Hardened drop-ins for failure-prone natives — `SafeIcon` (alias-repair + visible placeholder), `SafeEmptyState` (`imageName` fallback instead of a throw), `SafeStatisticsTrend`, `SafePopover` (auto-padding), and array-coercing `SafeDataTable` / `SafeSelect` / … that degrade to empty states instead of blanking the page | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/safe/README.md) |
 | **CRM data** | `CrmDataTable` / `CrmKanban` — batch-fetching, client-side-paginating CRM table & board, plus the `useCrmSearch*` hooks behind them | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/utils/README.md) |
-| **Utils** | Pure helpers for formatting, options, HubSpot value guards, tag-variant inference, collection filtering/searching, and active-filter chips | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/utils/README.md) |
+| **Utils** | Pure helpers for formatting, options, HubSpot value guards, tag-variant inference, collection filtering/searching, active-filter chips, and RFC 6902 JSON Patch applying (`applyPatches`) | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/utils/README.md) |
 
 ---
 

package/common-components.d.ts

@@ -60,6 +60,133 @@ export interface DateDirectionLabels {
   desc: string;
 }
 
+/** HubSpot DateInput value object — `month` is 0-indexed (0 = January). */
+export interface DateRangePickerDateValue {
+  year: number;
+  month: number;
+  date: number;
+}
+
+/** The explicit `is between` date range shape. */
+export interface DateRangePickerRangeValue {
+  from?: DateRangePickerDateValue | null;
+  to?: DateRangePickerDateValue | null;
+}
+
+export type DateRangePickerOperator =
+  | "InRollingDateRange"
+  | "Equal"
+  | "BeforeDateStaticOrDynamic"
+  | "AfterDateStaticOrDynamic"
+  | "InRange"
+  | "GreaterRolling"
+  | "LessRolling"
+  | "Known"
+  | "NotKnown";
+
+export type DateRangePickerRollingUnit = "day" | "week" | "month" | "year";
+export type DateRangePickerRollingDirection = "backward" | "forward";
+
+export interface DateRangePickerPresetValue {
+  operator: "InRollingDateRange";
+  preset?: string;
+}
+
+export interface DateRangePickerRollingValue {
+  operator: "GreaterRolling" | "LessRolling";
+  amount?: number;
+  unit?: DateRangePickerRollingUnit;
+  direction?: DateRangePickerRollingDirection;
+}
+
+export interface DateRangePickerSingleDateValue {
+  operator: "Equal" | "BeforeDateStaticOrDynamic" | "AfterDateStaticOrDynamic";
+  date?: DateRangePickerDateValue | null;
+}
+
+export interface DateRangePickerExplicitRangeValue extends DateRangePickerRangeValue {
+  operator: "InRange";
+}
+
+export interface DateRangePickerPresenceValue {
+  operator: "Known" | "NotKnown";
+}
+
+export type DateRangePickerValue =
+  | DateRangePickerRangeValue
+  | DateRangePickerPresetValue
+  | DateRangePickerSingleDateValue
+  | DateRangePickerRollingValue
+  | DateRangePickerExplicitRangeValue
+  | DateRangePickerPresenceValue;
+
+export interface DateRangePickerPresetOption {
+  label: string;
+  /** A preset key understood by presetToRange, or any key when getRange is given. */
+  value: string;
+  /** Fully custom preset: compute the range yourself from `now`. */
+  getRange?: (now: Date) => DateRangePickerRangeValue;
+}
+
+export interface DateRangePickerChangeMeta {
+  operator: DateRangePickerOperator;
+  /** Selected controlling CRM property, when field selection is enabled. */
+  field?: string | null;
+  /** The preset key that produced the range, or null for manual edits / clear. */
+  preset: string | null;
+  range?: DateRangePickerRangeValue | null;
+  previousOperator?: DateRangePickerOperator;
+}
+
+export interface DateRangePickerProps {
+  /** Controlled date filter value. Range sides may be null for an open-ended range. */
+  value?: DateRangePickerValue;
+  /** Initial date filter value for uncontrolled usage. */
+  defaultValue?: DateRangePickerValue;
+  /** Fires with normalized values. Explicit ranges only emit when valid (from <= to, or a side null). */
+  onChange?: (range: DateRangePickerValue, meta: DateRangePickerChangeMeta) => void;
+  /** Optional group label rendered above the control. */
+  label?: ReactNode;
+  /** Base for inner input names (`${name}-from`, `${name}-to`, `${name}-preset`). */
+  name?: string;
+  /** Controlled CRM date/datetime property value for the field dropdown. */
+  field?: string;
+  /** Initial CRM date/datetime property value for uncontrolled field selection. */
+  defaultField?: string;
+  onFieldChange?: (field: string) => void;
+  /** Render a controlling field dropdown above the operator. */
+  showFieldSelect?: boolean;
+  fieldOptions?: Array<{ label: ReactNode; value: string }>;
+  operator?: DateRangePickerOperator;
+  defaultOperator?: DateRangePickerOperator;
+  onOperatorChange?: (operator: DateRangePickerOperator) => void;
+  showOperatorSelect?: boolean;
+  operatorOptions?: Array<{ label: ReactNode; value: DateRangePickerOperator }>;
+  /** true = HS_DATE_PRESETS Select, false = none, or a custom preset array. */
+  presets?: boolean | DateRangePickerPresetOption[];
+  rollingUnitOptions?: Array<{ label: ReactNode; value: string }>;
+  direction?: "row" | "column";
+  /** Show a Clear link when the range is non-empty. */
+  clearable?: boolean;
+  min?: DateRangePickerDateValue;
+  max?: DateRangePickerDateValue;
+  fromLabel?: string;
+  toLabel?: string;
+  dateLabel?: string;
+  /** Keep DateInput labels visible. Defaults to false for compact filter rows. */
+  showDateLabels?: boolean;
+  /** DateInput display format. Default "medium". */
+  format?: "short" | "long" | "medium" | "standard" | "YYYY-MM-DD" | "L" | "LL" | "ll";
+  presetPlaceholder?: string;
+  customPresetLabel?: string;
+  clearLabel?: ReactNode;
+  invalidRangeMessage?: string;
+  readOnly?: boolean;
+  gap?: string;
+  /** Minimum column width for the field-enabled flexible AutoGrid layout. */
+  gridColumnWidth?: number;
+}
+
 export interface AvatarStackItemObject {
   letter?: string;
   color?: string;
@@ -100,6 +227,61 @@ export interface AvatarStackProps {
   alt?: string;
 }
 
+export type IconSize =
+  | number
+  | "xs"
+  | "extra-small"
+  | "sm"
+  | "small"
+  | "md"
+  | "med"
+  | "medium"
+  | "lg"
+  | "large"
+  | "xl"
+  | "extra-large";
+
+export interface IconPathObject {
+  d: string;
+  fill?: string;
+  fillRule?: "nonzero" | "evenodd";
+}
+
+export type IconPath = string | IconPathObject;
+
+export interface IconEntry {
+  /** Defaults to "0 0 24 24" when omitted. */
+  viewBox?: string;
+  paths: IconPath[];
+  /** Optional transform applied to all paths (e.g. a mirror/rotation). */
+  transform?: string;
+}
+
+export interface IconProps {
+  /** A registered glyph name (native or custom). Unknown names render nothing. */
+  name: string;
+  /** A semantic token ("inherit" | "alert" | "warning" | "success") or any CSS color. */
+  color?: string;
+  size?: IconSize;
+  /** Accessible label for screen readers. */
+  screenReaderText?: string;
+  /** Passed through to native HubSpot Icon when possible; fallback Image also receives it. */
+  onClick?: (...args: unknown[]) => void;
+  /** Passed through to native HubSpot Icon when possible; fallback Image also receives it. */
+  href?: string | { url: string; external?: boolean };
+}
+
+export interface IconDataUriResult {
+  src: string;
+  width: number;
+  height: number;
+}
+
+export interface IconDataUriOptions {
+  size?: IconSize;
+  color?: string;
+}
+
 export interface CollectionFilterConfig {
   name: string;
   type?: "select" | "multiselect" | "dateRange" | string;
@@ -273,6 +455,102 @@ export interface CrmLookupSelectProps {
   selectProps?: Record<string, unknown>;
 }
 
+/** Dotted property path ("properties.domain") or accessor function. */
+export type CrmRecordPickerFieldAccessor =
+  | string
+  | ((record: Record<string, unknown>) => unknown);
+
+export type CrmRecordPickerId = string | number;
+
+export type CrmRecordPickerRecord = Record<string, unknown>;
+
+/** A scalar or array of record ids and/or record objects. */
+export type CrmRecordPickerValue =
+  | CrmRecordPickerId
+  | CrmRecordPickerRecord
+  | Array<CrmRecordPickerId | CrmRecordPickerRecord>;
+
+export interface CrmRecordPickerOption {
+  label: ReactNode;
+  value: CrmRecordPickerId;
+  description?: string;
+}
+
+export interface CrmRecordPickerCreateConfig {
+  /** Static label or `(term) => label` formatter. Default `Create "<term>"`. */
+  label?: string | ((term: string) => string);
+  /** Create the record for the search term; return the new record or its id. */
+  onCreate: (
+    searchTerm: string
+  ) =>
+    | Promise<CrmRecordPickerRecord | CrmRecordPickerId>
+    | CrmRecordPickerRecord
+    | CrmRecordPickerId;
+}
+
+export interface CrmRecordPickerProps {
+  objectType: "contact" | "contacts" | "company" | "companies" | "deal" | "deals" | string;
+  properties?: string[];
+  labelField?: CrmRecordPickerFieldAccessor;
+  descriptionField?: CrmRecordPickerFieldAccessor;
+  value?: CrmRecordPickerValue;
+  defaultValue?: CrmRecordPickerValue;
+  /**
+   * Multi mode passes (ids, records) arrays; single mode passes a scalar id
+   * (or null) and the matching record (or null). Records never seen by the
+   * picker come back as `{ objectId: id }` stubs.
+   */
+  onChange?: (
+    ids: CrmRecordPickerId[] | CrmRecordPickerId | null,
+    records: CrmRecordPickerRecord[] | CrmRecordPickerRecord | null
+  ) => void;
+  multi?: boolean;
+  max?: number;
+  placeholder?: string;
+  label?: string;
+  name?: string;
+  required?: boolean;
+  readOnly?: boolean;
+  error?: boolean;
+  validationMessage?: string;
+  description?: string;
+  tooltip?: string;
+  variant?: "transparent" | "input";
+  pageLength?: number;
+  debounce?: number;
+  minSearchLength?: number;
+  filterMap?: (
+    filters: Record<string, unknown>,
+    params: Record<string, unknown>
+  ) => unknown;
+  allowCreate?: false | CrmRecordPickerCreateConfig;
+  fallbackLabel?: string;
+  format?: Record<string, unknown>;
+  baseConfig?: Record<string, unknown>;
+  onSearchChange?: (query: string) => void;
+  [key: string]: unknown;
+}
+
+export interface CrmRecordPickerCreateOptionRules {
+  allowCreate?: false | true | CrmRecordPickerCreateConfig;
+  searchTerm?: string;
+  options?: CrmRecordPickerOption[];
+  searching?: boolean;
+  createPending?: boolean;
+  atMax?: boolean;
+}
+
+export interface CrmRecordPickerOptionConfig {
+  labelField?: CrmRecordPickerFieldAccessor;
+  descriptionField?: CrmRecordPickerFieldAccessor;
+  fallbackLabel?: string;
+}
+
+export interface CrmRecordPickerSelection {
+  ids: CrmRecordPickerId[];
+  records: CrmRecordPickerRecord[];
+}
+
 export interface StyledTextFormat {
   fontWeight?: "bold" | "demibold" | "regular" | number;
   italic?: boolean;
@@ -362,61 +640,19 @@ export interface SpinnerProps {
   truncate?: boolean | { tooltipText?: string };
 }
 
-export type IconSize =
-  | number
-  | "xs"
-  | "extra-small"
-  | "sm"
-  | "small"
-  | "md"
-  | "med"
-  | "medium"
-  | "lg"
-  | "large"
-  | "xl"
-  | "extra-large";
-
-export interface IconPathObject {
-  d: string;
-  fill?: string;
-  fillRule?: "nonzero" | "evenodd";
-}
-
-export type IconPath = string | IconPathObject;
-
-export interface IconEntry {
-  /** Defaults to "0 0 24 24" when omitted. */
-  viewBox?: string;
-  paths: IconPath[];
-  /** Optional transform applied to all paths (e.g. a mirror/rotation). */
-  transform?: string;
-}
-
-export interface IconProps {
-  /** A registered glyph name (native or custom). Unknown names render nothing. */
-  name: string;
-  /** A semantic token ("inherit" | "alert" | "warning" | "success") or any CSS color. */
-  color?: string;
-  size?: IconSize;
-  /** Accessible label for screen readers. */
-  screenReaderText?: string;
-  /** Passed through to native HubSpot Icon when possible; fallback Image also receives it. */
-  onClick?: (...args: unknown[]) => void;
-  /** Passed through to native HubSpot Icon when possible; fallback Image also receives it. */
-  href?: string | { url: string; external?: boolean };
-}
-
-export interface IconDataUriResult {
-  src: string;
-  width: number;
-  height: number;
-}
-
-export interface IconDataUriOptions {
-  size?: IconSize;
-  color?: string;
-}
-
+export declare function AutoTag(props: AutoTagProps): ReactNode;
+export declare function AutoStatusTag(props: AutoStatusTagProps): ReactNode;
+export declare function ActiveFilterChips(props: ActiveFilterChipsProps): ReactNode;
+export declare function CollectionCount(props: CollectionCountProps): ReactNode;
+export declare function formatCollectionCount(params: FormatCollectionCountParams): ReactNode;
+export declare function CollectionFilterControl(props: CollectionFilterControlProps): ReactNode;
+export declare function CollectionSortSelect(props: CollectionSortSelectProps): ReactNode;
+export declare function CollectionToolbar(props: CollectionToolbarProps): ReactNode;
+export declare function SectionHeader(props: SectionHeaderProps): ReactNode;
+export declare function KeyValueList(props: KeyValueListProps): ReactNode;
+export declare function AvatarStack(props: AvatarStackProps): ReactNode;
+export declare function CrmLookupSelect(props: CrmLookupSelectProps): ReactNode;
+export declare function CrmRecordPicker(props: CrmRecordPickerProps): ReactNode;
 export declare function Icon(props: IconProps): ReactNode;
 /** Custom glyph names registered in this library (excludes native names). */
 export declare const ICON_NAMES: string[];
@@ -431,19 +667,6 @@ export declare function makeIconDataUri(
 ): IconDataUriResult | null;
 /** Parse a raw `<svg>` string into a registry entry (drops mask/defs, keeps per-path fills). */
 export declare function svgToIconEntry(raw: string): IconEntry;
-
-export declare function AutoTag(props: AutoTagProps): ReactNode;
-export declare function AutoStatusTag(props: AutoStatusTagProps): ReactNode;
-export declare function ActiveFilterChips(props: ActiveFilterChipsProps): ReactNode;
-export declare function CollectionCount(props: CollectionCountProps): ReactNode;
-export declare function formatCollectionCount(params: FormatCollectionCountParams): ReactNode;
-export declare function CollectionFilterControl(props: CollectionFilterControlProps): ReactNode;
-export declare function CollectionSortSelect(props: CollectionSortSelectProps): ReactNode;
-export declare function CollectionToolbar(props: CollectionToolbarProps): ReactNode;
-export declare function SectionHeader(props: SectionHeaderProps): ReactNode;
-export declare function KeyValueList(props: KeyValueListProps): ReactNode;
-export declare function AvatarStack(props: AvatarStackProps): ReactNode;
-export declare function CrmLookupSelect(props: CrmLookupSelectProps): ReactNode;
 export declare function StyledText(props: StyledTextProps): ReactNode;
 export declare function Spinner(props: SpinnerProps): ReactNode;
 export declare const SPINNERS: Record<SpinnerName, SpinnerPreset>;
@@ -459,6 +682,32 @@ export declare function makeStyledTextDataUri(
   options?: StyledTextDataUriOptions
 ): StyledTextDataUriResult;
 
+export declare function DateRangePicker(props: DateRangePickerProps): ReactNode;
+/** Translate an HS_DATE_PRESETS key into a { from, to } range. Null for unknown/custom/empty keys. */
+export declare function presetToRange(
+  presetKey: string | null | undefined,
+  now?: Date
+): DateRangePickerRangeValue | null;
+/** Convert a JS Date to a HubSpot date value object. Null for invalid input. */
+export declare function toHsDateValue(date: Date): DateRangePickerDateValue | null;
+/** Sort-style comparator for HubSpot date value objects; null sides compare as 0. */
+export declare function compareHsDateValues(
+  a: DateRangePickerDateValue | null | undefined,
+  b: DateRangePickerDateValue | null | undefined
+): number;
+/** True when the range is open-ended or from <= to. */
+export declare function isValidDateRange(range: DateRangePickerRangeValue | null | undefined): boolean;
+/** Sentinel preset value meaning "the user picked dates by hand". */
+export declare const DATE_RANGE_CUSTOM_VALUE: "custom";
+export declare const DATE_FILTER_OPERATORS: Array<{
+  label: string;
+  value: DateRangePickerOperator;
+}>;
+export declare const DATE_ROLLING_UNIT_OPTIONS: Array<{
+  label: string;
+  value: string;
+}>;
+
 export declare const HS_DATE_PRESETS: DatePresetOption[];
 export declare const HS_DATE_DIRECTION_LABELS: DateDirectionLabels;
 export declare const HS_FONT_FAMILY: string;
@@ -466,6 +715,8 @@ export declare const HS_TEXT_COLOR: string;
 export declare const HS_SUBTLE_BG: string;
 export declare const HS_MUTED_TEXT: string;
 export declare const HS_NEUTRAL_CHIP: string;
+/** Skeleton placeholder gray. */
+export declare const SKELETON_FILL: string;
 export declare const HS_TAG_SUBTLE_BORDER: string;
 export declare const HS_TAG_TEXT_COLOR: string;
 export declare const HS_TAG_FONT_SIZE: number;