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

package/types/components/widgets/AssetGallery/asset.types.d.ts

@@ -1,62 +1,19 @@
 import PropTypes from 'prop-types';
 import type { DragEvent, MouseEvent as ReactMouseEvent, ReactElement, ReactNode } from 'react';
 /**
- * The asset contract — the deepest prop API in this library, and the only one a
- * consumer builds objects *for* rather than passing props *to*.
+ * The asset contract — consumers build these objects rather than passing them as props.
  *
- * ================= THREE THINGS TO KNOW BEFORE EDITING THIS FILE =============
- *
- * 1. THE TYPES ARE THE SOURCE OF TRUTH; THE propTypes AT THE BOTTOM ARE LEGACY.
- *    Two descriptions of one shape live in one file on purpose, so they cannot
- *    drift apart in two. The `assetShape` / `assetShapeWithLayout` literals are
- *    still imported by four components and still evaluated at runtime on
- *    React 16, so they cannot be deleted yet — see the fenced block at the end
- *    for when they go and what to do then.
- *
- * 2. THIRTEEN MEMBERS HERE WERE NEVER DECLARED BY THE propTypes, AND EVERY ONE
- *    OF THEM IS READ AT RUNTIME. They are marked `@recovered` with the read
- *    site. This is why this file was hand-written instead of codemodded: a
- *    codemod can only reproduce what the propTypes said, and what the propTypes
- *    said was missing a third of the API. Generated prop types are CLOSED, so an
- *    omission converts silently from "undocumented" into "compile error at the
- *    consumer's call site". Before adding a member, grep for `asset.<name>`.
- *
- * 3. THE NESTED SHAPES ARE NAMED, EXPORTED INTERFACES, NOT INLINE OBJECT TYPES.
- *    A consumer keeping its own asset list needs to name the pieces
- *    (`AssetAction[]`, `AssetSummary`) in order to build them; inlining forces
- *    it to re-declare them or to reach for `any`. `Asset` is also meant to be
- *    EXTENDED — the gallery hands each asset object straight back to
- *    `component(asset, children)` and to every `onClick`, so consumer-only
- *    fields travel through the library untouched:
- *
- *      interface MyAsset extends Asset { credit: string }
- *
- *    Note that `AssetAction` (the interface below) and `AssetAction` (the
- *    component exported from `@ntbjs/react-components/widgets`) are different
- *    things with the same name. They never meet today, because this module is
- *    not re-exported from the widgets barrel. If you ever add it there, rename
- *    one of them.
- * ============================================================================
- */
-/**
- * An asset's identity, and one of its two required members.
- *
- * `AssetGalleryBase` drops any asset without one and warns; the value is also
- * used as a React `key`, which is why the union is `string | number` rather than
- * `unknown` — `PropTypes.oneOfType([string, number])`, verbatim.
+ * The interfaces are the source of truth; the propTypes at the bottom are legacy but still
+ * evaluated at runtime on React 16, so they cannot be deleted yet. Members marked `@recovered`
+ * were never declared by the propTypes but are read at runtime — grep `asset.<name>` before
+ * adding one, since a missing member becomes a compile error at the consumer's call site.
+ * `Asset` is meant to be extended (`interface MyAsset extends Asset { credit: string }`).
+ * The `AssetAction` interface here is unrelated to the `AssetAction` component in the widgets
+ * barrel; they never meet because this module is not re-exported there.
  */
+/** Identity and React key; must be `string | number`. */
 export type AssetKey = string | number;
-/**
- * What kind of file this asset is. Only `'video'` and `'audio'` change what the
- * cards render (a `<video>`, or a headset glyph); the other three fall through
- * to the lazily-loaded still image.
- *
- * Both cards branch on `asset.fileType?.toLowerCase()`, so a consumer passing
- * `'VIDEO'` gets the video preview while `renderMediaBadge` — which compares
- * `=== 'video'` without lowercasing — does not show the play badge. The union is
- * lowercase because that is what the propTypes always declared; widening it to
- * `string` would bless that inconsistency instead of exposing it.
- */
+/** Cards lowercase before checking; `renderMediaBadge` does not, causing inconsistency. */
 export type AssetFileType = 'image' | 'video' | 'pdf' | 'file' | 'audio';
 /**
  * Declared corner for the file-type glyph.
@@ -66,11 +23,7 @@ export type AssetFileType = 'image' | 'video' | 'pdf' | 'file' | 'audio';
  * removing it is a deliberate API change and belongs in its own commit.
  */
 export type AssetFileTypeIconPosition = 'top-left' | 'top-right';
