@ntbjs/react-components 3.0.0-rc.1 → 3.0.0-rc.3

package/styles/utils/colors-export.d.ts

@@ -1,31 +1,12 @@
 /**
  * Hand-written types for colors-export.js.
  *
- * ============================ WHY BY HAND ================================
- * NEVER DERIVE THIS FROM THE .js WITH `keyof typeof`.
- *
- * It works locally, because the library compiles with `allowJs`. It collapses
- * silently in the consumer, which does not: with no `allowJs`, TypeScript cannot
- * read colors-export.js at all, `keyof typeof colors` degrades to
- * `string | number | symbol` WITH NO DIAGNOSTIC, and `colors[name]` inside a
- * template string then emits TS2731 — an error in OUR file, appearing only in
- * THEIR build. A hand-written .d.ts resolves under every `moduleResolution` mode
- * with or without `allowJs`.
- *
- * The cost is that this is a THIRD hand-maintained copy of the palette, beside
- * src/styles/.config.scss and colors-export.js. That is what
- * `npm run verify:palette` (scripts/ts-migration/verify-palette.cjs) is for: it
- * makes drift a build failure rather than a silent `undefined` at runtime. Add a
- * colour to the .js and this union without the other and the gate names it.
- * =========================================================================
- *
- * src/styles stays .js permanently (playbook §A.1) and rollup copies the whole
- * directory verbatim into the published `styles/` and `build/styles/` trees, so
- * this file ships NEXT TO its .js and
- * `@ntbjs/react-components/styles/utils/colors-export` gains types where it
- * previously resolved none. A `.d.ts` is explicitly allowed by
- * scripts/assert-no-published-typescript.cjs for exactly this reason; a `.ts`
- * there would be raw TypeScript in a published package.
+ * Do not derive this from the .js with `keyof typeof`: it works here because the library
+ * compiles with `allowJs`, but a consumer without it degrades the key to
+ * `string | number | symbol` silently and then emits TS2731 in their build, not ours.
+ * The cost is a third hand-maintained copy of the palette beside .config.scss and
+ * colors-export.js, so drift is caught by a build gate rather than at runtime.
+ * It must stay a `.d.ts` — a `.ts` would ship raw TypeScript in the published package.
  */
 
 /**

package/types/components/data/Alert/Alert.styled.d.ts

@@ -1,6 +1,6 @@
 /**
  * Props of the `Alert` root, i.e. what `Alert.tsx` passes to `S.Alert`. Value types come
- * from that file's propTypes; all optional per §J.5.
+ * from that file's propTypes; all optional.
  */
 export interface AlertStyleProps {
     /** `isWarning` — derived in the component from `type === 'warning'`, so `boolean`. */
@@ -17,43 +17,19 @@ export interface AlertStyleProps {
     /** `horizontalPadding` — `PropTypes.number`, px, interpolated the same way. */
     $horizontalPadding?: number;
     /**
-     * `alertMessage` — `PropTypes.string`.
-     *
-     * DECLARED BECAUSE THE COMPONENT PASSES IT, NOT BECAUSE ANYTHING READS IT. No
-     * interpolation below mentions `$alertMessage`; the message is rendered as the
-     * `<span>` child of `AlertRender` instead. `shouldForwardProp` filters it, so it
-     * reaches neither the CSS nor the DOM — a dead prop, harmless, and dropping it from
-     * `Alert.tsx` is a separate cleanup.
+     * `alertMessage` — `PropTypes.string`. Component passes it; nothing reads it. Harmless; `$` filters it.
      */
     $alertMessage?: string;
     /**
-     * `align` — `PropTypes.oneOf(['left', 'center'])`.
-     *
-     * DEFECT, DECLARED NOT FIXED: this is the prop the component passes, and NOTHING READS
-     * IT. The `text-align` rule at the bottom of this template reads the non-`$` `align`
-     * (declared below) instead, and that is never passed — so `align="center"` has never
-     * had any effect and every Alert renders `text-align: left`.
-     *
-     * The fix is to repoint that read from `props.align` to `props.$align`, which ACTIVATES
-     * A BRANCH THAT HAS NEVER FIRED and so changes rendered CSS. §J.8 lists that as C10
-     * work with a baseline re-record; it must not ride along in a type-only commit.
+     * `align` — `PropTypes.oneOf(['left', 'center'])`. Defect: component passes `$align`; template reads plain `align` instead. No-op; every Alert is left-aligned.
      */
     $align?: 'left' | 'center';
     /**
-     * `width` — `PropTypes.number`, px.
-     *
-     * DEFECT, DECLARED NOT FIXED: no `$`. `Alert.tsx` passes `width={width}` and
-     * `shouldForwardProp` forwards every non-`$` prop, so whenever a caller sets `width` it
-     * also lands on the rendered `<div>`, which is not a valid attribute on a `<div>`.
-     * CONFIRMED, not inferred: `scripts/r19-harness/baseline.json` records
-     * `<div width="480" …>` for `data/Alert`. The fix is to rename it `$width` at both ends,
-     * which REMOVES a DOM attribute and so needs C10's re-record. §E.4's third case.
+     * `width` — `PropTypes.number`, px. Defect: no `$` means it leaks to DOM as invalid `width="480"` attribute.
      */
     width?: number;
     /**
-     * `align` again, in its non-`$` form — the key this template actually reads. Same
-     * defect as `$align` above, stated from the reading end: nothing passes this, so the
-     * `=== 'center'` comparison is always `false`.
+     * `align` in its non-`$` form — read but never passed; comparison always false.
      */
     align?: 'left' | 'center';
 }
@@ -67,14 +43,7 @@ interface AlertRenderStyleProps {
      */
     $lineClamp?: number;
     /**
-     * `fontSize` — `PropTypes.number`, px.
-     *
-     * DEFECT, DECLARED NOT FIXED: no `$`. `Alert.tsx` passes `fontSize={fontSize}`, so
-     * whenever a caller sets it, it also leaks onto the rendered `<div>` — AS
-     * `font-size="12"`, NOT `fontSize="12"`: React maps this particular camelCase name to
-     * its hyphenated attribute form. CONFIRMED, not inferred:
-     * `scripts/r19-harness/baseline.json` records `<div font-size="12" …>` for every
-     * `data/Alert` entry. The fix is `$fontSize` at both ends — a DOM change, so C10. §E.4.
+     * `fontSize` — `PropTypes.number`, px. Defect: no `$` means it leaks to DOM as `font-size="12"` attribute.
      */
     fontSize?: number;
 }

package/types/components/data/Badge/Badge.d.ts

@@ -7,15 +7,7 @@ type BadgeOwnProps = {
     badgeIcon?: React.ReactNode;
     /**
      * Content to be showed in the badge – e.g. number of results.
-     *
-     * NMB-3998: this is `React.ReactNode` and NOT the four-way union the propTypes
-     * codemod produced from `oneOfType([string, number, func, element])`. The `func`
-     * member was never a legal value: line 182 renders `{badgeContent}` as a child, and
-     * React THROWS "Functions are not valid as a React child" for a function. So the
-     * propTypes documented a value that cannot work, and transcribing them faithfully
-     * published that mistake as a type — which is what TS2769 on line 182 was reporting.
-     * The union was also missing `null`, used by `Badge badgeContent={null}` in
-     * Tabs.stories; that only compiled because `strictNullChecks` is off.
+     * ReactNode, not the union — func is never valid, null was missing.
      */
     badgeContent?: React.ReactNode;
     /**

package/types/components/data/Badge/Badge.styled.d.ts

@@ -1,128 +1,29 @@
-/** Props of the `Badge` root, i.e. what `Badge.tsx` passes to `S.Badge`. */
 export interface BadgeStyleProps {
-    /** `elevated` — `PropTypes.bool`; positions the label on top of the children. */
     $elevated?: boolean;
-    /** `Boolean(children)`, derived in the component, so genuinely `boolean`. */
     $hasChildren?: boolean;
 }
-/**
- * Props of `BadgeLabel`. Value types from `Badge.tsx`'s propTypes; all optional per §J.5.
- *
- * Read the file header before adding to this list: eight of these members exist because
- * the template and the component disagree about the key, not because they are wanted.
- */
 interface BadgeLabelStyleProps {
-    /** `elevated` — drives border-radius, margin, position and transform below. */
     $elevated?: boolean;
-    /** `active` — `PropTypes.bool`. */
     $active?: boolean;
-    /** `error` — `PropTypes.bool`. Takes priority over `$warning`. */
     $error?: boolean;
-    /** `warning` — `PropTypes.bool`. */
     $warning?: boolean;
-    /**
-     * `lineHeight` — `PropTypes.oneOfType([number, string])`.
-     *
-     * DEFECT, DECLARED NOT FIXED: `Badge.tsx` DEFAULTS `lineHeight` TO THE STRING
-     * `'normal'`, and the template emits `${props.$lineHeight}px` whenever the value is
-     * truthy — so every Badge that does not override it renders the invalid declaration
-     * `line-height: normalpx`, which browsers drop. The effect happens to match the
-     * intended `normal`, which is why it has gone unnoticed. Fixing it (default `undefined`,
-     * or a unit-aware interpolation) changes the emitted CSS text, so it is C10 work.
-     */
     $lineHeight?: number | string;
-    /** `horizontalPadding` — `PropTypes.number`, px. The one padding key that matches. */
     $horizontalPadding?: number;
-    /** `minHeight` — `PropTypes.number`, px. */
     $minHeight?: number;
-    /** `minWidth` — `PropTypes.number`, px. */
     $minWidth?: number;
-    /** `backgroundColors` — `[darkThemeColor, lightThemeColor]`, read by index. */
     $backgroundColors?: string[];
-    /** `colors` — font colour as `[darkThemeColor, lightThemeColor]`, read by index. */
     $colors?: string[];
-    /** `borderColors` — `[dark, light]`; when set, a 1px solid border is applied. */
     $borderColors?: string[];
-    /**
-     * `verticalPadding` — `PropTypes.number`, px.
-     *
-     * DEFECT, DECLARED NOT FIXED, AND IT IS THE §E.3 RUN-TOGETHER-NAME FAMILY.
-     * `Badge.tsx:85` passes `$elevatedverticalPadding={verticalPadding}` — `$elevated` and
-     * `verticalPadding` run together — while the template below reads the plain
-     * `verticalPadding`. Neither name is the other's, so BOTH sides are dead: nothing ever
-     * supplies the key this reads, and nothing ever reads the key the component supplies.
-     * `verticalPadding` has therefore never had any effect; every Badge falls through to
-     * the `$elevated ? '4px' : '6px'` default.
-     *
-     * The fix is to make both ends `$verticalPadding`, which ACTIVATES A BRANCH THAT HAS
-     * NEVER FIRED and so changes rendered padding. C10, with a re-record.
-     */
     verticalPadding?: number;
-    /**
-     * `$elevatedverticalPadding` — the key `Badge.tsx:85` actually passes. DECLARED BECAUSE
-     * THE COMPONENT PASSES IT, NOT BECAUSE ANYTHING READS IT; see `verticalPadding` above.
-     * Harmless in the DOM (the `$` prefix means `shouldForwardProp` still filters it), so
-     * unlike the four leaks below this one is invisible rather than wrong.
-     */
     $elevatedverticalPadding?: number;
-    /**
-     * `elevated` in its non-`$` form — read at the `font-size` block below, and NEVER
-     * PASSED (the component passes `$elevated`).
-     *
-     * DEFECT, DECLARED NOT FIXED: the ternary always takes the false arm, so an elevated
-     * Badge renders `font-size: 0.750rem` instead of the intended `0.625rem`. Fix: read
-     * `props.$elevated`, which is already declared above — a CSS change, so C10.
-     */
     elevated?: boolean;
-    /**
-     * `error` in its non-`$` form — read inside the dark-mode `color` callback, and NEVER
-     * PASSED.
-     *
-     * DEFECT, DECLARED NOT FIXED: it makes the second disjunct of
-     * `(props.$warning && !props.$error) || (props.error && !props.$active)` permanently
-     * `false`, so an inactive error Badge never gets the `gray-900` text colour in dark
-     * mode. Fix: `props.$error` — a colour change, so C10.
-     */
     error?: boolean;
-    /**
-     * `fontSize` — `PropTypes.oneOfType([number, string])`.
-     *
-     * DEFECT, DECLARED NOT FIXED: no `$`. `Badge.tsx:79` passes it and
-     * `shouldForwardProp` forwards every non-`$` prop, so a caller-supplied `fontSize` also
-     * lands on the rendered `<span>` — AS `font-size="15"`, NOT `fontSize="15"`: React maps
-     * this particular camelCase name to its hyphenated attribute form. CONFIRMED, not
-     * inferred: `scripts/r19-harness/baseline.json` records `<span font-size="12" …>` for
-     * every `data/Badge` entry. Note the `string` half of the propTypes union is also a
-     * trap: the template emits `${props.fontSize}px`, so `fontSize="15px"` would render
-     * `15pxpx`. Fix: `$fontSize` at both ends — removes a DOM attribute, so C10. §E.4's
-     * third case.
-     */
     fontSize?: number | string;
-    /**
-     * `fontWeight` — `PropTypes.oneOfType([number, string])`, interpolated raw so both
-     * halves are safe. Same non-`$` DOM leak as `fontSize`, hyphenated the same way, and
-     * this is the UNCONDITIONAL one: `Badge.tsx:80` passes it and `Badge.tsx:49` defaults it
-     * to `'normal'`, so `font-weight="normal"` is on EVERY rendered label whether the caller
-     * sets anything or not. Verified by rendering `<Badge badgeContent={5} />` with no other
-     * prop. Fix: `$fontWeight` at both ends — C10.
-     */
     fontWeight?: number | string;
-    /**
-     * `height` — `PropTypes.number`, px. Same non-`$` DOM leak; `Badge.tsx:87` passes it.
-     * `height` is not a valid attribute on a `<span>`. CONFIRMED: the baseline records
-     * `<span … height="24" …>` for every `data/Badge` entry. Fix: `$height` — C10.
-     */
     height?: number;
-    /**
-     * `width` — `PropTypes.number`, px. Same non-`$` DOM leak; `Badge.tsx:89` passes it. No
-     * baseline fixture sets it, so it is absent there, but rendering the built `Badge` with
-     * `width={50}` puts `width="50"` on the `<span>`. Fix: `$width` — C10.
-     */
     width?: number;
 }
-/** Props of `BadgeIcon`. */
 interface BadgeIconStyleProps {
-    /** `!!badgeContent`, derived in the component — adds the gutter between icon and text. */
     $useGutter?: boolean;
 }
 export declare const Badge: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, BadgeStyleProps>, never>> & string;

package/types/components/data/Popover/Popover.d.ts

@@ -1,36 +1,6 @@
 import React from 'react';
 import type { Middleware } from '@floating-ui/react';
 import type { PopoverPlacement } from '../../../hooks/useFloatingPopover';
-/**
- * tippy's `appendTo`, and the three-way rule it implies. `'parent'` and an implicit-parent
- * case are real tippy behaviours, not inventions — measured in
- * `tippy.js/dist/tippy.cjs.js`:
- *
- * ```js
- * if (instance.props.interactive && appendTo === TIPPY_DEFAULT_APPEND_TO || appendTo === 'parent') {
- *   parentNode = node.parentNode;          // INLINE, next to the reference
- * } else {
- *   parentNode = invokeWithArgsOrReturn(appendTo, [node]);   // portal
- * }
- * ```
- *
- * ⚠️ **`Popover` DEFAULTS `interactive` TO `true`, SO ITS DEFAULT IS THE INLINE BRANCH.**
- * `appendTo` appears in 6 files per consumer out of 30 `<Popover>` call sites across both,
- * so a blanket `FloatingPortal` would relocate the MAJORITY of call sites out of their
- * current DOM position — a stacking/`z-index` regression across both apps, not a
- * preservation. Plan §A3 originally resolved C4 as "portal by default" on half the evidence
- * and was corrected in `0ef5f71`; `Tooltip.tsx:77-97` is where the branch was first found.
- *
- * | `appendTo` | `interactive` | where it renders |
- * | --- | --- | --- |
- * | given | any | `FloatingPortal` rooted at `appendTo` |
- * | absent | `false` | `FloatingPortal` rooted at `document.body` |
- * | absent | `true` *(the default)* | **INLINE**, into the reference's parent |
- *
- * All 12 `appendTo` sites across both consumers pass `document.body`; the `'parent'` and
- * function forms are supported because tippy supported them and the render-gate fixture
- * uses `'parent'` to make an open popover capturable.
- */
 export type PopoverAppendTo = 'parent' | Element | ((reference: Element) => Element);
 type PopoverOwnProps = {
     /**
@@ -38,21 +8,11 @@ type PopoverOwnProps = {
      */
     content: string | React.ReactElement<any>;
     /**
-     * Determines if the `Popover` has interactive content inside of it, so that it can be
-     * hovered over and clicked inside without hiding.
-     *
-     * **It also decides where the popover renders** — see `PopoverAppendTo`. It defaults to
-     * `true`, so a `Popover` renders INLINE unless `appendTo` or `interactive={false}` says
-     * otherwise.
+     * Whether the popover's content is interactive and where it renders (inline by default for interactive popovers).
      */
     interactive?: boolean;
     /**
-     * The preferred placement of the `Popover`. Note that the flip middleware can change this
-     * to the opposite placement if it has more space.
-     *
-     * The 12 concrete names are spelled identically in Popper and Floating UI, so they need no
-     * translation. The three `auto*` values have no Floating UI string — they select
-     * `autoPlacement()` instead of `flip()`; see `useFloatingPopover`.
+     * Preferred placement; 12 concrete names need no Popper→Floating UI translation. Three `auto*` values select `autoPlacement()` instead of `flip()`.
      */
     placement?: PopoverPlacement;
     /**
@@ -60,66 +20,27 @@ type PopoverOwnProps = {
      */
     duration?: number;
     /**
-     * Determines the events that cause the `Popover` to show. Multiple event names are separated by
-     * spaces.
-     *
-     * *Example events:*
-     *
-     * `trigger: 'click'`
-     *
-     * `trigger: 'focusin'`
-     *
-     * `trigger: 'mouseenter click'`
-     *
-     * `''` means no triggers at all, and `undefined` means tippy's default
-     * (`'mouseenter focus'`) — though this component overrides that with its own default of
-     * `'click focus'`. See `parseTrigger`.
-     *
-     * --
+     * Events that cause the popover to show (space-separated). `''` means no triggers, `undefined` means `'mouseenter focus'`, component defaults to `'click focus'`.
      */
     trigger?: string;
     /**
-     * Displaces the popover from its reference element in pixels (skidding and distance).
-     *
-     * `[skidding, distance]`
-     *
-     * `distance` is the gap between the reference and the ARROW TIP, not the box — which is
-     * what it has always meant here, because the old implementation handed tippy
-     * `offset[1] + (arrow ? 15 : 0)`. `useFloatingPopover` adds the arrow height back, so the
-     * prop keeps its meaning; see `DEFAULT_ARROW_HEIGHT` for the derivation of the 15.
+     * `[skidding, distance]`; distance is the gap between reference and arrow tip (not box), absorbing the old `+15` offset.
      */
     offset?: number[];
     /**
-     * Determines if the popover has an arrow.
-     *
-     * ⚠️ It also moves the box even when the arrow is NOT drawn — see the block comment at
-     * `arrowDrivesTheOffset` in the body. That is the existing behaviour, reproduced.
+     * Whether the popover has an arrow; also moves the box even when not drawn (existing behaviour, reproduced).
      */
     arrow?: boolean;
     /**
-     * Use React's state to fully control the `Popover` instead of relying on the native trigger
-     * and `hideOnClick` props
-     *
-     * Passing a boolean — **including `false`** — switches the popover to CONTROLLED mode and
-     * its own triggers stop firing. `undefined` leaves it uncontrolled. `onClickOutside` still
-     * fires in controlled mode, which is how 12 consumer call sites close a controlled
-     * popover.
+     * Pass a boolean to control visibility; both `true` and `false` disable native triggers. `onClickOutside` still fires in controlled mode.
      */
     visible?: boolean;
     /**
-     * @deprecated Accepted and IGNORED. This was a Popper `modifiers` array, appended to
-     * `popperOptions.modifiers`; Floating UI has middleware instead and the two are not
-     * translatable prop-for-prop. Kept so that no existing call site throws — plan C6. No
-     * consumer passes it. Pass `middleware` instead.
+     * @deprecated Accepted and ignored; use `middleware` instead.
      */
     modifiers?: any[];
     /**
-     * Extra Floating UI middleware, appended after the built-in chain
-     * (`offset` → `flip`/`autoPlacement` → `shift` → `arrow` → `size`). This is the honest
-     * replacement for `modifiers`, and it exists because one internal caller genuinely needed
-     * it: `MultiLevelCheckboxSelect` matched the popover's width to its input with a
-     * hand-written Popper `sameWidth` modifier, which C6's accept-and-ignore would have
-     * silently dropped.
+     * Extra Floating UI middleware, appended after the built-in chain; one internal caller needed this for width matching.
      */
     middleware?: Middleware[];
     /**
@@ -141,8 +62,7 @@ type PopoverOwnProps = {
      */
     contextMenuSublevel?: boolean;
     /**
-     * `z-index` of the positioned element. Defaults to 9999, tippy's default. 10 consumer call
-     * sites pass this.
+     * `z-index` of the positioned element (default: 9999, tippy's default).
      */
     zIndex?: number;
     /**
@@ -151,8 +71,7 @@ type PopoverOwnProps = {
      */
     disabled?: boolean;
     /**
-     * Where the popover is rendered. Omitting it means INLINE for an `interactive` popover
-     * (the default) and `document.body` otherwise. See `PopoverAppendTo`.
+     * Where the popover is rendered (default: inline for interactive popovers, document.body otherwise).
      */
     appendTo?: PopoverAppendTo;
     /** Fired when a press lands outside both the reference and the popover. */
@@ -162,15 +81,7 @@ type PopoverOwnProps = {
      */
     onShow?: () => void;
     /**
-     * Fired when the popover closes. tippy's `onHide`, minus its instance argument.
-     *
-     * ONE INTERNAL CALLER DEPENDS ON IT: `inputs/Button` passes
-     * `onHide={handleDropdownClose}` to reset its `dropdown-is-active` class, so this is not a
-     * courtesy re-export. It fires on every close the component decides for itself —
-     * outside press, a second click on the trigger, a context-menu item click. It does NOT
-     * fire when a CONTROLLED popover is closed by its owner flipping `visible` to `false`,
-     * because nothing asks this component to close in that case; tippy did fire there. No
-     * call site pairs `onHide` with `visible`, so the difference is currently unobservable.
+     * Fired when the popover closes; one internal caller (inputs/Button) depends on it to reset dropdown-is-active class.
      */
     onHide?: () => void;
     /**

package/types/components/data/Tab/Tab.d.ts

@@ -3,20 +3,7 @@ type TabOwnProps = {
     children?: any;
     hidden?: boolean;
     /**
-     * The tab's clickable header, conventionally a `Badge`:
-     * `<Tab trigger={<Badge>Tab title</Badge>}>`.
-     *
-     * NOT DECLARED BY THE OLD propTypes AND NOT READ BY THIS COMPONENT — which is why
-     * neither the codemod nor the widening pass could produce it, and why it is
-     * hand-written here. `Tab` is a data carrier: `Tabs.tsx` walks its children with
-     * `child.type === Tab` and lifts `child.props?.trigger` out, then renders it inside
-     * `S.TabHeader`. The `<Tab>` element itself is never mounted, so `trigger` never
-     * reaches the DOM and there is no attribute leak to fix.
-     *
-     * `ReactElement`, not `ReactNode`: `Tabs.handleTabClick` reads
-     * `tab.trigger.props.children` to build the `triggerText` it passes to `onTabClick`.
-     * A string trigger would compile under `ReactNode` and silently produce an empty
-     * `triggerText`. All 44 call sites in `src` pass a `<Badge>`.
+     * The tab's clickable header, conventionally a `Badge`. Not read by Tab itself; Tabs extracts it.
      */
     trigger?: React.ReactElement<any>;
 };

package/types/components/data/Tabs/Tabs.styled.d.ts

@@ -4,23 +4,7 @@ export interface TabsStyleProps {
     $backgroundColor?: string;
 }
 /**
- * Shared by `TabHeaders` and `TabHeaderBorder`, the two components `Tabs.tsx` hands
- * `custompadding` to. One interface rather than two because the key, the value and the
- * defect are the same at both sites; a change here is a change to both, which is the
- * point of naming them together.
- *
- * DEFECT, DECLARED NOT FIXED: `custompadding` HAS NO `$`, so `shouldForwardProp` forwards
- * it and it lands on the rendered `<ul>` and `<div>`. This is not inferred — it is in
- * `scripts/r19-harness/baseline.json` as `<ul custompadding="40px" …>`. The fix is to
- * rename it `$customPadding` at both ends, which REMOVES a DOM attribute and so belongs to
- * C10 with its baseline re-record. §E.4's third case.
- *
- * `number | string`, not the `PropTypes.string` the propTypes claim: `Tabs.tsx` DEFAULTS
- * `customPadding` to the NUMBER `0`, and that default is what reaches these templates in
- * the common case. It is falsy, so the `!props.custompadding` arm wins and the padding
- * shorthand is emitted as `padding: 0` / `margin: -2px 0` — correct by accident. A
- * caller-supplied number would emit a unitless `padding: 0 8`, which is why the union is
- * worth stating rather than tidying away.
+ * Shared by `TabHeaders` and `TabHeaderBorder`. Defect: `custompadding` has no `$`, leaks to DOM. Typed as `number | string` to match component default of 0.
  */
 interface TabPaddingStyleProps {
     /** `customPadding` — see the interface JSDoc; both the leak and the union are there. */

package/types/components/data/Tooltip/Tooltip.d.ts

@@ -1,26 +1,5 @@
 import React from 'react';
 import type { PopoverPlacement, PopperOffset } from '../../../hooks/useFloatingPopover';
-/**
- * tippy's `appendTo`. `'parent'` and an implicit-parent case are real tippy behaviours, not
- * inventions — measured in `tippy.js/dist/tippy.cjs.js`:
- *
- * ```js
- * if (instance.props.interactive && appendTo === TIPPY_DEFAULT_APPEND_TO || appendTo === 'parent') {
- *   parentNode = node.parentNode;
- * } else {
- *   parentNode = invokeWithArgsOrReturn(appendTo, [node]);
- * }
- * ```
- *
- * ⚠️ THIS IS A CORRECTION TO PLAN §A3, WHICH RESOLVED C4 ON HALF THE EVIDENCE. §A3 quotes
- * `TIPPY_DEFAULT_APPEND_TO = () => document.body` and concludes that portalling by default
- * is behaviour-preserving. The line above is the other half: when `interactive` is true AND
- * `appendTo` is left at its default, tippy does NOT use that default — it renders INLINE,
- * into the reference's parent. So "portal by default" is behaviour-preserving only for
- * non-interactive instances. It is safe for `Tooltip`, whose `interactive` defaults to
- * `false` and which no consumer passes it to (measured across both apps), and it is a rule
- * `Popover` will have to honour, since `Popover` does have interactive call sites.
- */
 export type TooltipAppendTo = 'parent' | Element | ((reference: Element) => Element);
 type TooltipOwnProps = {
     /**
@@ -46,32 +25,11 @@ type TooltipOwnProps = {
      */
     duration?: number;
     /**
-     * Determines the events that cause the tooltip to show. Multiple event names are separated
-     * by spaces.
-     *
-     * *Example events:*
-     *
-     * `trigger: 'click'`
-     *
-     * `trigger: 'focusin'`
-     *
-     * `trigger: 'mouseenter click'`
-     *
-     * `trigger: 'mouseenter'`
-     *
-     * Omitting it means `'mouseenter focus'`, and `''` means no triggers at all — both are
-     * relied on by consumer code. See `parseTrigger`.
-     *
-     * --
+     * Events that cause the tooltip to show (space-separated). Defaults to `'mouseenter focus'`, `''` means no triggers.
      */
     trigger?: 'mouseenter' | 'mouseenter focus' | 'click' | 'focusin' | 'mouseenter click' | '';
     /**
-     * Determines if the tooltip is visible without trigger.
-     *
-     * Passing a boolean — **including `false`** — switches the tooltip to CONTROLLED mode and
-     * its own triggers stop firing. `undefined` leaves it uncontrolled. `useTooltipAutoShow`
-     * depends on that distinction and its `toolTipVisible` is `true | undefined` for exactly
-     * this reason.
+     * Pass a boolean to control visibility; both `true` and `false` disable native triggers. `undefined` leaves uncontrolled.
      */
     visible?: boolean;
     /**
@@ -80,15 +38,11 @@ type TooltipOwnProps = {
      */
     arrow?: boolean;
     /**
-     * `z-index` of the positioned element. Defaults to 9999, tippy's default. 30 consumer call
-     * sites pass this, which is why it is declared here even though it was never in the old
-     * prop type — it used to typecheck only because the published `Props` widened to
-     * `TippyProps`, and that widening disappears with tippy.
+     * `z-index` of the positioned element (default: 9999, tippy's default).
      */
     zIndex?: number;
     /**
-     * A disabled tooltip can never open, even under a controlled `visible={true}` — tippy's
-     * semantics, and what `useTooltipAutoShow`'s `toolTipDisabled` relies on.
+     * Disabled tooltip can never open, even under controlled `visible={true}` (tippy semantics).
      */
     disabled?: boolean;
     /**

package/types/components/data/VerificationStatusIcon/VerificationStatusIcon.styled.d.ts

@@ -1,26 +1,12 @@
 /**
- * Shared by all three components: `VerificationStatusIcon.tsx` passes `$background` to
- * every one of them. Only `VerificationIconWrapper` and `VerificationStatusIcon` read it;
- * on `VerificationStatusColor` it is passed and never read, which is harmless because the
- * `$` means `shouldForwardProp` filters it before both the CSS and the DOM.
+ * Shared by all three components. Only `VerificationIconWrapper` and `VerificationStatusIcon` read it; on `VerificationStatusColor` it's passed and never read (harmless due to `$`).
  */
 interface VerificationBackgroundStyleProps {
     /** `background` — `PropTypes.bool`; swaps in the black pill and the light icon colour. */
     $background?: boolean;
 }
 /**
- * Props of the `VerificationStatusIcon` element.
- *
- * DEFECT, DECLARED NOT FIXED: `iconHeight` in its non-`$` form is what the `svg` rule
- * below reads, and NOTHING PASSES IT — `VerificationStatusIcon.tsx` passes `$iconHeight`,
- * which this component never reads. So the `?? 15` fallback is unconditional and the icon
- * is 15px tall no matter what a caller asks for, WHILE `VerificationStatusColor` does read
- * `$iconHeight` and scales correctly. Pass `iconHeight={30}` today and the status dot grows
- * but the icon it sits on does not.
- *
- * The fix is to repoint the read to `props.$iconHeight`, which ACTIVATES A BRANCH THAT HAS
- * NEVER FIRED and changes the emitted height for every non-default `iconHeight`. §J.8 puts
- * that in C10 with its baseline re-record.
+ * Defect: reads `iconHeight` (never passed); component passes `$iconHeight` which is never read. Icon always 15px, dot scales correctly.
  */
 export interface VerificationStatusIconStyleProps extends VerificationBackgroundStyleProps {
     /** `iconHeight` — `PropTypes.number`, px. Read, never passed; see the JSDoc above. */
@@ -31,12 +17,7 @@ interface VerificationStatusColorStyleProps extends VerificationBackgroundStyleP
     /** `iconHeight` — `PropTypes.number`, px. This site reads the `$` form, correctly. */
     $iconHeight?: number;
     /**
-     * `status` — `PropTypes.oneOf(['verified', 'pending', 'rejected', 'mixed'])`, and
-     * `.isRequired` on the component but still OPTIONAL here per §J.5.
-     *
-     * Closed on purpose rather than widened to `string`: the block below compares this value
-     * four times, and with a closed union a mistyped status name is TS2367 instead of a
-     * branch that silently never fires. §J.6.
+     * `status` — closed union to catch mistyped names as TS2367 rather than silent branch misfire.
      */
     $status?: 'verified' | 'pending' | 'rejected' | 'mixed';
 }