hs-uix 1.5.1 → 1.6.0

package/README.md

@@ -29,6 +29,9 @@ Requires `react` >= 18.0.0 and `@hubspot/ui-extensions` >= 0.12.0 as peer depend
 |-----------|-------------|------|
 | **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 | See the [Kanban section](#kanban) below |
+| **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) |
 
 ---
 
@@ -192,6 +195,224 @@ const fields = [
 
 ---
 
+# Kanban
+
+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)
+
+## Quick Start
+
+```jsx
+import { Kanban } from "hs-uix/kanban";
+import { AutoTag } from "hs-uix/common-components";
+import { formatCurrencyCompact, formatDate } from "hs-uix/utils";
+
+const STAGES = [
+  { value: "qualified",     label: "Qualified",      variant: "info" },
+  { value: "proposal",      label: "Proposal",       variant: "info" },
+  { value: "negotiation",   label: "Negotiation",    variant: "warning" },
+  { value: "closed_won",    label: "Closed Won",     variant: "success", terminal: true },
+  { value: "closed_lost",   label: "Closed Lost",    variant: "default", terminal: true },
+];
+
+const CARD_FIELDS = [
+  { field: "name",      placement: "title" },
+  { field: "company",   placement: "subtitle" },
+  { field: "amount",    placement: "meta",   render: (val) => formatCurrencyCompact(val) },
+  { field: "segment",   placement: "body",   render: (val) => <AutoTag value={val} /> },
+  { field: "closeDate", placement: "footer", render: (val) => formatDate(val) },
+];
+
+<Kanban
+  data={deals}
+  stages={STAGES}
+  groupBy="stage"
+  cardFields={CARD_FIELDS}
+  onStageChange={(row, newStage) => updateDealStage(row.id, newStage)}
+/>
+```
+
+## Features
+
+- **Stage-based columns** with variant-colored headers (`success` / `warning` / `info` / `default`), collapse-to-rail, and stage-level count badges
+- **`cardFields` with placement** (`title` / `subtitle` / `meta` / `body` / `footer`) — same render/truncate/visible hooks as DataTable columns
+- **Filters and sort** with the same config shape as DataTable (`select`, `multiselect`, `dateRange`)
+- **Headline metrics** rendered above the board (deal totals, weighted pipeline, win rate) via a `metrics` prop
+- **Stage transition prompts** — async confirmation or extra-property capture before committing a stage change, declared per-stage via `stage.onEnterRequired.render`
+- **Selection bar + card actions** for bulk moves, deletes, or custom handlers (`KanbanCardActions`)
+- **Empty / loading / error render slots** that mirror DataTable's override API
+- **Paired view adapters** — use `deriveCardFieldsFromColumns` from `hs-uix/utils` to project a DataTable `columns` config into Kanban `cardFields` with a single function call
+
+## Highlights
+
+### 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)
+
+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)
+
+### Compact lead board
+
+![Kanban — Compact lead board preset](https://raw.githubusercontent.com/05bmckay/hs-uix/main/packages/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)
+
+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.
+
+---
+
+# Common Components
+
+Thin, composable visual wrappers built on HubSpot's native primitives — the reusable pieces that show up across DataTable rows, FormBuilder cells, and Kanban cards. Use them to skip rewriting the same status-tag / avatar-stack / label-value block on every surface.
+
+## Quick Start
+
+```jsx
+import {
+  AutoStatusTag,
+  AutoTag,
+  AvatarStack,
+  SectionHeader,
+  KeyValueList,
+  StyledText,
+  HS_DATE_PRESETS,
+} from "hs-uix/common-components";
+import { formatCurrency } from "hs-uix/utils";
+
+<SectionHeader
+  title="Deal Summary"
+  description="A compact summary block using common components."
+/>
+
+<KeyValueList
+  items={[
+    { label: "Status", value: <AutoStatusTag value="At risk" /> },
+    { label: "Segment", value: <AutoTag value="Enterprise" /> },
+    { label: "Owners", value: <AvatarStack items={["AR", "JK", "SP", "MB", "LM"]} maxVisible={4} /> },
+    { label: "Pipeline", value: formatCurrency(245000) },
+  ]}
+/>
+```
+
+## What's inside
+
+- `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`
+- `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
+
+Plus low-level builders (`makeAvatarStackDataUri`, `makeStyledTextDataUri`) that return `{ src, width, height }` for composing into larger SVGs, and style constants (`HS_FONT_FAMILY`, `HS_TEXT_COLOR`, `HS_SUBTLE_BG`, `HS_MUTED_TEXT`, `HS_NEUTRAL_CHIP`) that mirror HubSpot's native CSS — so custom SVGs sit alongside the rest of the UI without a color mismatch.
+
+## Highlights
+
+### AutoTag & AutoStatusTag
+
+![AutoTag variants](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/common-components/assets/auto-tag.png)
+
+![AutoStatusTag variants](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/common-components/assets/auto-status-tag.png)
+
+Pass a free-form status string and get a properly-colored tag back. Matching is case-insensitive and tolerates underscores / dashes / phrases (`"in_progress"`, `"on hold"`, `"at-risk"` all resolve). Override via `overrides={{ "Processing": "warning" }}` and `fallback="info"` for values that don't match built-in heuristics.
+
+### AvatarStack
+
+![Avatar stack](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/common-components/assets/avatar-stack.png)
+
+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.
+
+### SectionHeader & KeyValueList
+
+![KeyValueList](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/common-components/assets/key-value-list.png)
+
+Pair `SectionHeader` (title / description / action slot) with `KeyValueList` (`DescriptionList` rows) for compact summary panels. `direction="column"` on the list switches to stacked label-on-top rows.
+
+### StyledText
+
+![Styled text](https://raw.githubusercontent.com/05bmckay/hs-uix/main/src/common-components/assets/styled-text.png)
+
+Reach for `StyledText` when native `<Text>` can't do what you need: vertical rail labels (`orientation="vertical-down"`), HubSpot-style pill badges (`background={{ preset: "tag" }}`), or a specific glyph color. Plain horizontal `preset: "tag"` usage renders through native HubSpot `Tag`; rotated/custom tag cases still use the SVG fallback. Use native `<Text>` anywhere copy-paste matters.
+
+### HS_DATE_PRESETS
+
+HubSpot's native quick-date preset list (`Today`, `Last 7 days`, `This quarter`, …) as a ready-to-use `options` array for `DataTable` / `Kanban` select filters. Values are stable identifiers (`"today"`, `"7d"`, `"this_quarter"`) — translate to date bounds via `filterFn` or server-side in `onFilterChange`.
+
+---
+
+# Utils
+
+Pure helper functions for formatting values, building option arrays, detecting HubSpot-shaped date/time objects, and inferring tag variants from raw data. Zero side effects, no JSX — drop them into `renderCell`, `sortComparator`, or a server handler.
+
+## Quick Start
+
+```jsx
+import {
+  formatCurrency,
+  formatCurrencyCompact,
+  formatDate,
+  formatDateTime,
+  formatPercentage,
+  buildOptions,
+  findOptionLabel,
+  getAutoTagVariant,
+  createStatusTagSortComparator,
+  sumBy,
+} from "hs-uix/utils";
+
+formatCurrency(1234.56);              // → "$1,235"
+formatCurrencyCompact(123_580_000);   // → "$123.6M"
+formatDate("2026-04-15");             // → "Apr 15, 2026"
+formatPercentage(0.1567);             // → "16%"
+
+const statusOptions = buildOptions(
+  [{ name: "Open", id: "o" }, { name: "Closed", id: "c" }],
+  { labelKey: "name", valueKey: "id" },
+);
+findOptionLabel(statusOptions, "o"); // → "Open"
+
+getAutoTagVariant("At risk");         // → "warning"
+sumBy(deals, "amount");               // → total
+```
+
+## What's inside
+
+- **`formatters.js`** — locale-aware `Intl`-based number / currency / date / percentage formatters. Every formatter accepts a trailing options object that spreads into the underlying `Intl` call, so anything `Intl.NumberFormat` supports (narrow symbol, specific fraction digits, grouping) is reachable without a new helper.
+- **`options.js`** — `buildOptions(items, opts?)` to shape raw arrays into `{ label, value }` for HubSpot `Select` / `MultiSelect`; `findOptionLabel(options, value, fallback?)` for the reverse lookup.
+- **`hubspotValues.js`** — type guards for HubSpot's `DateInput` / `TimeInput` / `DateTimeInput` value shapes (`isDateValueObject`, `isTimeValueObject`, `isDateTimeValueObject`). Use in `filterFn` or `sortComparator` to distinguish a HubSpot date-object from a raw string/Date.
+- **`tagVariants.js`** — heuristic mappers from free-form status strings to semantic tag variants (`getAutoTagVariant`, `getAutoStatusTagVariant`, `getAutoTagDisplayValue`) plus `createStatusTagSortComparator` for DataTable columns grouped by color, then alphabetical within each color.
+- **`collections.js`** — `sumBy(items, keyOrFn)` for total / weighted-total rows, safe against `null` / missing values.
+
+## Highlights
+
+### Formatters
+
+```js
+formatCurrency(9500, { currency: "EUR" });            // → "€9,500"
+formatCurrencyCompact(4160);                          // → "$4.2K"
+formatDate(Date.now(), { month: "numeric" });         // → "4/15/2026"
+formatDateTime("2026-04-15T14:30:00Z");               // → "Apr 15, 2026, 9:30 AM" (local)
+formatPercentage(0.1567, { maximumFractionDigits: 1 });// → "15.6%"
+```
+
+Every formatter treats `null` / `undefined` as safe — `formatCurrency(null)` → `"$0"`, `formatDate(null)` → `""` — so they're safe to drop into cells rendering partially-loaded data.
+
+### Tag Variants
+
+The same inference that powers `AutoTag` / `AutoStatusTag`, exposed as plain functions for use in custom cells and sort comparators. Default ordering: `success → warning → danger/error → info → default`; override via `variantOrder` on `createStatusTagSortComparator`.
+
+### Options & HubSpot Value Guards
+
+Build select options from CRM records, resolve labels back to values, and detect HubSpot's structured date/time value objects in one import — no more ad-hoc `.map(r => ({ label: r.name, value: r.id }))` at every call site.
+
+---
+
 ## Migrating from `@hs-uix/datatable` or `@hs-uix/form`
 
 Both packages have been merged into `hs-uix`. Update your imports:

package/common-components.d.ts

@@ -49,7 +49,134 @@ export interface KeyValueListProps {
   gap?: string;
 }
 
+export interface DatePresetOption {
+  label: string;
+  value: string;
+}
+
+export interface DateDirectionLabels {
+  asc: string;
+  desc: string;
+}
+
+export interface AvatarStackItemObject {
+  letter?: string;
+  color?: string;
+  src?: string;
+}
+
+export type AvatarStackItem = string | AvatarStackItemObject;
+
+export interface AvatarStackDataUriResult {
+  src: string;
+  width: number;
+  height: number;
+  count: number;
+}
+
+export interface AvatarStackProps {
+  items?: AvatarStackItem[] | null;
+  size?:
+    | number
+    | "xs"
+    | "extra-small"
+    | "sm"
+    | "small"
+    | "md"
+    | "med"
+    | "medium"
+    | "lg"
+    | "large"
+    | "xl"
+    | "extra-large";
+  overlap?: number;
+  step?: number;
+  maxVisible?: number;
+  colors?: string[];
+  overflowBg?: string;
+  overflowColor?: string;
+  fontFamily?: string;
+  alt?: string;
+}
+
+export interface StyledTextFormat {
+  fontWeight?: "bold" | "demibold" | "regular" | number;
+  italic?: boolean;
+  lineDecoration?: "underline" | "strikethrough";
+  textTransform?: "uppercase" | "lowercase" | "capitalize" | "sentenceCase" | "none";
+}
+
+export interface StyledTextBackground {
+  preset?: "tag";
+  variant?: "default" | "success" | "warning" | "error" | "danger" | "info";
+  color?: string;
+  textColor?: string;
+  borderColor?: string;
+  borderWidth?: number;
+  radius?: number;
+  paddingX?: number;
+  paddingY?: number;
+  height?: number;
+  fontSize?: number;
+  canvasPaddingX?: number;
+  canvasPaddingY?: number;
+}
+
+export interface StyledTextDataUriResult {
+  src: string;
+  width: number;
+  height: number;
+}
+
+export interface StyledTextSharedProps {
+  text?: string;
+  children?: ReactNode;
+  alt?: string;
+  variant?: "bodytext" | "microcopy";
+  format?: StyledTextFormat;
+  orientation?: "horizontal" | "vertical-up" | "vertical-down" | number;
+  color?: string;
+  background?: StyledTextBackground | null;
+  fontFamily?: string;
+  fontSize?: number;
+  paddingX?: number;
+  paddingY?: number;
+  width?: number;
+  height?: number;
+}
+
+export interface StyledTextDataUriOptions extends Omit<StyledTextSharedProps, "children" | "text" | "alt"> {}
+
+export interface StyledTextProps extends StyledTextSharedProps {}
+
 export declare function AutoTag(props: AutoTagProps): ReactNode;
 export declare function AutoStatusTag(props: AutoStatusTagProps): 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 StyledText(props: StyledTextProps): ReactNode;
+export declare function makeAvatarStackDataUri(
+  items?: AvatarStackItem[] | null,
+  options?: Omit<AvatarStackProps, "items" | "alt">
+): AvatarStackDataUriResult | null;
+export declare function makeStyledTextDataUri(
+  text: string,
+  options?: StyledTextDataUriOptions
+): StyledTextDataUriResult;
+
+export declare const HS_DATE_PRESETS: DatePresetOption[];
+export declare const HS_DATE_DIRECTION_LABELS: DateDirectionLabels;
+export declare const HS_FONT_FAMILY: string;
+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;
+export declare const HS_TAG_SUBTLE_BORDER: string;
+export declare const HS_TAG_TEXT_COLOR: string;
+export declare const HS_TAG_FONT_SIZE: number;
+export declare const HS_TAG_LINE_HEIGHT: number;
+export declare const HS_TAG_PADDING_X: number;
+export declare const HS_TAG_PADDING_Y: number;
+export declare const HS_TAG_BORDER_RADIUS: number;
+export declare const HS_TAG_BORDER_WIDTH: number;
+export declare const DEFAULT_SVG_FONT_WEIGHT: number;