Catalog of `minor` fidelity widenings (TS type vs generated ReScript) for triage — blend 0.0.37-beta.6

[jagguji]

Detailed catalog of minor fidelity findings — generated bindings vs blend 0.0.37-beta.6

Re-validation came back 0 confirmed majors (see #63). This issue lists every minor finding (69 across 36 components) with its TS type vs generated ReScript type, for triage. None is a compile error (build is green) — each is a widening or representation choice. Filed so the team can decide which deserve tighter typing.

Generator: pkg.pr.new@62.

🔎 Worth a closer look (the only ones that lose guarantees, not just precision)

• Discriminated-union flattening — Card (variant/alignment/children), SelectItemV2 (selected/selectedValues), Badge (StandaloneBadgeProps | PositionedBadgeProps): all props present & correctly typed, but emitted all-optional, so per-branch required-ness is lost. Candidate for a real enhancement (e.g. a ReScript variant per branch).
• Everything else is an inherent TS→ReScript gap (CSS/styled-components/generics → string), a convention (| null→optional, ReactNode→React.element, number→int/float), or a documented opaque/overload mapping — all already carry ⚪ loose/ⓘ comments.

Full list

Component	Prop	TS type	Generated ReScript	Why minor
AvatarGroup	avatars[].fallback	string | React.ReactNode	React.element	AvatarData.fallback is string | React.ReactNode in TS; binding (AvatarGroupTypes.avatarData.fallback) maps it to React.element only, dr…
AvatarV2	onImageError	(error: Error) => void	JsError.t => unit	TS (error: Error) => void mapped to JsError.t => unit — faithful arity/return. No defect.
AvatarV2	width / height	CSSObject['width']	string	TS AvatarV2Dimensions uses CSSObject['width']/['height'] (Property.Width | number | undefined). Binding widens to string. Acceptable sty…
Badge	BadgeProps union	StandaloneBadgeProps | PositionedBadgeProps	single flattened props	TS BadgeProps is a discriminated union (StandaloneBadgeProps with children:undefined | PositionedBadgeProps with required children/positi…
Badge	offset	[number, number]	string	TS PositionedBadgeProps.offset is [number, number] tuple; binding maps to string with an explicit // ⚪ loose comment. Documented limit…
Button	(spread) HTML attributes	& Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'style' | 'className'>	...HtmlAttrs.buttonHTMLAttributesOmitClassNameDisabledOnClickStyle	Binding additionally omits disabled and onClick from the spread because they are explicitly declared as own props; this is correct de-dupl…
Button	justifyContent	CSSObject['justifyContent'] (styled-components CSS union)	justifyContent?: string	styled-components CSS property union widened to string. Known-acceptable widening of a styled-components type.
Button	onClick	onClick?: (event?: React.MouseEvent<HTMLButtonElement>) => void (a SINGLE optional-arg signature)	onClick?: ButtonTypes.OnClick.t (opaque) with comment '// was overloaded function (2 call signatures)'	The TS source has exactly one call signature, not two; the bindgen comment claiming '2 call signatures / overloaded' is inaccurate for thi…
Card	variant / alignment / children	CardProps = {maxWidth?,maxHeight?,minHeight?,skeleton?} & (DefaultCardProps | AlignedCardProps | CustomCardProps); discriminated union where alignment is required in AlignedCardProps, children required in CustomCardProps, and variant is the discriminant (required in Aligned/Custom).	all flattened into one make signature with every prop optional: ~variant=?, ~alignment=?, ~children=?, etc.	The discriminated union of the three card shapes is flattened into a single all-optional argument list. This loosens optionality (e.g. Ali…
CodeEditorV2	onBlur	onBlur?: () => void	onBlur?: EditorSharedTypes.OnBlur.t (opaque, with asThunk/asEvent helpers)	TS CodeEditorV2Props declares onBlur as a plain () => void, but the intersected Omit<React.HTMLAttributes,'style'|'className'|'onChang…
CodeEditorV2	onFocus	onFocus?: () => void	onFocus?: EditorSharedTypes.OnFocus.t (opaque, with asThunk/asEvent helpers)	Same overloaded-function widening as onBlur (HTMLAttributes onFocus not omitted in the Omit). Documented with ⓘ comment and OnFocus.asTh…
CoreChart	data / hoveredKey / onHoveredKeyChange	NewNestedDataPoint[] | null	Nullable.t<array<ChartsTypes.newNestedDataPoint>>=?	TS NewNestedDataPoint[] | null and string | null modeled as Nullable.t<...> — faithful (null preserved). colors: {key;color}[] -> …
DataTable	columnManagerAlwaysSelected	(keyof T)[]	string	TS is (keyof T)[] (an array); binding widens to a plain string (not array) with // ⚪ loose — was (keyof T)[]. The array-ness…
DataTable	columns	ColumnDefinition<T>[]	string	ColumnDefinition<T>[] widened to string with a // ⚪ loose comment — documented generic limitation (known-acceptable).
DataTable	data / columns / idField	—	—	Required props correctly emitted without =?. data:T[]->array<'a>, onRowSave/onRowClick/isRowLoading/getRowStyle arities and returns correc…
DataTable	idField	keyof T	string	keyof T widened to string with // ⚪ loose — documented (known-acceptable).
DataTable	onColumnReorder / onFieldChange / onHeaderChange / onOperations / onInsertLeft / onInsertRight / onDeleteColumn	(ColumnDefinition<T>[]) => void / (keyof T) => void	'b => unit (with ⓘ comment)	Callbacks whose param is ColumnDefinition<T>[] or keyof T are emitted as bare type variables ('b, 'c, 'd, 'e, 'f, 't6, 't7) with an ex…
DateRangePicker	customPresets	PresetsConfig	string	PresetsConfig (union array of DateRangePreset|CustomPresetConfig|CustomPresetDefinition) widened to string with `// ⚪ loose — was Pres…
Drawer	activeSnapPoint / onSnapPointChange	number | string | null	CommonTypes.stringOrNumber=?	TS number | string | null modeled as CommonTypes.stringOrNumber (the null member is dropped). Cosmetic union narrowing; the number|…
DrawerPortal	container	HTMLElement | DocumentFragment | null	~container: Dom.element=?	vaul Portal container TS type is HTMLElement | DocumentFragment | null; binding widens to non-nullable Dom.element and carries an explic…
DrawerV2	activeSnapPoint	number | string | null	CommonTypes.stringOrNumber=?	TS number | string | null; binding uses non-nullable CommonTypes.stringOrNumber. null not representable, but prop is optional. Minor.
DrawerV2	container	HTMLElement | null	Nullable.t<Dom.element>=?	TS HTMLElement | null correctly mapped to Nullable.t<Dom.element>=?. Faithful.
DrawerV2	onDrag/onRelease	(event: React.PointerEvent<HTMLDivElement>, n: number|open: boolean) => void	('a, float) => unit / ('b, bool) => unit	PointerEvent first arg could not be modelled; received as type variable ('a/'b) with explicit ⓘ comment. Second args (floa…
DrawerV2	setActiveSnapPoint	(snapPoint: number | string | null) => void	CommonTypes.stringOrNumber => unit=?	TS is (snapPoint: number | string | null) => void; binding types arg as CommonTypes.stringOrNumber (string|float) dropping the null bra…
DrawerV2NestedRoot	activeSnapPoint	—	—	TS: number | string | null. Bound as CommonTypes.stringOrNumber (optional). The explicit null member is dropped (undefined handled by …
DrawerV2NestedRoot	onDrag	—	—	TS: (event: React.PointerEvent, percentageDragged: number) => void. Bound as ('a, float) => unit with a documented `ⓘ para…
DrawerV2NestedRoot	onRelease	—	—	TS: (event: React.PointerEvent, open: boolean) => void. Bound as ('b, bool) => unit with the documented type-variable comm…
DrawerV2NestedRoot	setActiveSnapPoint	—	—	TS: (snapPoint: number | string | null) => void. Bound as CommonTypes.stringOrNumber => unit; null member dropped. Minor.
DrawerV2NestedRoot	snapPoints / fadeFromIndex	—	—	DialogProps is intersected with (WithFadeFromProps | WithoutFadeFromProps). Binding flattens both into optional snapPoints: array<stringO…
MenuV2	triggerProps	Omit<ButtonHTMLAttributes,'className'|'style'>	record spreading JsxDOM.domProps	TS is Omit<React.ButtonHTMLAttributes,'className'|'style'>. Binding maps to ReactTypes.reactPrimaryActionButtonPropsCo…
MenuV2Content	onInteractOutside	(e: unknown) => void	JSON.t => unit	TS (e: unknown) => void mapped to JSON.t => unit (same for onPointerDownOutside). Reasonable representation of an opaque event arg. alignm…
PivotTableModal	columns	ColumnDefinition<T>[]	string // ⚪ loose	TS ColumnDefinition<T>[] widened to string with documented // ⚪ loose comment. Known-acceptable generic limitation.
PivotTableModal	data	T[]	array<'a>	TS T[] (T extends Record<string,unknown>) mapped to array<'a>. Reasonable generic handling.
PivotTableModal	onConfigChange/onExport	(config: PivotTableConfig<T>) => void	DataTableTypes.dataTableOnConfigChangeConfig => unit	TS (config: PivotTableConfig<T>) => void mapped to DataTableTypes.dataTableOnConfigChangeConfig => unit. Generic config approximated by …
ResponsiveText	as	React.ElementType	ReactTypes.ElementType.t	TS React.ElementType mapped to ReactTypes.ElementType.t (opaque) with an inline doc comment explaining construction helpers. Faithful/know…
ResponsiveText	fontSize / color / fontWeight	CSSObject['fontSize'] | CSSObject['color'] | CSSObject['fontWeight']	string	TS types are CSSObject['fontSize'] / CSSObject['color'] / CSSObject['fontWeight'] (styled-components indexed access). Binding widens all t…
SelectItemV2	itemTokens	CSSObject['paddingTop'] etc. (string | number | undefined union)	string	SelectV2MenuItemTokensBase CSSObject-valued fields (paddingTop, margin, borderRadius, fontSize, fontWeight, color, backgroundColor, etc.) …
SelectItemV2	selected / selectedValues	selected: string (required when mode='single'); selectedValues: string[] (required when mode='multi')	~selected: string=?, ~selectedValues: array<string>=?	TS SelectItemV2Props is a discriminated union (SingleSelectItemV2Props | MultiSelectItemV2Props). In the single branch selected: string…
SingleSelect	items[].tooltip	string | React.ReactNode	React.element	SelectMenuItemType.tooltip is string | React.ReactNode; binding maps tooltip to React.element. Since string is a valid ReactNode this i…
SingleSelectV2Menu	collisionBoundary	Element | Element[] | null	ChatInputTypes.CollisonBoundaryRef.t	TS type is DropdownMenuContentProps['collisionBoundary'] (Element | Element[] | null). Widened to an opaque ChatInputTypes.CollisonBound…
StatCardV2NoData	filteredProps	React.ComponentProps<'div'> (DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>)	string	Widened to string with a documented // ⚪ loose comment. TS type is React.ComponentProps<'div'>. Known-acceptable documented limitati…
StyledCheckboxIndicator	as_	as?: AsTarget (optional)	~as_: string (required)	TS as (AsTarget) is optional but binding marks ~as_ as required (no =?). Cosmetic optionality mismatch on a loose-widened prop.
StyledCheckboxIndicator	theme/as_/forwardedAs/style + return	FastOmit<Substitute<...>> union	string	styled-components IStyledComponentBase<Substitute<FastOmit<CheckboxIndicatorProps & RefAttributes, ...>>> widened to stri…
StyledCheckboxRoot	as_	as?: AsTarget (optional)	~as_: string (required)	TS as (AsTarget) optional but binding marks ~as_ as required (no =?).
StyledCheckboxRoot	theme/as_/forwardedAs/style + return	FastOmit<Substitute<...>> union	string	styled-components IStyledComponentBase<Substitute<FastOmit<CheckboxProps & RefAttributes, ...>>> widened to string with…
StyledRadioV2Root	as_	as?: AsTarget (optional)	~as_: string (required)	TS as (AsTarget) optional but binding marks ~as_ as required (no =?).
StyledRadioV2Root	theme/as_/forwardedAs/style + return	Substitute<DetailedHTMLProps<...>> union	string	styled-components IStyledComponentBase<Substitute<DetailedHTMLProps<InputHTMLAttributes>, ...>> widened to string with '…
StyledTabsContent	as_	as?: AsTarget (optional)	~as_: string (required)	TS as (AsTarget) optional but binding marks ~as_ as required (no =?).
StyledTabsContent	theme/as_/forwardedAs/style + return	Substitute<FastOmit<TabsContentProps...>> union	string	styled-components IStyledComponentBase<Substitute<TabsContentProps & RefAttributes, ...>> widened to string with '// ⚪ loo…
StyledTabsList	as_	as?: AsTarget (optional)	~as_: string (required)	TS as (AsTarget) optional but binding marks ~as_ as required (no =?).
StyledTabsList	theme/as_/forwardedAs/style + return	Substitute<FastOmit<TabsListProps...>> union	string	styled-components IStyledComponentBase<Substitute<TabsListProps & RefAttributes, ...>> widened to string with '// ⚪ loose'…
StyledTabsRoot	as_	as?: AsTarget (optional)	~as_: string (required)	TS as (AsTarget) optional but binding marks ~as_ as required (no =?).
StyledTabsRoot	theme/as_/forwardedAs/style + return	FastOmit<TabsProps & RefAttributes<...>> union	string	Bound to exported StyledTabs (TabsProps & RefAttributes) — IStyledComponentBase widened to string with '// ⚪ loose' commen…
StyledTabsTrigger	as_	as?: AsTarget (optional)	~as_: string (required)	TS as (AsTarget) optional but binding marks ~as_ as required (no =?).
StyledTabsTrigger	theme/as_/forwardedAs/style + return	Substitute<FastOmit<TabsTriggerProps...>> union	string	styled-components IStyledComponentBase<Substitute<TabsTriggerProps & RefAttributes, ...>> widened to string with '// ⚪ …
TabsContent	forceMount	forceMount?: true (literal)	~forceMount: bool=?	TS Radix TabsContentProps types forceMount as the literal true (forceMount?: true); binding widens it to bool. Cosmetic widening; the on…
TabsV2Content	forceMount	forceMount?: true	~forceMount: bool=?	TS type is the literal true (forceMount?: true); binding widens to bool=?. Harmless widening of a single-literal flag.
TabsV2Content	value	value: string (required)	~value: string	Radix TabsContentProps.value is required (value: string); binding correctly marks ~value: string as required. Correct.
TabsV2IconContainer	as_	as?: AsTarget	~as_: string (required)	~as_ is emitted as required (no =?), but styled-components as is optional. Minor optionality cosmetic on a loose-widened prop.
TabsV2IconContainer	theme/as/forwardedAs/style	DefaultTheme | styled-component union	string (loose)	Styled-components span. theme/as/forwardedAs/style and return widened to string with documented // ⚪ loose comments — known-acceptable f…
Tag	BlockProps style props	BlockProps	flattened block style props	Tag extends Omit<BlockProps,'children'>; the many flattened style props (CSSObject string values, stringOrNumber for padding/margin) are r…
Tag	color	TagColor enum	~color: SplitTagTypes.color2=?	TS color?: TagColor (neutral|primary|success|error|warning|purple). Binding uses SplitTagTypes.color2 which is a polyvariant with tho…
Tag	size	TagSize enum	~size: TagsTypes.size2=?	TS size?: TagSize (xs|sm|md|lg). Binding uses TagsTypes.size2 = xs|sm|md|lg — exact members match; alias-name duplication only.
Tag	text	text: string (required)	~text: string	Required prop text: string correctly emitted as ~text: string (non-optional). Correct.
Tag	variant/shape/leftSlot/rightSlot/splitTagPosition/showSkeleton/skeletonVariant	TagProps extras	faithful	All present & correct: variant->tagVariant(noFill|attentive|subtle), shape->tagShape(rounded|squarical), splitTagPosition->left|right,…
TextArea	wrap	CSSObject['whiteSpace']	string	TS type is CSSObject['whiteSpace'] (a styled-components CSS union); widened to plain string in the binding. This is a reasonable/accepta…
TextInputV2	dropdown	TextInputV2Dropdown | TextInputV2Dropdown[]	string	TS type is TextInputV2Dropdown | TextInputV2Dropdown[] (SingleSelectV2Props & {position}). Widened to string placeholder, but carries…
ThemeProvider	foundationTokens	ThemeType	'a	TS type is ThemeType but the binding uses a free type variable 'a instead of a concrete record/type. This is a widening (accepts anythin…
UnitInput	value	number | undefined (required key)	value: float (required)	TS type is number | undefined on a non-optional key. Binding maps to required value: float, dropping the undefined value possibilit…

[jagguji]

Triaged all 69 findings. 4 fixed, 1 deferred (by-design), the rest are inherent/convention/documented (no action). Pushed to PR #62.

✅ Fixed

Finding	TS	Before	After
B5 Badge.offset (+ general: no tuple support)	[number, number]	string	(float, float) — TS tuples now map to ReScript tuples (variadic/optional-element/1-tuples stay string)
B2 Drawer/DrawerV2 snap-points	number | string | null	stringOrNumber (null dropped)	Nullable.t<stringOrNumber> — | null recovered on multi-type unions too (props + callbacks)
B1 UnitInput.value	number | undefined (required key)	value: float (required)	value?: float — merged-prop optionality now taken from the first-party signature (own | undefined wins over @types/react's value?)
B4 Button.onClick	(event?: MouseEvent) => void	opaque OnClick.t + wrong "2 sigs" note	option<ReactEvent.Mouse.t> => unit — a single first-party signature (merged with the inherited MouseEventHandler) isn't a real overload

⏸️ Deferred (by-design)

• B3 columnManagerAlwaysSelected: (keyof T)[] → string. This is the flag-don't-fake contract: emit collapses any opaque-containing type to a flat string placeholder rather than a half-faked array<string> (the element keyof T isn't a plain string). Sibling ColumnDefinition<T>[] is already accepted the same way. Left as-is.

🧩 Not done — needs sign-off

• C1 Discriminated-union props (Card/SelectItemV2/Badge) flatten to all-optional. A faithful fix = a ReScript variant per branch, which changes the generated API shape (consumers construct a variant) + golden/benchmark rework. Reasonable default as-is; happy to take it on if you want it.

⚪ Accept as-is (≈50 rows)

CSS/styled-components → string, generics (keyof T, ColumnDefinition<T>) → string, ReactNode→React.element, number→int/float, forceMount?: true→bool, opaque/overload modules — all inherent TS→ReScript gaps or conventions, already carrying ⚪ loose/ⓘ comments.

Verification: full blend compiles (0 broken); all 54 golden cases match + compile (new fixture tuples, extended nullable-fields); npm run bench green on all 8 packages (metrics equal-or-better), baselines updated. B1/B4 (first-party-vs-@types/react merges) are locked by the blend benchmark baseline; B5/B2 by goldens. docs/TYPE_MAPPING.md rows added for each.

[jagguji]

Re-validation after the #65 fixes — 0 majors, residual minors triaged ✅

Re-ran the full 209-component review against the latest pkg.pr.new@62 (commits 47d0239b tuples, 3248faf8 multi-type | null recovery, 622787a7 merged-prop optionality, 999c1f01 single-sig-is-not-an-overload). Compiles + formats clean, 0 broken, 0 major, 0 unverifiable. (170 faithful · 39 minor.)

Fixed from this catalog ✅

• Tuples: Badge.offset → (float, float) (was string).
• Fake overloads: Button.onClick, CodeEditorV2.onBlur/onFocus → proper single signatures (option<…> => unit), no longer opaque OnClick.t/OnBlur.t.
• Nullability: multi-type | null now recovered.
• (SingleSelectV2VirtualList.virtualItems.key — the key is back; now only a string vs string|number|bigint narrowing.)

Remaining ~minors — almost all inherent TS→ReScript gaps (WONTFIX-class)

CSS/styled-components → string (all Styled*, *Dimensions, Skeleton*), generics (keyof T, ColumnDefinition<T>[]), unmodelable PointerEvent callback params → type variables, ReactNode→React.element, opaque collision-boundary unions, literal true→bool. All carry ⚪ loose/ⓘ comments.

The only ones genuinely "could be better" (not bugs)

1. Discriminated-union flattening — Card (variant/alignment/children), SelectItemV2 (selected/selectedValues), Badge: per-branch required props emitted optional. Real enhancement candidate (variant-per-branch). (Main item.)
2. Required-but-| undefined → optional — e.g. BreadcrumbV2List.base (IndexedBreadcrumbChild | undefined, required key) emitted =?. Could be a required option<…>.
3. Multi-type literal narrowing — SingleSelectV2VirtualList.key: string | number | bigint → string.
4. number→int heuristic partial — count/index-named props become int while siblings like maxCount stay float (looks inconsistent; deliberate).

From this repo's side the bindings for blend@0.0.37-beta.6 are correct and usable. Items 1–4 are quality nice-to-haves, not blockers. 🙏

[jagguji]

New major (1.2.0) — union-of-array types mis-emitted as a {...JsxDOM.domProps} record

Found validating 1.2.0 against blend@0.0.37-beta.0 (95 components: 83 faithful, 11 minor, 1 major). The "intersection of arrays → array" fix (7a17e3ed) doesn't cover the union-of-arrays case.

DateRangePicker.customPresets

TS (DateRangePicker/types.d.ts:163, used at :253):

export type PresetsConfig =
  | DateRangePreset[]
  | CustomPresetConfig[]
  | CustomPresetDefinition[]
  | (DateRangePreset | CustomPresetConfig | CustomPresetDefinition)[];
// ...
customPresets?: PresetsConfig;

Generated (src/DateRangePicker.res + DateRangePickerTypes.res):

~customPresets: DateRangePickerTypes.presetsConfig=?,
// where:
type presetsConfig = {
  ...JsxDOM.domProps,
}

A union whose every member is an array is mistyped as a DOM-props object record — wrong shape (object vs array), wrong contents (HTML attrs vs presets), and no ⚪ loose/⚠️ REVIEW comment, so it reads as a real binding rather than a documented widening.

Inconsistency worth noting

The same PresetsConfig type, when generating blend@0.0.37-beta.6, widened to a documented string (// ⚪ loose — was PresetsConfig) — i.e. handled correctly-ish there. So the output for this type differs by input version / context, and the {...JsxDOM.domProps} fallback is the wrong branch.

Suggested fix

Treat a union where all members are array types like the intersection case — emit array<…> (widen the element to string/loose if the element union can't be modelled), or at minimum fall back to the documented string + ⚪ loose path rather than the {...JsxDOM.domProps} record fallback.

Repro

npm i -D @juspay/rescript-bindgen@1.2.0
npm i --no-save @juspay/blend-design-system@0.0.37-beta.0
npx rescript-bindgen --pkg @juspay/blend-design-system --node-modules ./node_modules \
  --no-install --out src --project . --webapi --report --clean --yes
grep -n customPresets src/DateRangePicker.res        # ~customPresets: DateRangePickerTypes.presetsConfig=?
grep -n -A2 'presetsConfig =' src/DateRangePickerTypes.res   # { ...JsxDOM.domProps }