-/**
- * Usage-restriction level, 1 (info) to 5 (highly restricted). Passed through to
- * `InstructionSeverityDisplay` and `SummaryCard`, which key their badge label
- * and colour off it. `PropTypes.oneOf([1, 2, 3, 4, 5])`, verbatim.
- */
+/** Usage-restriction level (1=info, 5=highly restricted); controls badge styling. */
 export type AssetInstructionSeverity = 1 | 2 | 3 | 4 | 5;
 /**
  * Which of the two things a computed row entry is: a real asset card, or the
@@ -215,13 +168,7 @@ export interface AssetLayout {
     type: AssetLayoutType;
     /** Whether the source asset declared both a width and a height. Compact view only. */
     hasHeightAndWidth?: boolean;
-    /**
-     * Scroll-virtualisation flag: `false` unmounts the card.
-     *
-     * @recovered `AssetGalleryBase.tsx` both writes it (`calculateVisibility`) and
-     *   reads it (the render map, and the arrow-key navigation). The propTypes
-     *   never declared it.
-     */
+    /** Scroll-virtualisation flag: `false` unmounts the card. */
     show?: boolean;
 }
 /**
@@ -236,115 +183,51 @@ export interface Asset {
     key: AssetKey;
     /** Required. Selects the preview branch — see {@link AssetFileType}. */
     fileType: AssetFileType;
-    /** Image, video or audio source for the thumbnail. */
     previewUrl?: string;
-    /** Rendered as the card title and as the `<img alt>`. */
+    /** Card title and `<img alt>`. */
     title?: string;
-    /** Intrinsic pixel width; drives the compact view's row aspect ratio. Falls back to 1920. */
+    /** Pixel width; drives compact view row aspect ratio (falls back to 1920). */
     width?: number;
-    /** Intrinsic pixel height; drives the compact view's row aspect ratio. Falls back to 1080. */
+    /** Pixel height; drives compact view row aspect ratio (falls back to 1080). */
     height?: number;
     note?: AssetNote;
-    /** Consecutive assets sharing a `group` get one heading row above the first of them. */
+    /** Consecutive assets sharing this get one heading row above the first. */
     group?: string;
     actions?: AssetAction[];
-    /** Top-right glyph on the thumbnail. When set, it suppresses the note glyph. */
+    /** Top-right glyph on the thumbnail; suppresses the note glyph when set. */
     statusIcon?: ReactElement<any>;
-    /** Rendered over everything else on the card; the consumer owns its positioning. */
+    /** Rendered over everything else on the card; consumer owns positioning. */
     overlay?: ReactElement<any>;
-    /** Draws the "completed" veil over the compact card. */
     completed?: boolean;
-    /** Draws the "error" veil over the compact card. */
     hasError?: boolean;
-    /** Dims the card. Does NOT stop `onClick` from firing. */
+    /** Dims the card but does not prevent click handlers. */
     disabled?: boolean;
-    /** Declared corner for the file-type glyph. Read by nothing — see the type. */
     fileTypeIconPosition?: AssetFileTypeIconPosition;
-    /** Severity of `imageRights`, shown as a badge on the card and in the summary. */
     instructionSeverity?: AssetInstructionSeverity;
     summary?: AssetSummary;
-    /**
-     * Called with the React click event AND the asset. Not called while the
-     * gallery is in extended-select mode, where a click selects instead.
-     */
+    /** Called with event + asset; skipped in extended-select mode (click selects instead). */
     onClick?: (event: ReactMouseEvent<HTMLElement>, asset: Asset) => void;
-    /**
-     * Called with the React mouse event AND the asset, after the card has started
-     * playing a video preview.
-     */
+    /** Called with event + asset after video preview starts playing. */
     onMouseEnter?: (event: ReactMouseEvent<HTMLElement>, asset: Asset) => void;
-    /**
-     * Called with the NATIVE event, not a React one: both cards attach this with
-     * `addEventListener('contextmenu', …)` on the card element. The card
-     * default-prevents it before calling.
-     */
+    /** Called with native event (not React event); card prevents default before calling. */
     onContextMenu?: (event: MouseEvent) => void;
