hs-uix 2.0.0 → 2.1.0

package/README.md

@@ -15,25 +15,36 @@ npm install hs-uix
 import { DataTable } from "hs-uix/datatable";
 import { FormBuilder } from "hs-uix/form";
 import { Feed } from "hs-uix/feed";
-import { AutoStatusTag, AutoTag, KeyValueList, SectionHeader } from "hs-uix/common-components";
-import { formatCurrency, formatDate } from "hs-uix/utils";
+import { Calendar } from "hs-uix/calendar";
+import {
+  Icon,
+  AutoStatusTag,
+  AutoTag,
+  CrmLookupSelect,
+  KeyValueList,
+  SectionHeader,
+  CollectionToolbar,
+} from "hs-uix/common-components";
+import { CrmDataTable, CrmKanban, formatCurrency, formatDate } from "hs-uix/utils";
 
 // or import everything from the root
-import { DataTable, FormBuilder, AutoStatusTag, AutoTag } from "hs-uix";
+import { DataTable, FormBuilder, Kanban, Feed, Calendar, Icon } from "hs-uix";
 ```
 
-Requires `react` >= 18.0.0 and `@hubspot/ui-extensions` >= 0.12.0 as peer dependencies (already present in any HubSpot UI Extensions project).
+Requires `react` >= 18.0.0 and `@hubspot/ui-extensions` >= 0.14.0 as peer dependencies (already present in any HubSpot UI Extensions project).
 
 ## Components
 
 | Component | Description | Docs |
 |-----------|-------------|------|
-| **DataTable** | Filterable, sortable, paginated table with auto-sized columns, inline editing, row grouping, and more | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/packages/datatable/README.md) |
-| **FormBuilder** | Declarative, config-driven form with validation, multi-step wizards, and 20+ field types | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/packages/form/README.md) |
-| **Kanban** | Stage-based board with filters, sort, headline metrics, card action bars, and DataTable-parity card field config | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/packages/kanban/README.md) |
-| **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/packages/feed/README.md) |
-| **Common Components** | Thin visual wrappers over HubSpot primitives — `AutoTag`, `AutoStatusTag`, `AvatarStack`, `SectionHeader`, `KeyValueList`, `StyledText` | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/common-components/README.md) |
-| **Utils** | Pure helpers for formatting, options, HubSpot value guards, and tag-variant inference | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/utils/README.md) |
+| **DataTable** | Filterable, sortable, paginated table with auto-sized columns, inline editing, row grouping, and more | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/datatable/README.md) |
+| **FormBuilder** | Declarative, config-driven form with validation, multi-step wizards, and 20+ field types | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/form/README.md) |
+| **Kanban** | Stage-based board with filters, sort, headline metrics, card action bars, and DataTable-parity card field config | [Full documentation](https://github.com/05bmckay/hs-uix/blob/main/src/kanban/README.md) |
+| **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) |
+| **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) |
 
 ---
 
@@ -41,7 +52,7 @@ Requires `react` >= 18.0.0 and `@hubspot/ui-extensions` >= 0.12.0 as peer depend
 
 A drop-in table component for HubSpot UI Extensions. Define your columns, pass your data, and you get search, filtering, sorting, pagination, inline editing, row grouping, and auto-sized columns out of the box.
 
-![Full-Featured DataTable](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/datatable/assets/fully-featured-table.png)
+![Full-Featured DataTable](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/datatable/assets/fully-featured-table.png)
 
 ## Quick Start
 
@@ -94,29 +105,29 @@ That's a searchable, sortable, paginated table with auto-sized columns in 5 line
 
 ### Filters & Footer Totals
 
-![Active Filters](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/datatable/assets/fully-featured-table-active-filters.png)
+![Active Filters](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/datatable/assets/fully-featured-table-active-filters.png)
 
 ### Row Selection & Bulk Actions
 
-![Row Selection with Action Bar](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/datatable/assets/action-bar-per-row-actions.png)
+![Row Selection with Action Bar](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/datatable/assets/action-bar-per-row-actions.png)
 
 ### Inline Editing
 
-![Discrete Editing](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/datatable/assets/inline-editing-discreet.png)
+![Discrete Editing](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/datatable/assets/inline-editing-discreet.png)
 
 Two edit modes: **discrete** (click-to-edit, default) and **inline** (always-visible inputs). Supports `text`, `textarea`, `number`, `currency`, `stepper`, `select`, `multiselect`, `date`, `time`, `datetime`, `toggle`, and `checkbox`.
 
 ### Row Grouping
 
-![Row Grouping](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/datatable/assets/row-grouping.png)
+![Row Grouping](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/datatable/assets/row-grouping.png)
 
 ### Full-Row Editing
 
-![Full-Row Editing](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/datatable/assets/full-row-editing.png)
+![Full-Row Editing](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/datatable/assets/full-row-editing.png)
 
 ### useAssociations
 
-![useAssociations + DataTable](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/datatable/assets/useAssociations.png)
+![useAssociations + DataTable](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/datatable/assets/useAssociations.png)
 
 Connect live CRM data (contacts, deals, tickets, etc.) to a DataTable with `useAssociations` from `@hubspot/ui-extensions/crm`.
 
@@ -126,7 +137,7 @@ Connect live CRM data (contacts, deals, tickets, etc.) to a DataTable with `useA
 
 Declarative, config-driven forms for HubSpot UI Extensions. Define fields as data, get a complete form with validation, layout, multi-step wizards, and full HubSpot component integration.
 
