hs-uix 1.6.4 → 1.7.0

package/packages/kanban/index.d.ts

@@ -0,0 +1,367 @@
+import type { ReactElement, ReactNode } from "react";
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+export type KanbanStageVariant = "success" | "info" | "warning" | "default";
+export type KanbanCardDensity = "compact" | "comfortable";
+export type KanbanStageControlMode = "select" | "menu" | "none";
+export type KanbanCardBodyMode = "descriptionList" | "stack";
+export type KanbanFilterType = "select" | "multiselect" | "dateRange";
+
+export interface KanbanOption<T = string> {
+  label: string;
+  value: T;
+}
+
+export interface KanbanFilterConfig<Row = Record<string, unknown>> {
+  name: string;
+  type?: KanbanFilterType;
+  placeholder?: string;
+  /** Prefix used in the active-filter chip. Defaults to `placeholder` or `name`. */
+  chipLabel?: string;
+  options?: KanbanOption[];
+  filterFn?: (row: Row, value: unknown) => boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Card fields
+// ---------------------------------------------------------------------------
+
+export type KanbanCardFieldPlacement = "title" | "subtitle" | "meta" | "body" | "footer";
+
+export interface KanbanCardField<Row = Record<string, unknown>> {
+  key?: string;
+  field?: string;
+  label?: string;
+  render?: (value: unknown, row: Row) => ReactNode;
+  placement?: KanbanCardFieldPlacement;
+  href?:
+    | string
+    | { url: string; external?: boolean }
+    | ((row: Row) => string | { url: string; external?: boolean });
+  truncate?: true | number;
+  visible?: (row: Row) => boolean;
+  colSpan?: number;
+}
+
+export interface KanbanCardDividers {
+  afterTitle?: boolean;
+  afterSubtitle?: boolean;
+  afterBody?: boolean;
+  afterFooter?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Stage definition
+// ---------------------------------------------------------------------------
+
+export interface KanbanStageChangeResult {
+  extraProperties?: Record<string, unknown>;
+}
+
+export interface KanbanTransitionPromptContext<Row> {
+  row: Row;
+  fromStage: string;
+  toStage: string;
+  onConfirm: (result?: KanbanStageChangeResult) => void;
+  onCancel: () => void;
+}
+
+export interface KanbanStage<Row = Record<string, unknown>> {
+  value: string;
+  label: string;
+  shortLabel?: string;
+  description?: string;
+  variant?: KanbanStageVariant;
+  color?: string;
+  icon?: string;
+  terminal?: boolean;
+  order?: number;
+  footer?: (rows: Row[]) => ReactNode;
+  canEnter?: (row: Row) => boolean;
+  onEnterRequired?: {
+    render: (ctx: KanbanTransitionPromptContext<Row>) => ReactNode;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Pagination
+// ---------------------------------------------------------------------------
+
+export interface KanbanStageMeta {
+  hasMore?: boolean;
+  totalCount?: number;
+  loading?: boolean;
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Sorting
+// ---------------------------------------------------------------------------
+
+export interface KanbanSortOption<Row = Record<string, unknown>> {
+  value: string;
+  label: string;
+  /** Optional grouping metadata for the richer "field + direction" sort picker UI. */
+  field?: string;
+  /** Optional direction used with `field` to render Asc/Desc toggle controls. */
+  direction?: "asc" | "desc";
+  /** Optional label shown for the grouped field selector. */
+  fieldLabel?: string;
+  comparator: (a: Row, b: Row) => number;
+}
+
+// ---------------------------------------------------------------------------
+// Selection
+// ---------------------------------------------------------------------------
+
+export interface KanbanSelectionAction<Id = string | number> {
+  label: string;
+  icon?: string;
+  variant?: "primary" | "secondary" | "transparent";
+  onClick: (selectedIds: Id[]) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Render contexts
+// ---------------------------------------------------------------------------
+
+export interface KanbanCardRenderContext<Row = Record<string, unknown>> {
+  stage: KanbanStage<Row>;
+  isChanging: boolean;
+  density: KanbanCardDensity;
+  onStageChange: (newStage: string) => void;
+}
+
+export interface KanbanParams {
+  search: string;
+  filters: Record<string, unknown>;
+  sort: string | null;
+  collapsedStages: string[];
+}
+
+export interface KanbanEmptyStateRenderContext {
+  title: string;
+  message: string;
+}
+
+export interface KanbanLoadingStateRenderContext {
+  label: string;
+}
+
+export interface KanbanErrorStateRenderContext {
+  error: string | boolean;
+  title: string;
+  message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Labels
+// ---------------------------------------------------------------------------
+
+export interface KanbanLabels {
+  search?: string;
+  showMore?: (shown: number, total: number) => string;
+  showLess?: string;
+  loadMore?: (loaded: number, total?: number) => string;
+  loadingMore?: string;
+  retryLoadMore?: string;
+  emptyColumn?: string;
+  emptyTitle?: string;
+  emptyMessage?: string;
+  loading?: string;
+  loadingMessage?: string;
+  errorTitle?: string;
+  errorMessage?: string;
+  cardCount?: (n: number) => string;
+  moveTo?: string;
+  clearAll?: string;
+  selectAll?: string | ((count: number, label: string) => string);
+  deselectAll?: string;
+  selected?: (count: number, label: string) => string;
+  /** Primary label for the overflow-filter toggle button. */
+  filtersButton?: string;
+  dateFrom?: string;
+  dateTo?: string;
+  sortButton?: string;
+  sortAscending?: string;
+  sortDescending?: string;
+  metricsButton?: string;
+}
+
+export interface KanbanMetricItem {
+  id?: string;
+  label: string;
+  number: string | number;
+  trend?: {
+    direction?: "increase" | "decrease";
+    value: string;
+    color?: "red" | "green";
+  };
+}
+
+export interface KanbanSelectionBarRenderContext<Id = string | number> {
+  selectedIds: Id[];
+  selectedCount: number;
+  displayCount: number;
+  countLabel: (n: number) => string;
+  allSelected: boolean;
+  onSelectAll: () => void;
+  onDeselectAll: () => void;
+  selectionActions: KanbanSelectionAction<Id>[];
+  labels: KanbanLabels;
+}
+
+// ---------------------------------------------------------------------------
+// KanbanCardActions — shipped helper
+// ---------------------------------------------------------------------------
+
+export interface KanbanCardAction {
+  key?: string;
+  label: string;
+  icon?: string;
+  tooltip?: string;
+  variant?: "primary" | "secondary" | "transparent";
+  disabled?: boolean;
+  visible?: boolean;
+  onClick?: () => void;
+  href?: string | { url: string; external?: boolean };
+}
+
+export interface KanbanCardActionsProps {
+  actions: KanbanCardAction[];
+  display?: "icon" | "label" | "iconAndLabel";
+  size?: "xs" | "sm";
+  align?: "start" | "end" | "between";
+  gap?: string;
+  separator?: "none" | "pipe";
+  overflowAfter?: number;
+  overflowLabel?: string;
+}
+
+export declare function KanbanCardActions(props: KanbanCardActionsProps): ReactElement | null;
+
+// ---------------------------------------------------------------------------
+// Kanban props
+// ---------------------------------------------------------------------------
+
+export interface KanbanProps<Row = Record<string, unknown>, Id = string | number> {
+  // Data
+  data: Row[];
+  stages: KanbanStage<Row>[];
+  groupBy?: string | ((row: Row) => string);
+  rowIdField?: string;
+
+  // Card rendering
+  renderCard?: (row: Row, context: KanbanCardRenderContext<Row>) => ReactNode;
+  cardFields?: KanbanCardField<Row>[];
+  cardDensity?: KanbanCardDensity;
+  cardDividers?: boolean | KanbanCardDividers;
+  cardBodyAs?: KanbanCardBodyMode;
+  countDisplay?: "tag" | "text" | "none";
+  maxBodyLines?: number;
+  maxCardsPerColumn?: number;
+  maxCardsExpanded?: number;
+  expandedStages?: string[];
+  onExpandedStagesChange?: (stages: string[]) => void;
+
+  // Per-stage pagination
+  stageMeta?: Record<string, KanbanStageMeta>;
+  onLoadMore?: (stage: string) => void;
+
+  // Selection
+  selectable?: boolean;
+  selectedIds?: Id[];
+  onSelectionChange?: (selectedIds: Id[]) => void;
+  selectionActions?: KanbanSelectionAction<Id>[];
+  recordLabel?: { singular: string; plural: string };
+  /** Optional key that forces uncontrolled selection memory to reset when it changes. */
+  selectionResetKey?: unknown;
+  /** Clears uncontrolled selection when search/filter/sort changes. Default true. */
+  resetSelectionOnQueryChange?: boolean;
+  /** Hide the default selection bar while keeping selection state active. */
+  showSelectionBar?: boolean;
+  /** Full render override for the selection bar — receives all state + handlers. */
+  renderSelectionBar?: (ctx: KanbanSelectionBarRenderContext<Id>) => ReactNode;
+
+  // Stage transitions
+  stageControl?: KanbanStageControlMode;
+  stageControlPlacement?: "inline" | "separateRow";
+  onStageChange?: (
+    row: Row,
+    newStage: string,
+    oldStage: string,
+    result?: KanbanStageChangeResult
+  ) => void | Promise<unknown>;
+  isStageChanging?: (row: Row) => boolean;
+  canMove?: (row: Row, toStage: string) => boolean;
+
+  // Toolbar
+  showSearch?: boolean;
+  /** Search is only active, and the search input only renders, when this list is non-empty. */
+  searchFields?: string[];
+  searchPlaceholder?: string;
+  /** ms to debounce onSearchChange callback. 0 = no debounce. */
+  searchDebounce?: number;
+  /** Enable fuzzy matching via Fuse.js */
+  fuzzySearch?: boolean;
+  /** Custom Fuse.js options (threshold, distance, keys, etc.) */
+  fuzzyOptions?: Record<string, unknown>;
+  filters?: KanbanFilterConfig<Row>[];
+  /** Number of filters shown inline before the "Filters" overflow button. Default 2. */
+  filterInlineLimit?: number;
+  /** Show active filter chips with individual clear affordances. Default true. */
+  showFilterBadges?: boolean;
+  /** Show the "Clear all" reset button when filters are active. Defaults to `showFilterBadges` when omitted, so hiding the chips hides the clear-all button too. */
+  showClearFiltersButton?: boolean;
+  /** Supports simple options or grouped field/direction options for the richer sort picker UI. */
+  sortOptions?: KanbanSortOption<Row>[];
+  defaultSort?: string;
+  sort?: string;
+  onSortChange?: (value: string) => void;
+
+  // Column level
+  columnFooter?: (rows: Row[], stage: KanbanStage<Row>) => ReactNode;
+  /**
+   * Pixel width for each column, passed to AutoGrid's columnWidth. Columns
+   * share available horizontal space equally with this value as the minimum.
+   * Clamped to 280px minimum regardless of the value passed. Default 280px.
+   */
+  columnWidth?: number;
+  collapsedStages?: string[];
+  onCollapsedStagesChange?: (stages: string[]) => void;
+
+  // Metrics panel (toggled via the toolbar's Metrics button)
+  /** Array of stat items for the <Statistics> panel, or a custom ReactNode. */
+  metrics?: KanbanMetricItem[] | ReactNode;
+  /** Controlled visibility of the metrics panel. */
+  showMetrics?: boolean;
+  /** Fires when the Metrics button is clicked. Receives the new visible state. */
+  onMetricsToggle?: (visible: boolean) => void;
+
+  // Controlled state
+  searchValue?: string;
+  onSearchChange?: (term: string) => void;
+  filterValues?: Record<string, unknown>;
+  onFilterChange?: (values: Record<string, unknown>) => void;
+  /** Unified callback fired when search/filter/sort/collapsed-stage state changes. */
+  onParamsChange?: (params: KanbanParams) => void;
+  loading?: boolean;
+  error?: string | boolean;
+
+  // Labels
+  labels?: KanbanLabels;
+
+  /** Replace the default empty-state UI. */
+  renderEmptyState?: (ctx: KanbanEmptyStateRenderContext) => ReactNode;
+  /** Replace the default loading spinner UI. */
+  renderLoadingState?: (ctx: KanbanLoadingStateRenderContext) => ReactNode;
+  /** Replace the default top-level error UI. */
+  renderErrorState?: (ctx: KanbanErrorStateRenderContext) => ReactNode;
+}
+
+export declare function Kanban<Row = Record<string, unknown>, Id = string | number>(
+  props: KanbanProps<Row, Id>
+): ReactElement | null;

package/utils.d.ts

@@ -1,3 +1,7 @@
+import type { ComponentType } from "react";
+import type { DataTableProps, DataTableColumn } from "./packages/datatable/index";
+import type { KanbanProps } from "./packages/kanban/index";
+
 export type AutoStatusTagVariant = "default" | "success" | "warning" | "danger" | "info";
 export type AutoTagVariant = "default" | "success" | "warning" | "error" | "info";
 
@@ -47,6 +51,17 @@ export interface StatusTagSortComparatorOptions extends AutoStatusTagOptions {
 export declare function createStatusTagSortComparator(
   options?: StatusTagSortComparatorOptions
 ): (aValue: unknown, bValue: unknown) => number;
+export declare function buildCrmSearchConfig(params?: CrmSearchParams, options?: CrmSearchConfigOptions): Record<string, unknown>;
+export declare function normalizeCrmSearchRecord<Row = Record<string, unknown>>(record: unknown, options?: CrmSearchNormalizeOptions<Row>): Row;
+export declare function normalizeCrmSearchRows<Row = Record<string, unknown>>(response: unknown, options?: CrmSearchNormalizeOptions<Row>): Row[];
+export declare function useCrmSearchDataSource<Row = Record<string, unknown>>(params?: CrmSearchParams, options?: CrmSearchConfigOptions<Row>): CrmSearchDataSource<Row>;
+export declare function crmSearchResultToOption<Row = Record<string, unknown>>(row: Row, options?: CrmSearchOptionOptions<Row>): BuiltOption;
+export declare function useCrmSearchOptions<Row = Record<string, unknown>>(params?: CrmSearchParams, options?: CrmSearchConfigOptions<Row> & CrmSearchOptionOptions<Row>): CrmSearchOptionsDataSource<Row>;
+export declare function makeCrmSearchSelectField<Field = Record<string, unknown>>(field: Field, searchOptions: { options?: BuiltOption[]; loading?: boolean; isLoading?: boolean }): Field & CrmSearchFormField;
+export declare function makeCrmSearchMultiSelectField<Field = Record<string, unknown>>(field: Field, searchOptions: { options?: BuiltOption[]; loading?: boolean; isLoading?: boolean }): Field & CrmSearchFormField;
+export declare function resolveCrmObjectType(objectType: string): string;
+export declare const CrmDataTable: ComponentType<CrmDataTableProps>;
+export declare const CrmKanban: ComponentType<CrmKanbanProps>;
 export interface FormatCurrencyCompactOptions extends Intl.NumberFormatOptions {
   locale?: string;
   currency?: string;
@@ -54,6 +69,113 @@ export interface FormatCurrencyCompactOptions extends Intl.NumberFormatOptions {
   compactDisplay?: "short" | "long";
 }
 
+export interface CrmSearchParams {
+  search?: string;
+  filters?: Record<string, unknown>;
+  sort?: unknown;
+  pageLength?: number;
+  [key: string]: unknown;
+}
+
+export interface CrmSearchConfigOptions<Row = Record<string, unknown>> {
+  objectType?: string;
+  properties?: string[];
+  query?: string;
+  filterGroups?: Array<{ filters: Array<Record<string, unknown>> }>;
+  sorts?: Array<Record<string, unknown>>;
+  pageLength?: number;
+  propertyMap?: Record<string, string>;
+  filterMap?: (filters: Record<string, unknown>, params: CrmSearchParams) => Array<{ filters: Array<Record<string, unknown>> }> | undefined;
+  sortMap?: (sort: unknown, params: CrmSearchParams) => Array<Record<string, unknown>> | undefined;
+  baseConfig?: Record<string, unknown>;
+  format?: Record<string, unknown>;
+  row?: CrmSearchNormalizeOptions<Row>;
+  rowIdField?: string;
+  option?: CrmSearchOptionOptions<Row>;
+  mapResponse?: (response: unknown) => Row[];
+  totalCount?: number | ((response: unknown) => number);
+  loading?: boolean | ((response: unknown) => boolean);
+  error?: string | boolean | ((response: unknown) => string | boolean);
+}
+
+export interface CrmSearchNormalizeOptions<Row = Record<string, unknown>> {
+  idField?: string;
+  objectIdField?: string;
+  propertiesKey?: string;
+  flattenProperties?: boolean;
+  propertyValueKey?: string;
+  mapRecord?: (record: unknown) => Row;
+}
+
+export interface CrmSearchOptionOptions<Row = Record<string, unknown>> {
+  label?: string | ((row: Row) => unknown);
+  value?: string | ((row: Row) => unknown);
+  description?: string | ((row: Row) => unknown);
+  fallbackLabel?: string;
+  mapOption?: (row: Row) => BuiltOption;
+}
+
+export interface CrmSearchDataSource<Row = Record<string, unknown>> {
+  data: Row[];
+  rows: Row[];
+  response: unknown;
+  loading: boolean;
+  isLoading: boolean;
+  error: string | boolean;
+  totalCount: number;
+  rowIdField: string;
+}
+
+export interface CrmSearchOptionsDataSource<Row = Record<string, unknown>> extends CrmSearchDataSource<Row> {
+  options: BuiltOption[];
+}
+
+export interface CrmSearchFormField<Field = Record<string, unknown>> extends Record<string, unknown> {
+  type: "select" | "multiselect";
+  options: BuiltOption[];
+  loading?: boolean;
+}
+
+export interface CrmDataTableProps<Row = Record<string, unknown>> extends Omit<DataTableProps<Row>, "data" | "loading" | "error" | "columns" | "searchValue" | "onParamsChange"> {
+  objectType: "contact" | "contacts" | "company" | "companies" | "deal" | "deals" | string;
+  properties?: string[];
+  columns?: DataTableColumn<Row>[];
+  pageLength?: number;
+  serverSide?: boolean;
+  filters?: DataTableProps<Row>["filters"];
+  autoFilters?: boolean | string[] | { fields?: string[] };
+  autoFilterMaxOptions?: number;
+  filterMap?: CrmSearchConfigOptions<Row>["filterMap"];
+  propertyMap?: Record<string, string>;
+  sortMap?: CrmSearchConfigOptions<Row>["sortMap"];
+  searchFields?: string[];
+  format?: Record<string, unknown>;
+  mapRecord?: (record: unknown) => Row;
+  dataTableProps?: Partial<DataTableProps<Row>>;
+}
+
+export interface CrmKanbanProps<Row = Record<string, unknown>>
+  extends Omit<KanbanProps<Row>, "data" | "loading" | "error" | "stages" | "groupBy" | "searchValue" | "filterValues" | "onParamsChange"> {
+  objectType: "contact" | "contacts" | "company" | "companies" | "deal" | "deals" | string;
+  properties?: string[];
+  groupBy: KanbanProps<Row>["groupBy"];
+  /** Pass for real pipeline labels; auto-derived from the batch when omitted. */
+  stages?: KanbanProps<Row>["stages"];
+  /** Friendly labels for auto-derived stages — object map or fn. */
+  stageLabels?: Record<string, string> | ((value: string) => string);
+  pageLength?: number;
+  serverSide?: boolean;
+  autoFilters?: boolean | string[] | { fields?: string[] };
+  autoFilterMaxOptions?: number;
+  filterMap?: CrmSearchConfigOptions<Row>["filterMap"];
+  propertyMap?: Record<string, string>;
+  sortMap?: CrmSearchConfigOptions<Row>["sortMap"];
+  searchFields?: string[];
+  format?: Record<string, unknown>;
+  mapRecord?: (record: unknown) => Row;
+  kanbanProps?: Partial<KanbanProps<Row>>;
+}
+
 export interface DeriveCardFieldsOptions<Row = Record<string, unknown>> {
   titleField?: string;
   titleHref?: (row: Row) => string | { url: string; external?: boolean };