-    /**
-     * Duration in MILLISECONDS. Rendered as `h:mm:ss` in the media badge by
-     * `convertMsToHMS`, so seconds here are wrong by a factor of 1000.
-     *
-     * @recovered both cards read `asset.duration`.
-     */
+    /** Duration in MILLISECONDS (not seconds). */
     duration?: number;
-    /**
-     * Body text under the title on the grid card, and in the summary card.
-     *
-     * @recovered both cards read `asset.description`, and both list it in their
-     *   `React.memo` comparator, so it is one of the fields that re-renders them.
-     */
+    /** Body text under title on grid card and summary card. */
     description?: string;
-    /**
-     * The usage-restriction text. Its presence is what makes the grid card render
-     * an `InstructionSeverityDisplay` at all.
-     *
-     * @recovered both cards read `asset.imageRights`.
-     */
+    /** Usage-restriction text; its presence gates InstructionSeverityDisplay. */
     imageRights?: string;
-    /**
-     * Severity level → translated label, e.g. `{ 1: 'Info', 5: 'Svært begrenset' }`.
-     *
-     * `Record<string, string>` rather than a keyed-by-severity mapped type,
-     * because that is `PropTypes.objectOf(PropTypes.string)` on both components
-     * that consume it (`InstructionSeverityDisplay`, `SummaryCard`) and it stays
-     * assignable in both directions once those are typed.
-     *
-     * @recovered both cards forward `asset.instructionLabels`.
-     */
+    /** Severity level → label map, e.g. `{ 1: 'Info', 5: 'Svært begrenset' }`. */
     instructionLabels?: Record<string, string>;
-    /**
-     * Number of versions, shown in the layers badge.
-     *
-     * @recovered both cards read `asset.versions`.
-     */
+    /** Number of versions, shown in layers badge. */
     versions?: number;
-    /**
-     * A pre-rendered verification badge. A NODE, not a status string — the compact
-     * card returns it as-is from `renderVerificationBadge`, so the consumer owns
-     * the markup.
-     *
-     * @recovered `AssetGalleryCompactCard.tsx` reads `asset.verifications` for
-     *   both `displayIcon: 'verifications'` and `displayIcon: 'dynamic'`.
-     */
+    /** Pre-rendered verification badge (ReactNode, not string); consumer owns markup. */
     verifications?: ReactNode;
-    /**
-     * Per-asset override of the gallery's `selectable` prop. `AssetGalleryBase`
-     * tests `'selectable' in asset`, so `false` here beats `true` there.
-     *
-     * @recovered `AssetGalleryBase.tsx`.
-     */
+    /** Per-asset override of gallery's `selectable` prop; `false` here beats `true` there. */
     selectable?: boolean;
-    /**
-     * Sets the DOM `draggable` attribute on the card root.
-     *
-     * @recovered both cards pass `asset.draggable`.
-     */
+    /** Sets DOM `draggable` attribute on card root. */
     draggable?: boolean;
-    /**
-     * Called with the NATIVE drag event: both cards attach this with
-     * `addEventListener('dragstart', …)`. Pair it with `draggable: true`.
-     *
-     * @recovered both cards read `asset.onDragstart`.
-     */
+    /** Called with native drag event; pair with `draggable: true`. */
     onDragstart?: (event: DragEvent) => void;
 }
 /**

package/types/components/widgets/AssetPreview/AssetPreviewTopBar/AssetPreviewTopBar.styled.d.ts

@@ -1,30 +1,16 @@
 /**
- * `disabled` — `PropTypes.bool`, greys out the back button.
- *
- * NO `$`, AND THAT IS A DEFECT THAT IS ALREADY IN THE RENDER BASELINE. React recognises
- * `disabled` and renders it as a bare boolean attribute on any element, so
- * `widgets/AssetPreviewTopBar#disabled` in `scripts/r19-harness/baseline.json` records
- * `<div disabled="">` AND `<a disabled="">`. Renaming it `$disabled` removes both
- * attributes and therefore MOVES the baseline — C10 work, §E.4.
- *
- * Note it also has to be DECLARED to be read at all: `disabled` is a member of neither
- * `HTMLAttributes<HTMLDivElement>` nor `AnchorHTMLAttributes<HTMLAnchorElement>`. That is
- * the same asymmetry §J.9 records for `CompactTextInput` — there the identical read on an
- * `<input>` needs no declaration, because `InputHTMLAttributes` really does have it.
- *
- * Hosts: `AssetPreviewTopBar` and `BackButtonContainer`.
+ * `disabled` — greys out the back button. Not transient; present in baseline as bare boolean attribute.
  */
 interface AssetPreviewTopBarDisabledStyleProps {
     disabled?: boolean;
 }