-![Basic Form](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/basic-form.png)
+![Basic Form](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/basic-form.png)
 
 ## Quick Start
 
@@ -165,35 +176,35 @@ const fields = [
 
 ### Layout
 
-![Explicit Layout](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/explicit-layout-weighted.png)
+![Explicit Layout](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/explicit-layout-weighted.png)
 
 ### Conditional Visibility & Dependent Properties
 
-![Dependent & Cascading](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/dependent-cascading.gif)
+![Dependent & Cascading](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/dependent-cascading.gif)
 
 ### Async Validation
 
-![Async Validation](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/async-validation-side-effects.png)
+![Async Validation](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/async-validation-side-effects.png)
 
 ### Repeater Fields
 
-![Repeater Fields](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/repeater-fields.png)
+![Repeater Fields](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/repeater-fields.png)
 
 ### Sections & Groups
 
-![Sections & Groups](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/section-and-groups.png)
+![Sections & Groups](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/section-and-groups.png)
 
 ### Custom Field Types
 
-![Custom Field Types](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/custom-field-types.png)
+![Custom Field Types](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/custom-field-types.png)
 
 ### Display Options
 
-![Display Options](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/display-options.png)
+![Display Options](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/display-options.png)
 
 ### Read-Only Mode
 
-![Read-Only Mode](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/form/assets/readonly-autosave-dirty.png)
+![Read-Only Mode](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/form/assets/readonly-autosave-dirty.png)
 
 ---
 
@@ -201,7 +212,7 @@ const fields = [
 
 A stage-based board view that shares DataTable's config vocabulary (`cardFields` ≈ `columns`, filters, sort, selection) so you can offer users a table-or-board toggle without rewriting the data layer. Drag-and-drop isn't available inside HubSpot UI Extensions, so stage changes happen through an inline `Select` (or menu) on each card.
 
-![Kanban — HubSpot Deals preset with metrics](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/kanban/assets/hubspot-deals-preset-with-metrics.png)
+![Kanban — HubSpot Deals preset with metrics](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/kanban/assets/hubspot-deals-preset-with-metrics.png)
 
 ## Quick Start
 
@@ -250,21 +261,21 @@ const CARD_FIELDS = [
 
 ### HubSpot Deals preset
 
-![Kanban — HubSpot Deals preset with metrics](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/kanban/assets/hubspot-deals-preset-with-metrics.png)
+![Kanban — HubSpot Deals preset with metrics](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/kanban/assets/hubspot-deals-preset-with-metrics.png)
 
 Drop-in preset shaped like HubSpot's native deals pipeline: stage-variant headers, per-stage amount totals in the header metric, and an avatar-stack footer row. Hide the summary row with `showMetrics={false}` for dashboards that already surface totals elsewhere.
 
-![Kanban — HubSpot Deals preset without metrics](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/kanban/assets/hubspot-deals-preset-no-metrics.png)
+![Kanban — HubSpot Deals preset without metrics](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/kanban/assets/hubspot-deals-preset-no-metrics.png)
 
 ### Compact lead board
 
-![Kanban — Compact lead board preset](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/kanban/assets/compact-lead-board-preset.png)
+![Kanban — Compact lead board preset](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/kanban/assets/compact-lead-board-preset.png)
 
 `cardDensity="compact"` with trimmed `cardFields` for high-volume boards (leads, tickets, tasks) where you want to fit 8-12 cards per column on a typical viewport without horizontal scrolling.
 
 ### Load-more & stage controls
 
-![Kanban — Select + load more preset](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/kanban/assets/select-load-more-preset.png)
+![Kanban — Select + load more preset](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/kanban/assets/select-load-more-preset.png)
 
 Per-stage pagination via an `onLoadMore` handler and `stageMeta.hasMore`, plus inline `Select` stage controls on each card (`stageControl="select"`). Switch to `"menu"` for action-menu style transitions, or `"none"` for read-only boards.
 
@@ -305,9 +316,11 @@ import { formatCurrency } from "hs-uix/utils";
 
 ## What's inside
 
+- `Icon` — a superset of HubSpot's native `<Icon>`: custom glyphs, any CSS color, and pixel sizes, delegating to the native component whenever the request is natively expressible
 - `AutoStatusTag` — `StatusTag` with variant inferred from the value (`Active` → success, `At risk` → warning, `Failed` → danger, etc.)
 - `AutoTag` — `Tag` with the same inference, for non-status labels
 - `AvatarStack` — overlapping circular avatars as a single SVG (letters, image URLs, or mixed); `+N` overflow chip past `maxVisible`
+- `CrmLookupSelect` — CRM-backed `Select` / `MultiSelect` with live, debounced search
 - `SectionHeader` — title + optional description + actions slot
 - `KeyValueList` — vertical list of label/value rows via `DescriptionList`
 - `StyledText` — SVG-rendered text with rotation, custom color, and pill backgrounds for cases native `<Text>` can't express
@@ -330,6 +343,16 @@ Pass a free-form status string and get a properly-colored tag back. Matching is
 
 Overlapping avatars rendered as a single SVG via `<Image>`. T-shirt sizing (`xs` → `xl`) or a raw pixel number. Letters auto-color from the built-in palette; image URLs get circular-clipped. Extras past `maxVisible` collapse into a neutral `+N` chip.
 
+### Icon
+
+A superset of HubSpot's native `<Icon>`. When the request is natively expressible (a whitelisted `name`, a semantic `color`, an `sm`/`md`/`lg` `size`) it **delegates to the real `<Icon>`** — keeping auto-sizing, `color="inherit"`, and screen-reader semantics. Otherwise it renders a registered SVG glyph as a data-URI `<Image>`, lifting all three native limits: custom/unregistered glyphs (~248 bundled in `ICONS`), any CSS color, and `xs`–`xl` tokens or a pixel size. Add your own glyphs via `svgToIconEntry`, or build a data URI directly with `makeIconDataUri`.
+
+### CrmLookupSelect
+
+![CrmLookupSelect live search](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/common-components/assets/crmLookUp.gif)
+
+Point it at a CRM `objectType` + `properties` and get a debounced `Select` / `MultiSelect` that searches the first `pageLength` CRM matches as the user types. Picked options stay valid after results change, `loadingOption` shows during the debounce window, and `noResultsOption` only appears once a query settles — no "no results" flash mid-type. For custom lookup UIs that need native cursor controls, `useCrmSearchOptions` exposes `pagination` / `hasMore`.
+
 ### SectionHeader & KeyValueList
 
 ![KeyValueList](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/common-components/assets/key-value-list.png)

package/calendar.d.ts

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

package/common-components.d.ts

@@ -100,6 +100,139 @@ export interface AvatarStackProps {
   alt?: string;
 }
 
+export interface CollectionFilterConfig {
+  name: string;
+  type?: "select" | "multiselect" | "dateRange" | string;
+  label?: string;
+  placeholder?: string;
+  options?: Array<{ label: ReactNode; value: unknown }>;
+  includeAll?: boolean;
+  allValue?: unknown;
+  emptyValue?: unknown;
+  allLabel?: string;
+  chipLabel?: string;
+  fromLabel?: string;
+  toLabel?: string;
+}
+
+export interface CollectionFilterLabels {
+  all?: string;
+  dateFrom?: string;
+  dateTo?: string;
+}
+
+export interface CollectionFilterControlProps {
+  filter?: CollectionFilterConfig;
+  value?: unknown;
+  onChange?: (name: string, value: unknown) => void;
+  namePrefix?: string;
+  labels?: CollectionFilterLabels;
+  selectVariant?: "transparent" | "input" | string;
+  includeAll?: boolean;
+  allValue?: unknown;
+}
+
+export interface ActiveFilterChip {
+  key: string;
+  label: ReactNode;
+}
+
+export interface ActiveFilterChipsProps {
+  chips?: ActiveFilterChip[];
+  showBadges?: boolean;
+  showClearAll?: boolean;
+  clearAllLabel?: ReactNode;
+  onRemove?: (key: string) => void;
+  gap?: string;
+}
+
+export interface CollectionToolbarSearchConfig {
+  visible?: boolean;
+  show?: boolean;
+  name?: string;
+  placeholder?: string;
+  value?: string;
+  clearable?: boolean;
+  onChange?: (value: string) => void;
+  onInput?: (value: string) => void;
+}
+
+export interface CollectionToolbarFiltersConfig {
+  items?: CollectionFilterConfig[];
+  values?: Record<string, unknown>;
+  inlineLimit?: number;
+  namePrefix?: string;
+  onChange?: (name: string, value: unknown) => void;
+  labels?: CollectionFilterLabels & Record<string, unknown>;
+  includeAll?: boolean;
+  allValue?: unknown;
+  selectVariant?: "transparent" | "input" | string;
+  overflowButtonSize?: string;
+  filtersButtonLabel?: ReactNode;
+}
+
+export interface CollectionToolbarChipsConfig {
+  items?: ActiveFilterChip[];
+  showBadges?: boolean;
+  showClearAll?: boolean;
+  clearAllLabel?: ReactNode;
+  onRemove?: (key: string) => void;
+  gap?: string;
+}
+
+export interface CollectionCountLabelObject {
+  singular: string;
+  plural: string;
+}
+
+export interface CollectionCountProps {
+  shown?: number;
+  total?: number;
+  label?: string | CollectionCountLabelObject | ((count: number) => string);
+  text?: ReactNode;
+  formatter?: (shown: number, total: number) => ReactNode;
+  bold?: boolean;
+  variant?: string;
+  format?: Record<string, unknown>;
+}
+
+export interface FormatCollectionCountParams {
+  shown?: number;
+  total?: number;
+  label?: string | CollectionCountLabelObject | ((count: number) => string);
+  formatter?: (shown: number, total: number) => ReactNode;
+}
+
+export interface CollectionSortSelectProps {
+  name?: string;
+  value?: string | null;
+  options?: Array<{ label: ReactNode; value: string }>;
+  placeholder?: string;
+  onChange?: (value: string) => void;
+  includeEmpty?: boolean;
+  emptyValue?: string;
+  variant?: "transparent" | "input" | string;
+  idPrefix?: string;
+  uniqueName?: boolean;
+}
+
+export interface CollectionToolbarProps {
+  search?: CollectionToolbarSearchConfig;
+  filters?: CollectionToolbarFiltersConfig;
+  chips?: CollectionToolbarChipsConfig;
+  right?: ReactNode;
+  footer?: ReactNode;
+  labels?: Record<string, unknown>;
+  leftFlex?: number;
+  rightFlex?: number;
+  rightAlignSelf?: string;
+  gap?: string;
+  /** Optional stable prefix used to generate unique child input/select names. */
+  idPrefix?: string;
+  /** Append a per-toolbar suffix to child input/select names. Default true. */
+  uniqueNames?: boolean;
+}
+
 export interface CrmLookupSelectProps {
   objectType: "contact" | "contacts" | "company" | "companies" | "deal" | "deals" | string;
   properties?: string[];
@@ -267,6 +400,10 @@ export interface IconProps {
   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 {
@@ -297,6 +434,12 @@ 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;

package/datatable.d.ts

@@ -1,27 +1 @@
-export {
-  DataTable,
-  DataTableProps,
-  DataTableColumn,
-  DataTableFilterConfig,
-  DataTableFilterType,
-  DataTableGroupBy,
-  DataTableSortDirection,
-  DataTableSortObject,
-  DataTableParams,
-  DataTableOption,
-  DataTableDateValue,
-  DataTableTimeValue,
-  DataTableDateRangeValue,
-  DataTableWidth,
-  DataTableColumnWidth,
-  DataTableEditMode,
-  DataTableEditType,
-  DataTableSelectionAction,
-  DataTableRowAction,
-  DataTableSelectAllRequestPayload,
-  DataTableLabels,
-  DataTableSelectionBarRenderContext,
-  DataTableEmptyStateRenderContext,
-  DataTableLoadingStateRenderContext,
-  DataTableErrorStateRenderContext,
-} from "./packages/datatable/index";
+export * from "./src/datatable/index";