hs-uix 2.1.0 → 2.2.0

package/src/experimental/README.md

@@ -0,0 +1,126 @@
+# experimental (`hs-uix/experimental`)
+
+APIs that are shipping for real-world feedback but whose surface may still
+change in a minor release. Graduating components move to their stable subpath
+with a re-export left behind for one minor version.
+
+Currently here:
+
+- **`Wizard` / `OnboardingChecklist`** — re-exported from `hs-uix/wizard`.
+- **`ExperimentalDataTable`** — DataTable with the in-progress row-expansion API.
+- **`Skeleton`** (+ `SkeletonText`, `SkeletonBox`, `SkeletonCircle`,
+  `SkeletonTable`, `makeSkeletonDataUri`, `SKELETON_WIDTH_TOKENS`) — loading
+  placeholders, documented below.
+
+---
+
+## Skeleton
+
+Content placeholders for loading states. `Spinner` says "something is
+happening"; `Skeleton` holds the **shape** of the incoming content so the
+layout doesn't jump when data lands. There is no native skeleton component and
+CSS is forbidden, so each placeholder is a gray rounded-rect SVG data URI
+rendered through the native `<Image>` — the same technique as `StyledText` and
+`AvatarStack`.
+
+One component, two modes.
+
+### Wrapper mode (auto) — the default way to use it
+
+Wrap any surface, pass `loading`, done. While loading, `Skeleton` never
+renders its children — it reads each child element's component name and props
+and draws a placeholder with the same footprint; when `loading` flips false
+the children render untouched.
+
+```jsx
+import { Skeleton } from "hs-uix/experimental";
+
+<Skeleton loading={isLoading}>
+  <DataTable data={rows} columns={COLUMNS} pageSize={10} />
+</Skeleton>
+// while loading → a 10-row table skeleton with COLUMNS.length columns
+```
+
+Recognized children and what sizes their placeholder:
+
+| Child | Shape | Sized from |
+|---|---|---|
+| `DataTable` / `CrmDataTable` | table rows | `columns.length` / `properties.length`, `pageSize` |
+| native `Table` | table rows | 4 × 3 default |
+| `Kanban` / `CrmKanban` | board columns of cards | `stages.length` |
+| `Feed` | avatar + text rows | `pageSize` |
+| `FormBuilder` / native `Form` | label + input rows | `fields.length` |
+| `KeyValueList` / `DescriptionList` | label/value pairs | `items.length` / child count |
+| native `Statistics` | metric blocks | child count |
+| native field inputs (`Select`, `Input`, `DateInput`, …) | one label + input row | — |
+| `Button` / `Tag` / `StatusTag` | small pill | — |
+| `BarChart` / `LineChart` / `Calendar` / `Tile` / `Card` / `Image` / … | block | chart/image height |
+| `Text` / `Heading` / `List` | text lines | child count |
+| anything else | text block | `lines` (default 3) |
+
+Native components work because they are remote *string* types (`"Table"`,
+`"Select"`) — the element type is the name. hs-uix components carry explicit
+`displayName`s, so matching survives minified bundles.
+
+Overrides, when the inference isn't what you want:
+
+```jsx
+// Pick the shape yourself…
+<Skeleton loading={isLoading} variant="board" columns={4}>…</Skeleton>
+
+// …or supply your own static blocks
+<Skeleton
+  loading={isLoading}
+  skeleton={
+    <Flex direction="column" gap="md">
+      <SkeletonBox height={48} />
+      <SkeletonText lines={4} />
+    </Flex>
+  }
+>
+  <MyCustomPanel … />
+</Skeleton>
+```
+
+`variant` replaces the inferred shape (`"table" | "board" | "list" | "form" |
+"keyvalue" | "stats" | "input" | "chip" | "block" | "text" | "box" |
+"circle"`); `rows` / `columns` / `lines` / `height` refine it. Multiple
+children each get their own skeleton, stacked in a column.
+
+### Static mode — the building blocks
+
+Without children, `Skeleton` is the placeholder primitive itself, and the
+composite shapes work standalone too:
+
+```jsx
+import {
+  Skeleton,
+  SkeletonText,
+  SkeletonBox,
+  SkeletonCircle,
+  SkeletonTable,
+} from "hs-uix/experimental";
+
+{loading ? <SkeletonText lines={3} width="md" /> : <Text>{description}</Text>}
+
+<Flex direction="row" gap="sm" align="center">
+  <SkeletonCircle size={32} />
+  <SkeletonText lines={2} width="sm" height={10} gap={6} />
+</Flex>
+
+<SkeletonTable rows={5} columns={4} />
+<Skeleton variant="board" columns={3} />   {/* composite variants work statically */}
+```
+
+| Prop | Type | Default | Notes |
+| ---- | ---- | ------- | ----- |
+| `loading` | boolean | `false` | Wrapper mode: gate for `children`. |
+| `skeleton` | node | — | Wrapper mode: your own placeholder; skips inference. |
+| `variant` | shape | `"text"` | Static shape, or inference override in wrapper mode. |
+| `width` | px \| `"sm"`\|`"md"`\|`"lg"` | varies | Tokens = 120 / 240 / 360 (`SKELETON_WIDTH_TOKENS`). |
+| `height` | px | varies | Line height (text), block height (box), diameter (circle). |
+| `lines` / `rows` / `columns` | number | varies | Sizing for text / composite shapes. |
+| `lastLineWidth`, `gap`, `radius`, `columnGap`, `fill`, `alt` | — | — | Primitive styling (see JSDoc). |
+
+`makeSkeletonDataUri(opts)` returns `{ src, width, height }` for composing
+placeholders into larger SVGs.