-/** The top bar root, i.e. what `AssetPreviewTopBar.tsx` passes to it. */
+/**
+ * Props passed by `AssetPreviewTopBar.tsx` to `<S.AssetPreviewTopBar>`.
+ */
 export interface AssetPreviewTopBarStyleProps extends AssetPreviewTopBarDisabledStyleProps {
-    /** `border` — `PropTypes.bool`; swaps `border-bottom` between `1px solid` and `none`. */
+    /** Swaps `border-bottom` between `1px solid` and `none`. */
     $border?: boolean;
-    /** `shadow` — `PropTypes.bool`. Read as `props.$shadow && props.theme.themeProp(…)`,
-     *  which evaluates to `false | RuleSet` — a valid `Interpolation`. A BARE
-     *  `${props => props.$shadow}` would not be: `Interpolation` accepts `Falsy` but not
-     *  `true`, so it would be TS2345 even with the prop correctly typed `boolean`. §J.5. */
+    /** Shadow; evaluated as `props.$shadow && props.theme.themeProp(…)` to produce valid Interpolation. */
     $shadow?: boolean;
 }
 export declare const AssetPreviewTopBar: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, AssetPreviewTopBarStyleProps>, never>> & string;

package/types/components/widgets/ContextMenu/ContextMenu.d.ts

@@ -5,23 +5,7 @@ type ContextMenuOwnProps = {
      */
     children?: any;
     /**
-     * Marks this menu as the sublevel/submenu of another context menu.
-     *
-     * NOT DECLARED BY THE OLD propTypes, so the codemod could not emit it; the widening
-     * pass reported it as a `(dynamic key)` undeclared read but cannot type it, because
-     * `S.ContextMenu` is a `styled.div` and `sublevel` is not an HTML attribute. Declared
-     * by hand so the documented usage in this file's own JSDoc and in
-     * `ContextMenu.stories.tsx:103` keeps compiling.
-     *
-     * PRE-EXISTING FINDING, DELIBERATELY NOT FIXED HERE: nothing reads it. The component
-     * strips it out of the spread —
-     * `Object.entries(props).filter(([key]) => key !== 'sublevel')` — so it reaches
-     * neither the DOM nor `ContextMenu.styled.ts`, which reads no prop at all. The
-     * sublevel placement it appears to request is actually driven by the *`Popover`*'s
-     * `contextMenuSublevel`, which the stories set on the same element. So this is a
-     * documented public prop that is a no-op. Removing it is an API break and belongs in
-     * its own commit with its own decision; keeping the declaration records the API as it
-     * is published today rather than as we wish it were.
+     * Marks this menu as the sublevel/submenu of another context menu. This is a documented public prop that is currently a no-op; removing it is an API break.
      */
     sublevel?: boolean;
 };

package/types/components/widgets/ContextMenu/ContextMenuItem/ContextMenuItem.styled.d.ts

@@ -1,23 +1,15 @@
 import type { ReactElement } from 'react';
 /**
- * `ContextMenuItem`'s props, i.e. what `ContextMenuItem.tsx` passes to
- * `<S.ContextMenuItem>`: `$icon`, `$hoverColors`, `$hoverBackgroundColors` and
- * `$openssublevel`. Value types from that file's propTypes; all optional per §J.5.
+ * Props passed by `ContextMenuItem.tsx` to `<S.ContextMenuItem>`.
  */
 export interface ContextMenuItemStyleProps {
-    /** `icon` — `PropTypes.element`, so a React element and not a `ReactNode`. Read only
-     *  as `!props.$icon`, i.e. for presence. */
+    /** React element, read for presence only. */
     $icon?: ReactElement<any>;
-    /** `opensSublevel` — `PropTypes.bool`. Selects the right-hand padding, since a
-     *  sublevel item has its own chevron in that space. Lower-case by existing convention
-     *  at both ends; renaming it would be a two-file change for no type benefit. */
+    /** Selects right-hand padding (sublevel items have their own chevron). */
     $openssublevel?: boolean;
-    /** `hoverColors` — `PropTypes.arrayOf(PropTypes.string)`, documented as exactly
-     *  `[darkModeColor, lightModeColor]` hex strings. `string[]` and not
-     *  `[string, string]`: the propTypes say an array of any length, which is why the
-     *  template guards the array's presence and then `[0]` and `[1]` individually. */
+    /** `[darkModeColor, lightModeColor]` hex strings. */
     $hoverColors?: string[];
-    /** `hoverBackgroundColors` — same shape as `$hoverColors`. */
+    /** Same shape as `$hoverColors`. */
     $hoverBackgroundColors?: string[];
 }
 export declare const ContextMenuItem: 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>>, ContextMenuItemStyleProps>, never>> & string;

package/types/components/widgets/ContextMenu/ContextMenuItemsGroup/ContextMenuItemsGroup.d.ts

@@ -2,24 +2,6 @@ import React from 'react';
 type ContextMenuItemsGroupOwnProps = {
     /**
      * Nodes of the `ContextMenuItem` component — one, or an array.
-     *
-     * DEFECT FIXED, NOT TRANSCRIBED. The propTypes said
-     * `children: PropTypes.arrayOf(PropTypes.node)`, and the codemod faithfully rendered
-     * that as `React.ReactNode[]` — which REJECTS A SINGLE JSX CHILD, because React does not
-     * wrap one child in an array:
-     *
-     *     <ContextMenuItemsGroup><ContextMenuItem title="Edit" /></ContextMenuItemsGroup>
-     *
-     * gives `children` as one element. On React 16 this was a dev-time propTypes warning
-     * only, which is how it survived — the React 16 gate is what surfaced it. Under the
-     * generated closed type it became a hard COMPILE error at every such call site, in the
-     * consumer as well as here, so faithfully reproducing the propTypes would have shipped a
-     * type that forbids the component's most obvious usage.
-     *
-     * `React.ReactNode` is the accurate type and it still admits the array form, since
-     * `ReactNode` includes `Iterable<ReactNode>`. The component only forwards `children` to
-     * `S.ContextMenuItemsGroup`, so nothing here depends on it being an array. Zero runtime
-     * change: the propTypes this replaces were already deleted by the codemod.
      */
     children?: React.ReactNode;
 };

package/types/components/widgets/InfoCard/InfoCard.styled.d.ts