package/src/experimental/index.d.ts

@@ -0,0 +1,346 @@
+import type { ReactElement, ReactNode } from "react";
+import type { DataTableProps } from "../datatable/index";
+import type {
+  ActiveFilterChipsProps,
+  AutoStatusTagProps,
+  AutoTagProps,
+  AvatarStackProps,
+  CollectionCountProps,
+  CollectionFilterControlProps,
+  CollectionSortSelectProps,
+  CollectionToolbarProps,
+  CrmLookupSelectProps,
+  CrmRecordPickerCreateOptionRules,
+  CrmRecordPickerId,
+  CrmRecordPickerOption,
+  CrmRecordPickerOptionConfig,
+  CrmRecordPickerProps,
+  CrmRecordPickerRecord,
+  CrmRecordPickerSelection,
+  CrmRecordPickerValue,
+  FormatCollectionCountParams,
+  KeyValueListProps,
+  SectionHeaderProps,
+  StyledTextFormat,
+  StyledTextProps,
+} from "../../common-components";
+
+export * from "../wizard/index";
+
+export interface ExperimentalDataTableRowExpansionProps<
+  Row = Record<string, unknown>,
+  Id = string | number
+> {
+  /** Enables expandable detail rows. Content renders in a full-span row directly under the data row. */
+  renderExpandedRow?: (row: Row) => ReactNode;
+  /** Controlled expansion state — array of expanded row IDs. */
+  expandedRowIds?: Id[];
+  /** Uncontrolled initial expansion state. */
+  defaultExpandedRowIds?: Id[];
+  /** Called with the next expanded id array on every toggle. */
+  onExpandedRowsChange?: (expandedRowIds: Id[]) => void;
+  /** "icon" adds a chevron column; "row" toggles through cell content links. */
+  expandOn?: "icon" | "row";
+  /** Accordion mode — expanding a row collapses the others. */
+  expandSingle?: boolean;
+}
+
+export type ExperimentalDataTableProps<
+  Row = Record<string, unknown>,
+  Id = string | number
+> = DataTableProps<Row, Id> & ExperimentalDataTableRowExpansionProps<Row, Id>;
+
+export declare function DataTable<
+  Row = Record<string, unknown>,
+  Id = string | number
+>(props: ExperimentalDataTableProps<Row, Id>): ReactElement | null;
+
+export { DataTable as ExperimentalDataTable };
+
+// ---------------------------------------------------------------------------
+// Skeleton loading placeholders (experimental)
+// ---------------------------------------------------------------------------
+
+export type SkeletonShape =
+  | "table"
+  | "board"
+  | "list"
+  | "form"
+  | "keyvalue"
+  | "stats"
+  | "input"
+  | "chip"
+  | "block";
+
+export type SkeletonVariant = "text" | "box" | "circle" | SkeletonShape;
+
+/** Pixel number or a width token: sm = 120, md = 240, lg = 360. */
+export type SkeletonWidth = number | "sm" | "md" | "lg";
+
+export interface SkeletonDataUriOptions {
+  variant?: "text" | "box" | "circle";
+  width?: SkeletonWidth;
+  /** Per-line height for "text" (default 12), block height for "box" (default 96), diameter for "circle" (default 40). */
+  height?: number;
+  /** "text" only: number of stacked lines. Default 1. */
+  lines?: number;
+  /** "text" only: final-line width when lines > 1. (0, 1] = fraction of width; > 1 = px; tokens allowed. Default 0.6. */
+  lastLineWidth?: SkeletonWidth;
+  /** "text" only: px between lines. Default 8. */
+  gap?: number;
+  /** Corner radius px (ignored for "circle"). Default 3. */
+  radius?: number;
+  /** "box" only: split the block into N equal cells. Default 1. */
+  columns?: number;
+  /** "box" only: px between cells. Default 16. */
+  columnGap?: number;
+  /** Placeholder color. Default SKELETON_FILL. */
+  fill?: string;
+}
+
+export interface SkeletonDataUriResult {
+  src: string;
+  width: number;
+  height: number;
+}
+
+export interface SkeletonProps extends Omit<SkeletonDataUriOptions, "variant"> {
+  /** Static shape, or the override for the inferred shape in wrapper mode. */
+  variant?: SkeletonVariant;
+  /** Wrapper mode: while true, children are replaced by shape-matched placeholders. Default false. */
+  loading?: boolean;
+  /** Wrapper mode: your own placeholder node(s); skips auto-inference. */
+  skeleton?: ReactNode;
+  /** Wrapper mode: content gated by `loading`. */
+  children?: ReactNode;
+  /** Composite shapes: row count. */
+  rows?: number;
+  /** Accessible label on the underlying <Image>. Default "Loading". */
+  alt?: string;
+  [imageProp: string]: unknown;
+}
+
+export interface SkeletonTextProps extends Omit<SkeletonProps, "variant"> {
+  /** Default 3. */
+  lines?: number;
+  /** Default "md" (240). */
+  width?: SkeletonWidth;
+}
+
+export interface SkeletonBoxProps extends Omit<SkeletonProps, "variant"> {
+  /** Default "md" (240). */
+  width?: SkeletonWidth;
+  /** Default 96. */
+  height?: number;
+}
+
+export interface SkeletonCircleProps
+  extends Omit<SkeletonProps, "variant" | "width" | "height"> {
+  /** Diameter px. Default 40. */
+  size?: number;
+}
+
+export interface SkeletonTableProps {
+  /** Default 4. */
+  rows?: number;
+  /** Cells per row. Default 3. */
+  columns?: number;
+  /** Total row width: px or token. Default "lg" (360). */
+  width?: SkeletonWidth;
+  /** Px height of each row's cells. Default 16. */
+  rowHeight?: number;
+  /** Px between cells within a row. Default 16. */
+  columnGap?: number;
+  /** Flex gap token between rows. Default "sm". */
+  gap?: string;
+  /** Cell corner radius px. Default 3. */
+  radius?: number;
+  fill?: string;
+  /** Accessible label applied to each row image. Default "Loading table". */
+  alt?: string;
+  [flexProp: string]: unknown;
+}
+
+export type SpinnerName =
+  | "braille"
+  | "braillewave"
+  | "dna"
+  | "scan"
+  | "rain"
+  | "scanline"
+  | "pulse"
+  | "snake"
+  | "sparkle"
+  | "cascade"
+  | "columns"
+  | "orbit"
+  | "breathe"
+  | "waverows"
+  | "checkerboard"
+  | "helix"
+  | "fillsweep"
+  | "diagswipe";
+
+export interface SpinnerPreset {
+  frames: readonly string[];
+  interval: number;
+}
+
+export interface SpinnerProps {
+  name?: SpinnerName | string;
+  frames?: readonly string[];
+  interval?: number;
+  label?: ReactNode;
+  children?: ReactNode;
+  paused?: boolean;
+  gap?: string;
+  variant?: "bodytext" | "microcopy";
+  format?: StyledTextFormat;
+  inline?: boolean;
+  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 Icon(props: IconProps): ReactNode;
+/** Custom glyph names registered in this library (excludes native names). */
+export declare const ICON_NAMES: string[];
+/** The custom glyph registry, keyed by icon name. */
+export declare const ICONS: Record<string, IconEntry>;
+/** The native `@hubspot/ui-extensions` `<Icon>` name whitelist, sorted. */
+export declare const NATIVE_ICON_NAME_LIST: string[];
+/** Build an SVG data URI from a registered name or an inline entry. Null for unknown names. */
+export declare function makeIconDataUri(
+  nameOrEntry: string | IconEntry,
+  options?: IconDataUriOptions
+): 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 CrmRecordPicker(props: CrmRecordPickerProps): ReactNode;
+
+/** Sentinel option value for CrmRecordPicker's inline "Create" option. */
+export declare const CREATE_OPTION_VALUE: "__create__";
+/** True when the value looks like a record object (vs a scalar id). */
+export declare function isRecordLike(value: unknown): boolean;
+/** Extract a record's id (objectId | id | hs_object_id | properties.hs_object_id). */
+export declare function getRecordId(record: unknown): CrmRecordPickerId | undefined;
+/** Normalize a picker value (ids and/or records, scalar or array) to { ids, records }. */
+export declare function normalizeRecordSelection(
+  value: CrmRecordPickerValue | null | undefined
+): CrmRecordPickerSelection;
+/** Map a record to a { label, value, description? } option. */
+export declare function recordToPickerOption(
+  record: CrmRecordPickerRecord,
+  config?: CrmRecordPickerOptionConfig
+): CrmRecordPickerOption;
+/** Merge search-page options with selected options so selections stay visible. */
+export declare function mergePickerOptions(
+  options: CrmRecordPickerOption[],
+  selectedOptions?: CrmRecordPickerOption | CrmRecordPickerOption[] | null
+): CrmRecordPickerOption[];
+/** Trim a selection to its first `max` ids (rejects picks beyond the cap). */
+export declare function enforceSelectionMax(
+  ids: CrmRecordPickerId[] | CrmRecordPickerId | null | undefined,
+  max?: number
+): CrmRecordPickerId[];
+/** Injection rules for the inline create option. */
+export declare function shouldShowCreateOption(
+  rules?: CrmRecordPickerCreateOptionRules
+): boolean;
+/** Build the `Create "<term>"` option for a search term. */
+export declare function makeCreateOption(
+  term: string,
+  label?: string | ((term: string) => string)
+): CrmRecordPickerOption;
+/** Split an onChange payload into real ids + whether the create sentinel was chosen. */
+export declare function splitCreateSelection(
+  next: CrmRecordPickerId[] | CrmRecordPickerId | null | undefined
+): { ids: CrmRecordPickerId[]; create: boolean };
+/** Map ids back to records via a Map/object registry; unknown ids become { objectId } stubs. */
+export declare function mapIdsToRecords(
+  ids: CrmRecordPickerId[] | CrmRecordPickerId | null | undefined,
+  recordsById?: Map<CrmRecordPickerId, CrmRecordPickerRecord> | Record<string, CrmRecordPickerRecord>
+): CrmRecordPickerRecord[];
+/** Upsert records into a list deduped by record id (later wins). */
+export declare function upsertRecords(
+  records: CrmRecordPickerRecord[] | null | undefined,
+  additions: CrmRecordPickerRecord | CrmRecordPickerRecord[] | null | undefined
+): CrmRecordPickerRecord[];
+export declare function StyledText(props: StyledTextProps): ReactNode;
+export declare function Skeleton(props: SkeletonProps): ReactNode;
+export declare function SkeletonText(props: SkeletonTextProps): ReactNode;
+export declare function SkeletonBox(props: SkeletonBoxProps): ReactNode;
+export declare function SkeletonCircle(props: SkeletonCircleProps): ReactNode;
+export declare function SkeletonTable(props: SkeletonTableProps): ReactNode;
+/** Build the SVG data URI + intrinsic dimensions for a skeleton placeholder. */
+export declare function makeSkeletonDataUri(
+  options?: SkeletonDataUriOptions
+): SkeletonDataUriResult;
+/** Width tokens accepted anywhere a skeleton takes a `width` (sm/md/lg → px). */
+export declare const SKELETON_WIDTH_TOKENS: { sm: number; md: number; lg: number };

package/src/feed/README.md

@@ -75,6 +75,8 @@ If the primary mental model is “what happened, and when?”, use Feed. If the
 - Built-in item count (`5 of 12 events`) with custom `recordLabel` / `itemCountText`
 - View-more pagination (`pageSize`) plus server/external load-more (`hasMore`, `onLoadMore`)
 - Client-side or server-side mode (`serverSide`) with unified `onParamsChange`
+- Real-time append: `newItemsBehavior="pill"` buffers live arrivals behind a "Show N new items" pill; `highlightNew` marks fresh items with an info `Tag`
+- Per-type display presets (`typePresets` + `DEFAULT_FEED_TYPE_PRESETS`) covering HubSpot's standard activity types with verified native icon names
 - Built-in loading, error, and empty states with render overrides
 - Tile-backed outer/item containers and divider mode
 - Render escape hatches for item, toolbar, and individual item regions
@@ -183,6 +185,64 @@ Feed shows `pageSize` items initially and a transparent “View more” button w
 />
 ```
 
+## Real-time append
+
+Live feeds prepend items while the user is reading. By default (`newItemsBehavior="immediate"`) new items just render. Set `newItemsBehavior="pill"` to hold items that arrive **newer than the previously-newest visible timestamp** in a buffer and show a centered "Show N new items" pill instead — clicking it flushes the buffer into the list:
+
+```jsx
+<Feed
+  items={liveActivity}            // parent prepends as events stream in
+  newItemsBehavior="pill"
+  onNewItemsFlush={(flushed) => console.log(`released ${flushed.length} items`)}
+  highlightNew={30000}            // flushed items carry a "New" tag for 30s
+  sortOptions={[{ value: "newest", label: "Newest first", field: "timestamp", direction: "desc" }]}
+  defaultSort="newest"
+/>
+```
+
+Behavior details (all decided by the pure, exhaustively-tested `partitionNewItems` / `flushBuffer` kernel in `feedLiveBuffer.js`):
+
+- The **first load never buffers** — there is no previous watermark.
+- Only items **strictly newer** than the watermark buffer; equal timestamps and unparseable/missing timestamps stay visible.
+- **Updates to already-visible items (matched by key) never buffer**, even if their timestamp moved forward — a visible row must not vanish into the pill. Give live items stable `id`s; index-based fallback keys defeat update detection.
+- The pill renders even when the visible list is empty (the buffer may hold the only items), and the item count reflects visible items only.
+- `highlightNew={ms}` marks flushed (pill) or freshly-prepended (immediate) items with an info `Tag` ("New") for that window, then clears automatically. `false` (default) disables it. Custom `renderItem` rows bypass the marker.
+- Labels: `labels.newItems` (string or `(count) => string`) and `labels.newItemTag`.
+
+`partitionNewItems(prevNewestTs, items, getTs, { knownIds, getId })`, `flushBuffer(visible, buffered, getTs)`, and `toTimestampMs(value)` are exported for server adapters and tests.
+
+## Per-type presets
+
+Stop repeating `iconName: "calling"` on every call row. `typePresets` maps `item.type` machine values to display defaults, merged **under** item-level values (the item always wins):
+
+```jsx
+import { Feed, DEFAULT_FEED_TYPE_PRESETS } from "hs-uix/feed";
+
+// Built-in HubSpot activity-type presets:
+<Feed items={engagements} typePresets />            // or typePresets={DEFAULT_FEED_TYPE_PRESETS}
+
+// Extend or override:
+<Feed
+  items={engagements}
+  typePresets={{
+    ...DEFAULT_FEED_TYPE_PRESETS,
+    call: { ...DEFAULT_FEED_TYPE_PRESETS.call, statusVariant: "info" },
+    deploy: { icon: "rotate", label: "Deployment" },
+  }}
+/>
+```
+
+A preset fills these item keys when missing: `icon` → `iconName`, `color` → `iconColor`, `label` → `typeLabel`, `statusVariant` → `statusVariant`. Lookup by `type` is case-insensitive and snake_case-normalized, so API values like `"EMAIL"` or `"Postal Mail"` resolve.
+
+`DEFAULT_FEED_TYPE_PRESETS` covers `call`, `email`, `incoming_email`, `forwarded_email`, `meeting`, `note`, `task`, `sms`, `whatsapp`, `linkedin_message`, `postal_mail`, and `conversation` — every icon name is verified against the native HubSpot icon whitelist by a unit test (invalid native icon names render **nothing**).
+
+| Preset key | Description |
+|---|---|
+| `icon` | Native HubSpot icon name (verify against the whitelist — invalid names render nothing) |
+| `color` | Icon color: native enum (`alert`/`warning`/`success`/`inherit`) or any CSS color (SVG fallback) |
+| `label` | Display label used as `typeLabel` |
+| `statusVariant` | `StatusTag` variant fallback: `default`, `info`, `success`, `warning`, `danger` |
+
 ## Server-side mode
 
 Use `serverSide` when the parent/API owns filtering, sorting, searching, and pagination. Feed renders the toolbar and calls back with params, but does not mutate `items`.
@@ -223,4 +283,13 @@ Use `serverSide` when the parent/API owns filtering, sorting, searching, and pag
 
 ## Props
 
+Live-append and preset props:
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `newItemsBehavior` | `"immediate" \| "pill"` | `"immediate"` | `"pill"` buffers strictly-newer arrivals behind a "Show N new items" Button (variant `secondary`, centered) |
+| `onNewItemsFlush` | `(items) => void` | — | Fired with the released items when the pill is clicked |
+| `highlightNew` | `number \| false` | `false` | Window (ms) during which flushed/prepended items carry an info `Tag` "New" marker; initial load is never marked |
+| `typePresets` | `object \| true` | — | `{ [type]: { icon, color, label, statusVariant } }` merged under item values; `true` uses `DEFAULT_FEED_TYPE_PRESETS` |
+
 See `feed.d.ts` for the full typed API.