@@ -1,28 +1,11 @@
 /**
- * `height` — `PropTypes.number`, px, interpolated as `${props.height}px` with a `50px`
- * fallback. `number` and not `number | string`: a string here would already render
- * `height: 60pxpx`.
- *
- * NO `$`, AND THAT IS A DEFECT THAT IS ALREADY IN THE RENDER BASELINE. `height` is not a
- * member of `HTMLAttributes<HTMLDivElement>` (which is why the read needs this
- * declaration at all) but React DOES recognise it and renders it, so `widgets/InfoCard`
- * in `scripts/r19-harness/baseline.json` opens with `<div height="60" class="…">`.
- * Renaming it `$height` removes that attribute and therefore MOVES the baseline — C10
- * work, §E.4.
+ * `height` as number (px); NO `$` prefix to preserve existing DOM baseline (already in r19-harness).
  */
 export interface InfoCardContainerStyleProps {
     height?: number;
 }
 /**
- * `$isHovered` — the `Link`'s hover state, held in `InfoCard.tsx`'s `useState`, so
- * genuinely `boolean` and not derived from any prop.
- *
- * NOT COVERABLE BY THE RENDER GATE, and the fixture says so: it comes from `useState`, so
- * it is `false` in every static render whatever props are passed. Both of its hosts
- * therefore have rule blocks the baseline can never exercise — which is exactly why the
- * type matters here more than it would on a prop a fixture pins.
- *
- * Hosts: `ButtonLink` and `StyledArrowIcon`.
+ * `$isHovered` from useState; not coverable by render gate (always false at baseline).
  */
 interface InfoCardHoverStyleProps {
     $isHovered?: boolean;

package/types/components/widgets/InstructionSeverityDisplay/InstructionSeverityDisplay.styled.d.ts

@@ -1,35 +1,25 @@
 /**
- * Card's props, i.e. what `InstructionSeverityDisplay.tsx` passes to `S.Card`.
- * Value types from that file's propTypes; all optional per §J.5.
+ * Card's props — what `InstructionSeverityDisplay.tsx` passes to `S.Card`; all optional.
  */
 export interface CardStyleProps {
-    /** `severity` — `PropTypes.oneOf([1, 2, 3, 4, 5])`. Closed on purpose: the template
-     *  compares `=== 5`, and a comparison against a value outside the union is TS2367
-     *  rather than a branch that never fires. */
+    /** Severity level 1-5; closed to allow === 5 comparison without TS2367. */
     $severity?: 1 | 2 | 3 | 4 | 5;
-    /** `showCard` — component defaults it to `true`, but see §J.5: a default in the
-     *  COMPONENT is not a default here, so this stays optional. */
+    /** Show card styling; optional here even though component defaults to true. */
     $showCard?: boolean;
-    /** `padding` — a whole CSS padding shorthand, e.g. `'8px 6px'`. `string`, not
-     *  `number`: the template uses it raw (`padding: ${props.$padding}`) with a
-     *  `'14px 10px'` fallback, so a number would emit a unitless `padding: 8`. */
+    /** CSS padding shorthand as string, e.g. `'8px 6px'`; fallback `'14px 10px'`. */
     $padding?: string;
-    /** `bgLight` — CSS colour applied under `body.light-theme`. */
+    /** CSS colour under `body.light-theme`. */
     $bgLight?: string;
-    /** `bgDark` — CSS colour applied under `body.dark-theme`. */
+    /** CSS colour under `body.dark-theme`. */
     $bgDark?: string;
-    /** Derived in the component as `thumbnail !== undefined`, so genuinely `boolean`
-     *  and not the `string` the `thumbnail` prop is. */
+    /** Derived as `thumbnail !== undefined`; boolean not string. */
     $hasThumbnail?: boolean;
 }
 /** InstructionText's props. */
 interface InstructionTextStyleProps {
-    /** `detailsFontSize` — a font-size with its unit, e.g. `'12px'`, `'0.875rem'`.
-     *  `string` for the same reason as `$padding`: it is interpolated raw. */
+    /** Font-size as string with unit, e.g. `'12px'`, `'0.875rem'`; interpolated raw. */
     $fontSize?: string;
-    /** `maxLines` — `PropTypes.number`, the `-webkit-line-clamp` count. Read only
-     *  behind `props.$maxLines &&`, which is what keeps it valid when
-     *  `strictNullChecks` is eventually turned on. */
+    /** Line-clamp count for `-webkit-line-clamp`; used only behind `props.$maxLines &&`. */
     $maxLines?: number;
 }
 export declare const Card: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, CardStyleProps>, never>> & string;

package/types/components/widgets/Instructions/Instructions.styled.d.ts

@@ -1,21 +1,9 @@
 /**
- * `TopBarContainer`, the only component in this file that reads a prop.
+ * TopBarContainer — the only component in this file that reads a prop.
  */
 interface InstructionsTopBarStyleProps {
     /**
-     * `initialHover` — `Instructions.tsx`'s `useState(true)`, so genuinely `boolean` and not
-     * derived from any prop. Transient, so it never reaches the DOM.
-     *
-     * READ, PASSED, AND NEVERTHELESS INERT — recorded, not fixed. The rule it guards is
-     * `themeProp('background', '#634E01', getColor('signal-yellow-400'))`, character for
-     * character the same declaration as the UNCONDITIONAL one three lines above it. So
-     * whichever way `$initialHover` goes, the emitted background is identical and the
-     * conditional only ever adds a duplicate of the rule that precedes it.
-     *
-     * Deleting it is the fix, and it is not a type-only change: removing the block removes a
-     * duplicate declaration from the generated CSS and therefore moves the render baseline
-     * (§J.8). Whether the intent was a DIFFERENT hover colour is a question for whoever owns
-     * the design, not for this commit.
+     * `$initialHover` is inert: its conditional rule duplicates the unconditional one above it.
      */
     $initialHover?: boolean;
 }

package/types/components/widgets/ProgressBar/ProgressBar.styled.d.ts

@@ -1,58 +1,21 @@
-/**
- * `height` — `PropTypes.number`, px, interpolated as `${props.height}px` with a `50px`
- * fallback, so `number` and not `number | string`.
- *
- * NO `$`, AND THAT IS A DEFECT THAT IS ALREADY IN THE RENDER BASELINE. `height` is not a
- * member of `HTMLAttributes<HTMLDivElement>` — hence the declaration — but React does
- * recognise it and renders it, so `widgets/ProgressBar` in
- * `scripts/r19-harness/baseline.json` opens with `<div height="50" class="…">`. Renaming
- * it `$height` removes that attribute and MOVES the baseline — C10, §E.4.
- */
 interface ProgressBarContainerStyleProps {
+    /** `height` — px, so `number`. No `$` but defect in baseline. */
     height?: number;
 }
-/**
- * `$hasLink` — `Boolean(linkText)`, so genuinely boolean and not `linkText`'s `string`.
- *
- * Declared for `MetricsContainer` only. `ProgressBar.tsx` also passes `$hasLink` to
- * `PercentageIndicator`, WHICH NEVER READS IT — so per rule 2 (declare only what is
- * actually consumed) that component gets no generic, and the pass is recorded here as the
- * dead prop it is. It is transient, so it does not reach the DOM either way.
- */
 interface ProgressBarMetricsStyleProps {
+    /** `$hasLink` — declared for MetricsContainer only; PercentageIndicator never reads it. */
     $hasLink?: boolean;
 }
-/** `ProgressBarFill`, the one component here whose props are read from two places. */
 interface ProgressBarFillStyleProps {
-    /**
-     * `type` — `PropTypes.string`, selecting a row of `colorMap`. Left as `string` rather
-     * than narrowed to the five `colorMap` keys, because `string` is what the published
-     * propTypes say; narrowing it here would invent a contract the component does not have
-     * (§E.1 rule 2). The `|| colorMap.default` fallback is what makes that safe.
-     *
-     * NO `$`, AND THAT IS A DEFECT ALREADY IN THE RENDER BASELINE — but on OTHER components.
-     * `ProgressBar.tsx` passes `type` to `InnerContainer`, `Completed` and `ProgressBarFill`
-     * alike; the first two never read it, and a string-valued `type` renders on a `<div>`,
-     * so `widgets/ProgressBar` records `<div type="success">` twice. Renaming it removes
-     * those attributes — C10, §E.4.
-     */
+    /** `type` — left as `string` to match propTypes contract; has `colorMap.default` fallback. */
     type?: string;
-    /** `barColor` — `PropTypes.string`, a whole CSS colour that short-circuits `colorMap`
-     *  entirely. NO `$` either, and it is unread by any other component, so it leaks only
-     *  from this one and only when a consumer passes it — no fixture does. */
+    /** `barColor` — whole CSS colour that short-circuits `colorMap`. */
     barColor?: string;
-    /** `(completedAssets / totalAssets) * 100`, interpolated as `${props.$percentage}%`, so
-     *  `number`. Not rounded — the rounding is only for the label text. */
+    /** `(completedAssets / totalAssets) * 100`, interpolated as `%`. */
     $percentage?: number;
 }
-/**
- * `$isHovered` — the `Link`'s hover state from `ProgressBar.tsx`'s `useState`, so
- * genuinely `boolean`. Like `InfoCard`'s, it is `false` in every static render, so the
- * rule blocks it guards are unreachable from the render gate.
- *
- * Hosts: `ButtonLink` and `StyledArrowIcon`.
- */
 interface ProgressBarHoverStyleProps {
+    /** `$isHovered` — hover state from `useState`. Hosts: `ButtonLink` and `StyledArrowIcon`. */
     $isHovered?: boolean;
 }
 export declare const ProgressBar: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLParagraphElement>, HTMLParagraphElement>>, never>, never>> & string;

package/types/components/widgets/SummaryCard/SummaryCard.styled.d.ts

@@ -1,56 +1,17 @@
-/** The card root, i.e. what `SummaryCard.tsx` passes to `<S.SummaryCard>`. */
+/** Card root props; what `SummaryCard.tsx` passes to `<S.SummaryCard>`. */
 export interface SummaryCardStyleProps {
-    /**
-     * `view` — `PropTypes.string`. The template tests `=== 'compact'` twice and treats every
-     * other value as the grid view. Left as `string` rather than narrowed to
-     * `'compact' | 'grid'`: that is what the published propTypes say, and narrowing it here
-     * would invent a contract the component does not have (§E.1 rule 2). Note the asymmetry
-     * with `AssetGalleryCompactCard`'s `type`, which IS narrowed — there the propTypes
-     * really do declare a closed set.
-     *
-     * NO `$`, AND THAT IS A DEFECT ALREADY IN THE RENDER BASELINE. A string-valued `view`
-     * renders on a `<div>`, so `widgets/SummaryCard` records `<div width="300" view="grid">`
-     * and its `#compact` variant records `view="compact"`. Renaming it removes that
-     * attribute and MOVES the baseline — C10, §E.4.
-     */
+    /** `view` as string (not narrowed to 'compact'|'grid'); NO `$` to preserve existing DOM baseline. */
     view?: string;
-    /**
-     * `width` — `PropTypes.number`, px, interpolated as `${props.width}px` with a `100%`
-     * fallback, so `number` and not `number | string`.
-     *
-     * NO `$`, AND ALSO ALREADY IN THE BASELINE: `<div width="300" …>` on the same element.
-     * `width` is not a member of `HTMLAttributes<HTMLDivElement>` — hence the declaration —
-     * but React recognises and renders it. C10, §E.4.
-     */
+    /** `width` as number (px); NO `$` to preserve existing DOM baseline. */
     width?: number;
-    /** `useBorder` — `PropTypes.bool`; the component defaults it to `false`, which is not a
-     *  default HERE (nothing but `theme` is injected by `applyDefaultTheme`), so it stays
-     *  optional per §J.5. */
+    /** `useBorder` — optional here even though component defaults to false. */
     $useBorder?: boolean;
 }
-/**
- * `Gutter`, the spacer component. `SummaryCard.tsx` renders it seven times and passes
- * `$gutter` every time.
- */
+/** Gutter spacer component; rendered seven times by `SummaryCard.tsx`. */
 interface SummaryCardGutterStyleProps {
-    /** `$gutter` — px, always a literal (`4`, `8` or `16`) at the seven call sites, so
-     *  `number`. The `|| 8` fallback is unreachable from inside this library. */
+    /** `$gutter` — always a literal (4, 8, or 16) at the call sites; number. */
     $gutter?: number;
-    /**
-     * `renderAsMargin` IS READ AND NEVER PASSED — DECLARED, NOT FIXED.
-     *
-     * None of the seven `<S.Gutter>` sites passes it and nothing else in `src` constructs
-     * this component, so the `if` branch below never runs: `margin-bottom` is never emitted
-     * and the `else` branch is what always applies. And the `else` branch is REDUNDANT with
-     * the unconditional `padding-bottom` on the line after the block, which emits the same
-     * declaration a second time — so today the whole conditional contributes nothing at all.
-     *
-     * Two separate things to fix, neither of them here: wiring up `renderAsMargin` is a
-     * feature, and deleting the dead conditional REMOVES a duplicate declaration from the
-     * generated CSS and therefore moves the baseline (§J.8). It also has NO `$`, though
-     * that part is harmless: React drops an unrecognised camelCase prop whose value is
-     * `true`, so it could not reach the DOM even if it were passed.
-     */
+    /** `renderAsMargin` — read but never passed; conditional here is dead code. */
     renderAsMargin?: boolean;
 }
 export declare const SummaryCard: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, SummaryCardStyleProps>, never>> & string;

package/types/hooks/useElementSize.d.ts

@@ -1,25 +1,14 @@
 import type { RefObject } from 'react';
-/** The layout box this hook reports: `offsetWidth` / `offsetHeight`, in px. */
 export interface ElementSize {
     width: number;
     height: number;
 }
 /**
- * Tracks an element's `offsetWidth` / `offsetHeight` across window resizes.
+ * Tracks element offsetWidth and offsetHeight across window resizes.
  *
- * `ref` IS REQUIRED AND NOT NULLABLE, because the body reads `ref.current`
- * without a guard — passing `null` throws. The type records the existing
- * contract rather than papering over it; adding `?.` would be a behaviour
- * change, and this commit is type-only.
- *
- * NOTE FOR WHOEVER TOUCHES THIS NEXT: this hook has zero importers in `src`, is
- * not reachable through `package.json#exports` (there is no `./hooks` entry),
- * and a grep of the `ntb-dam` consumer finds no use of it. Playbook §A.2/C8
- * schedules it for deletion for exactly that reason. It is typed here rather
- * than deleted because deletion is a separate, labelled commit — but do not
- * invest further in it before checking whether it should exist at all.
+ * Ref is required (not nullable) — the body reads ref.current without a guard.
  *
  * @param ref                     element to measure
- * @param delayWindowResizeUpdate debounce window for the `resize` handler, in ms
+ * @param delayWindowResizeUpdate debounce window for the resize handler, in ms
  */
 export declare function useElementSize<T extends HTMLElement = HTMLElement>(ref: RefObject<T | null>, delayWindowResizeUpdate?: number): ElementSize;