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

package/types/hooks/useEventListner.d.ts

@@ -1,46 +1,14 @@
 import type { RefObject } from 'react';
-/**
- * Every event name this hook accepts, mapped to the event object the handler
- * actually receives.
- *
- * AN INTERSECTION, NOT `interface DomEventMap extends WindowEventMap,
- * HTMLElementEventMap, DocumentEventMap {}`. The three lib.dom maps share keys
- * through `GlobalEventHandlersEventMap`, and an interface extending all three is
- * a TS2320 candidate ("named property 'X' of types … are not identical") as soon
- * as two of them declare a shared key with types that are equivalent rather than
- * identical — a lib.dom detail that changes between TypeScript releases. An
- * intersection has no such rule: overlapping keys become `MouseEvent &
- * MouseEvent`, `keyof` is still the union of all three key sets, and lib.dom
- * stays the single source of truth for which event class each name carries. Do
- * not "tidy" this into an interface.
- *
- * All three maps are needed because the target is chosen at runtime:
- * `element?.current ?? window`.
- */
 export type DomEventMap = WindowEventMap & HTMLElementEventMap & DocumentEventMap;
-/** Any DOM event name this hook accepts — `keyof DomEventMap`. */
 export type DomEventName = keyof DomEventMap;
 /**
- * Subscribes to a DOM event for the lifetime of the component, always calling
- * the latest `handler` without re-subscribing when it changes identity.
- *
- * `element` AND `options` ARE OPTIONAL, AND THAT IS THE ENTIRE FIX FOR THE
- * TS2554 ARITY ERRORS IN THIS DIRECTORY. In JavaScript a missing argument is
- * `undefined`; in TypeScript a parameter with neither `?` nor a default is
- * REQUIRED. Annotating the original four parameters without marking the last two
- * optional is what made every existing 2- and 3-argument call site a hard error
- * (`useOnClickOutside.ts:4`, `useElementSize.ts:22`,
- * `MultiLevelCheckboxSelect.tsx:65-67`). `element` really is optional — the hook
- * falls back to `window` — and `options` really is optional, so the declaration
- * below records what this function has always done. The body is unchanged.
+ * Subscribes to a DOM event for the component lifetime, always calling the latest handler.
+ * Element and options are optional (fall back to window and no options).
  *
- * @param eventName any DOM event name; it selects the handler's event type
- * @param handler   receives the event. Stored in a ref, so it may be a fresh
- *                  closure on every render without rebinding the listener
- * @param element   ref to the target. Omit it — or pass a ref whose `current` is
- *                  still `null` — to listen on `window`
- * @param options   forwarded verbatim to `addEventListener` and
- *                  `removeEventListener`
+ * @param eventName any DOM event name; selects the handler's event type
+ * @param handler   received event; stored in a ref so closures don't rebind the listener
+ * @param element   target ref; omit to listen on `window`
+ * @param options   forwarded to addEventListener and removeEventListener
  */
 declare function useEventListener<K extends DomEventName, T extends EventTarget = HTMLElement>(eventName: K, handler: (event: DomEventMap[K]) => void, element?: RefObject<T | null> | null, options?: boolean | AddEventListenerOptions): void;
 export { useEventListener };

package/types/hooks/useFloatingPopover.d.ts

@@ -1,61 +1,8 @@
 import { useInteractions, useTransitionStyles } from '@floating-ui/react';
 import type { Middleware, OpenChangeReason, Placement, UseClickProps, UseDismissProps, UseFloatingReturn, UseFocusProps, UseHoverProps, UseTransitionStylesProps } from '@floating-ui/react';
-/**
- * THE ARROW HEIGHT, RE-DERIVED — AND THE `+15` IN `Popover.tsx` WAS NEVER A FUDGE.
- *
- * `Popover.tsx` computes `const errorOffset = useMemo(() => (arrow ? 15 : 0), [arrow])`
- * and passes `offset={[offset[0], offset[1] + errorOffset]}`. The name says the
- * 15 is a correction for a mistake. It is not: it is the arrow's height, and here
- * is the measurement chain.
- *
- * 1. `Popover.styled.ts` OVERRIDES tippy's default arrow geometry. For a top
- *    placement it writes `border-width: 15px 13px 0` on both `.tippy-arrow::before`
- *    and `::after` — a CSS border triangle **15px tall on a 26px base**
- *    (13px + 13px). The same 15/13 pair appears on all four sides.
- * 2. The FILL layer, `& > .tippy-arrow:after`, is positioned `bottom: -15px`. The
- *    `.tippy-arrow` box's bottom edge is the `.tippy-box` edge, so all 15px of
- *    that triangle sit OUTSIDE the box: **the arrow protrudes exactly 15px.**
- *    (The outline layer, `::before`, is at `-16px` — 1px further out. That 1px is
- *    the popover's border continued around the arrow, not extra arrow.)
- * 3. So with `offset={[0, 8]}` (the `Popover` default) plus 15, tippy puts the BOX
- *    23px from the reference and the arrow TIP 23 − 15 = **8px** from it. The
- *    public `offset` prop has therefore always meant "gap between the arrow tip
- *    and the reference", and `15` is the term that makes it mean that.
- * 4. Floating UI's `FloatingArrow` positions its `<svg>` at `[side]: '100%'` —
- *    flush against the outside edge of the floating element — so the full
- *    `height` prop protrudes, exactly like tippy's fill layer. Therefore
- *    `mainAxis = distance + height` reproduces today's geometry when, and only
- *    when, `height === 15`.
- *
- * Get this wrong and it is immediately visible: leaving Floating UI's own default
- * `height = 7` would put a 7px arrow in a 23px gap (16px of daylight between tip
- * and reference), and dropping the term would put the box 8px out with a 15px
- * arrow, i.e. the tip 7px INSIDE the reference.
- *
- * One sub-pixel inconsistency does not survive: tippy's bottom-placement fill
- * layer is at `top: -14.5px`, half a pixel less than the other three sides. 15 is
- * used uniformly here.
- *
- * The `Tooltip` arrow is a different size — it never overrode tippy's default
- * geometry — and its number is derived at `TOOLTIP_ARROW` in
- * `src/components/data/_shared/FloatingArrow.styled.ts`, which also re-exports
- * this constant as the popover arrow's height so the offset maths and the rendered
- * `<svg>` cannot disagree.
- */
 export declare const DEFAULT_ARROW_HEIGHT = 15;
-/**
- * The placement vocabulary of our public props: Floating UI's `Placement` plus
- * Popper's three `auto` values.
- *
- * The 12 concrete names are identical in both libraries (`bottom-end`,
- * `right-start`, …) so they need no translation. `auto*` has no Floating UI
- * equivalent — it is a different middleware — which is handled in
- * `buildMiddleware` below.
- */
 export type PopoverPlacement = Placement | AutoPlacement;
-/** Popper's three `auto` values, which Floating UI has no string for. */
 export type AutoPlacement = 'auto' | 'auto-start' | 'auto-end';
-/** Popper's `offset` modifier shape: `[skidding, distance]`. */
 export type PopperOffset = readonly [skidding: number, distance: number];
 /** What `useFloatingPopover` accepts. Every member is optional. */
 export interface UseFloatingPopoverOptions {
@@ -87,15 +34,8 @@ export interface UseFloatingPopoverOptions {
      */
     trigger?: string | null;
     /**
-     * Popper's `[skidding, distance]`, where `distance` is the gap between the
-     * ARROW TIP and the reference (rule 3 in the file header). `skidding` maps to
-     * Floating UI's `crossAxis` and NOT `alignmentAxis`: Popper applies skidding as
-     * a plain shift along the cross axis with no sign flip for `-end` placements
-     * (`distanceAndSkiddingToXY` in `@popperjs/core`), which is `crossAxis`'s
-     * behaviour, whereas `alignmentAxis` inverts on `end`. Every consumer offset
-     * measured so far is `[0, n]`, so the distinction is currently unobservable —
-     * which is exactly why it is written down rather than discovered later.
-     *
+     * `[skidding, distance]` where distance is the arrow-tip gap (see `DEFAULT_ARROW_HEIGHT`).
+     * Skidding maps to Floating UI's `crossAxis` (no sign flip for `-end` placements).
      * @default [0, 0]
      */
     offset?: PopperOffset;
@@ -115,15 +55,8 @@ export interface UseFloatingPopoverOptions {
      */
     arrowHeight?: number;
     /**
-     * tippy's `interactive`: the pointer may travel from the reference into the
-     * floating element without closing it. Implemented as
-     * `useHover(context, { handleClose: safePolygon() })`, which is only
-     * meaningful for a hover trigger — a click-triggered popover is "interactive"
-     * by construction.
-     *
-     * Also decides `pointerEvents` in the return value, because tippy sets
-     * `pointer-events: none` on its popper root for a non-interactive instance.
-     *
+     * Pointer can travel from reference to floating element without closing.
+     * Also determines `pointerEvents` in the return value.
      * @default false
      */
     interactive?: boolean;
@@ -148,13 +81,8 @@ export interface UseFloatingPopoverOptions {
      */
     transition?: Omit<UseTransitionStylesProps, 'duration'>;
     /**
-     * `useDismiss` overrides. The hook's own defaults are tippy's behaviour:
-     * `outsidePress: true` (tippy's `hideOnClick` default), `referencePress: false`
-     * (tippy explicitly does NOT hide when a hover-triggered reference is pressed)
-     * and `escapeKey: false` (rule 4 in the file header).
-     *
-     * `enabled` is NOT overridable — it is `!disabled`, because a disabled instance
-     * has nothing to dismiss.
+     * `useDismiss` overrides. Defaults match tippy: `outsidePress: true`,
+     * `referencePress: false`, `escapeKey: false`. `enabled` is `!disabled`.
      */
     dismiss?: Omit<UseDismissProps, 'enabled'>;
     /** `useHover` overrides, e.g. `restMs`. `enabled` and `handleClose` are owned here. */
@@ -162,21 +90,12 @@ export interface UseFloatingPopoverOptions {
     /** `useClick` overrides. `enabled` is owned here. */
     click?: Omit<UseClickProps, 'enabled'>;
     /**
-     * `useFocus` overrides. `enabled` is owned here, and `visibleOnly` DEFAULTS TO
-     * `false` rather than Floating UI's `true`: tippy's `focus`/`focusin` triggers
-     * attach a plain `focusin` listener with no `:focus-visible` test, so leaving
-     * `visibleOnly` at `true` would stop every `trigger="mouseenter focus"` tooltip
-     * from opening on a mouse-driven focus. 6 consumer call sites pass
-     * `"mouseenter focus"`.
+     * `useFocus` overrides. `visibleOnly` defaults to `false` (not Floating UI's `true`)
+     * to match tippy's plain focusin listener without :focus-visible test.
      */
     focus?: Omit<UseFocusProps, 'enabled'>;
     /**
-     * Cap the floating element's height to the space available, replacing the
-     * `popper-max-size-modifier` + `applyMaxSize` pair in `Popover.tsx`.
-     *
-     * OPT-IN, because only `Popover` has it today. Turning it on for `Tooltip`
-     * would add a `max-height` to every tooltip in both consumers.
-     *
+     * Cap floating element height to available space. Opt-in; only Popover uses it.
      * @default false
      */
     constrainHeight?: boolean;

package/types/hooks/useIsomorphicLayoutEffect.d.ts

@@ -1,26 +1,3 @@
 import type { DependencyList, EffectCallback } from 'react';
-/**
- * `useLayoutEffect` in the browser, `useEffect` on the server.
- *
- * WHY THE ANNOTATION IS EXPLICIT RATHER THAN INFERRED. The two hooks have
- * identical signatures, so the inferred type of the ternary is a UNION of two
- * call signatures — and a union of signatures is only callable through their
- * intersection, which is a worse thing to hand 1 call site and every future one
- * than the single signature they agree on. Naming that signature is also what
- * the deleted `@type` JSDoc was clumsily trying to say by listing the same
- * signature twice.
- *
- * WHY THE RUNTIME TERNARY MUST STAY A RUNTIME TERNARY. The two hooks are
- * interchangeable to the type system and NOT interchangeable to React:
- * `useLayoutEffect` logs "useLayoutEffect does nothing on the server" under
- * `renderToStaticMarkup` — which the render gate captures as a warning with its
- * own exit code — and it runs before paint rather than after it. So this file
- * cannot be simplified into a plain re-export, and no type here can protect
- * that. Hence this comment.
- *
- * `typeof window !== 'undefined'` is evaluated ONCE, at module scope, on
- * purpose: the choice must not vary between renders or React sees a different
- * hook in the same slot.
- */
 declare const useIsomorphicLayoutEffect: (effect: EffectCallback, deps?: DependencyList) => void;
 export default useIsomorphicLayoutEffect;

package/types/hooks/useOnClickOutside.d.ts

@@ -1,31 +1,13 @@
 import type { DomEventMap } from './useEventListner';
 import type { RefObject } from 'react';
-/**
- * The event names this hook can watch for. Narrower than `DomEventName` on
- * purpose — the parameter is called `mouseEvent`, and a non-pointer event name
- * here would silently never fire the outside-click check.
- */
 export type OutsideClickEventName = 'mousedown' | 'mouseup' | 'click';
-/**
- * What the handler receives. DERIVED from `DomEventMap` rather than written as
- * `MouseEvent`, so it follows lib.dom if a future TypeScript retypes any of
- * these three names (`click` has already moved between `MouseEvent` and
- * `PointerEvent` upstream).
- */
 export type OutsideClickEvent = DomEventMap[OutsideClickEventName];
 /**
- * Calls `handler` when the chosen pointer event happens anywhere outside `ref`'s
- * element and its descendants.
- *
- * `ref` IS TYPED AS NULLABLE BECAUSE THE BODY READS `ref?.current`. That is not
- * defensiveness copied from elsewhere — it is the existing runtime contract, so
- * the type records it. Contrast `useElementSize`, whose body reads `ref.current`
- * and whose `ref` is therefore required.
+ * Fires handler on pointer events outside ref (and its descendants).
+ * Ref is nullable — the runtime contract checks ref?.current.
  *
- * @param ref        the "inside" element. A click on it or on any descendant is
- *                   ignored
- * @param handler    called with the originating event for outside clicks only
- * @param mouseEvent which event to listen for; defaults to `'mousedown'` so the
- *                   callback fires before a click can move focus
+ * @param ref        the "inside" element; clicks on it or descendants are ignored
+ * @param handler    called only for outside clicks
+ * @param mouseEvent event to listen for; defaults to `'mousedown'` (before focus moves)
  */
 export declare function useOnClickOutside<T extends Node = HTMLElement>(ref: RefObject<T | null> | null | undefined, handler: (event: OutsideClickEvent) => void, mouseEvent?: OutsideClickEventName): void;

package/types/hooks/useTooltipAutoShow.d.ts

@@ -13,68 +13,19 @@ export interface TooltipAutoShow {
     /** `true` while there is no content, which suppresses the tooltip entirely. */
     toolTipDisabled: boolean;
     /**
-     * `true` | `undefined` — NEVER `false`, AND THE `undefined` IS LOAD-BEARING.
-     * `Tooltip` treats `visible` as the switch between UNCONTROLLED and CONTROLLED
-     * mode: `undefined` leaves the tooltip under its own `trigger` prop
-     * (hover/focus), while any boolean — including `false` — hands control to us
-     * permanently and the tooltip stops responding to hover for the rest of its
-     * life. So this type is `true | undefined` rather than the `boolean` it looks
-     * like it wants to be. DO NOT "SIMPLIFY" IT: widening to `boolean` compiles
-     * fine and silently breaks every hover tooltip in `TextArea` and
-     * `CompactTextInput`.
-     *
-     * That rule was tippy's and is now the library's own: `useFloatingPopover`
-     * decides controlled-ness with `typeof open === 'boolean'`, so this contract
-     * survived the Floating UI migration unchanged and deliberately.
-     *
-     * ONE SEMANTIC DIFFERENCE, RECORDED BECAUSE IT IS REAL EVEN THOUGH THE
-     * OBSERVABLE OUTCOME IS THE SAME. Going from `true` back to `undefined` used
-     * to leave the tippy instance SHOWN — `@tippyjs/react` only issues an
-     * imperative `show()`/`hide()` while `visible !== undefined`, so dropping out
-     * of controlled mode issued nothing and the tooltip stayed up until the
-     * reference's own `mouseleave` hid it. `useFloatingPopover` instead resolves
-     * to its uncontrolled state, which is closed. Both end with the tooltip
-     * hidden, because the caller drives this from `onMouseLeave` and that same
-     * pointer exit is what used to hide it; the new path just does not depend on a
-     * second event arriving.
+     * `true | undefined`, never `false`. Any boolean (including `false`) switches
+     * to controlled mode and disables hover triggering. `undefined` means uncontrolled;
+     * `true` means force-visible. This contract is checked by `useFloatingPopover`
+     * with `typeof open === 'boolean'`.
      */
     toolTipVisible: true | undefined;
 }
 /**
- * Tracks a tooltip's content and automatically forces it to be visible when the
- * content transitions from empty → non-empty, then defaults to trigger prop.
+ * Tracks tooltip content and forces visibility when content transitions from
+ * empty → non-empty, then defaults to trigger prop.
  *
- * ================== PLAN C8, DECIDED: THIS STAYS A SEPARATE HOOK ==================
- *
- * The plan asks whether `useFloatingPopover` should absorb this. It should not,
- * and the premise of the question turned out to be wrong.
- *
- * 1. **It does not read tippy's imperative instance API.** The plan describes it
- *    as doing so, but measured — `grep -i tippy` over this file — the only match
- *    is prose. There is no `_tippy`, no instance handle, no `show()`/`hide()`,
- *    and no tippy import. Whatever was true when the plan was written, the
- *    TypeScript migration left a hook that is pure React: two refs, one
- *    `useState`, one `useEffect`.
- * 2. **What it depends on is a CONTRACT, not an implementation**, namely the
- *    `undefined`-means-uncontrolled rule documented on `toolTipVisible`.
- *    `useFloatingPopover` preserves that rule exactly, so this file needed no
- *    behavioural change to survive the migration — and did not get one.
- * 3. **Merging it would put the wrong responsibility in the wrong place.** This
- *    is a content-change detector: it compares the previous `content` string with
- *    the current one and force-shows on the empty → non-empty edge.
- *    `useFloatingPopover` owns position and interaction and never reads `content`
- *    at all. Absorbing this would mean giving the positioning hook a `content`
- *    parameter and a sticky-previous-value state machine for the benefit of the
- *    two call sites that want it, out of the five it is meant to serve — three of
- *    which (`SummaryCard`, `AssetAction`, `AssetGalleryCompactCard`) have no
- *    content prop to diff.
- *
- * So the change here is documentation only: the JSDoc used to attribute the
- * controlled-mode rule to tippy, and tippy is going away.
- *
- * @param content the tooltip text. `string`, because both call sites declare
- *                `descriptionToolTip: PropTypes.string` with a `''` default —
- *                the sticky `displayContent` ref would not survive a `ReactNode`
+ * @param content the tooltip text. `string`, not `ReactNode`, because both call sites
+ *                use it with an empty-string default.
  */
 declare function useTooltipAutoShow(content?: string): TooltipAutoShow;
 export default useTooltipAutoShow;

package/types/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/utils/dateTime.d.ts

@@ -2,12 +2,7 @@
  * Convert time given in miliseconds to a string representation of hours, minutes and seconds
  * in the format HH:MM:SS
  *
- * The hours segment is omitted entirely for durations under an hour, so the
- * result is `MM:SS` there — the `HH:` above is the maximal form, not a promise
- * about width. Both call sites (`AssetGalleryGridCard`,
- * `AssetGalleryCompactCard`) feed it straight into a `Badge`.
- *
- * @param ms duration in milliseconds. `number`, not `number | string`: the body
- *           divides it, and a string would produce `NaN:NaN` rather than fail
+ * Hours are omitted for durations under an hour (result is MM:SS).
+ * @param ms duration in milliseconds as number (not string, to avoid NaN)
  */
 export declare const convertMsToHMS: (ms: number) => string;

package/types/utils/defaultTheme.d.ts

@@ -1,67 +1,31 @@
 import type { ColorName } from '../styles/utils/colors-export';
 import type { Interpolation, RuleSet } from 'styled-components';
 export type { ColorName };
-/**
- * Looks up a design-token colour.
- *
- * Throws at runtime for an unregistered name, which is why the parameter is the
- * closed `ColorName` union rather than `string`: the error moves from a runtime
- * throw inside a styled template to a compile error at the call site.
- */
 export type GetColor = (name: ColorName) => string;
-/**
- * A value `themeProp` interpolates into the generated rule. Widened to
- * styled-components' own `Interpolation` because that is literally what happens
- * to it — six call sites in `Badge.styled.ts` and `Tabs.styled.ts` pass a
- * `() => string` callback rather than a string, and two in `TextInput.styled.ts`
- * pass numbers. The guarantee this type buys is ARITY, not value narrowness.
- */
 export type ThemePropValue = Interpolation<object>;
 /**
- * Emits one declaration three times — for `body.dark-theme`, for
- * `body.light-theme`, and for neither-class-set with a
- * `prefers-color-scheme: dark` fallback — so a single property can differ
- * between themes.
- *
- * TWO REPO CONVENTIONS THE TYPE SYSTEM CANNOT ENFORCE, and both cause real
- * visual bugs when broken:
+ * Emits three declarations: body.dark-theme, body.light-theme, and
+ * neither-class with prefers-color-scheme fallback, so one property can
+ * differ between themes.
  *
- * - **Never call `themeProp()` inside an `&::after` / `&::before` block.** The
- *   generated `body.dark-theme &&` selector cannot address a pseudo-element from
- *   inside one. Write the two rules out explicitly instead:
- *   `body.light-theme &::after { … }` and `body.dark-theme &::after { … }`.
+ * Two unenforceable conventions that cause visual bugs: (1) Don't call inside
+ * `&::after` / `&::before` — generated selector can't address pseudo-elements;
+ * write rules explicitly instead. (2) Use static `&[data-x='state']` selectors,
+ * not dynamic `${props => css\`\`}` — dynamic rules share componentId, so
+ * instances collide.
  *
- * - **Prefer static `&[data-x='state']` selectors over dynamic
- *   `${props => css\`…\`}` rules for per-instance state.** Interpolated rules
- *   share the component's `componentId`, so two instances in different states
- *   collide and one wins for both.
- *
- * @param property   the CSS property, e.g. `color`, `background`, or a custom
- *                   property like `--checkbox-black-box`
- * @param darkMode   the value applied under `body.dark-theme`
- * @param lightMode  the value applied under `body.light-theme`, and the fallback
- *                   when neither class is present
- * @param specificity how many `&` to repeat in the generated selector. A NUMBER —
- *                   the implementation does `Array(specificity).fill('&')`, so a
- *                   string silently produces a one-element array and specificity
- *                   1. Typing it `number` is deliberate: it turns the one site
- *                   that passes `'!important'` here into a compile error rather
- *                   than blessing it.
+ * @param property    CSS property (e.g. color, background, --custom-prop)
+ * @param darkMode    value for body.dark-theme
+ * @param lightMode   value for body.light-theme (also fallback when no class)
+ * @param specificity how many `&` to repeat in selector; a number (prevents
+ *                    passing '!important' by mistake)
  */
 export type ThemeProp = (property: string, darkMode: ThemePropValue, lightMode: ThemePropValue, specificity?: number) => RuleSet<object>;
-/**
- * Spacing scale. Consumed by react-select through its own `theme` prop as well
- * as by our styled templates, which is why the member names are react-select's.
- */
 export interface ThemeSpacing {
     baseUnit: number;
     controlHeight: number;
     menuGutter: number;
 }
-/**
- * react-select's colour contract, filled from our palette. These names are
- * react-select's, not ours — do not rename them to design-token names.
- */
 export interface ThemeColors {
     primary: string;
     primary75: string;
@@ -80,17 +44,6 @@ export interface ThemeColors {
     neutral80: string;
     neutral90: string;
 }
-/**
- * The whole theme, as a styled template sees it.
- *
- * Every member is REQUIRED, which is the truth inside an interpolation
- * (`props.theme.getColor` is always there) and a constraint at the
- * `<ThemeProvider>` boundary. Nothing in this repo hands over a partial theme —
- * the only `ThemeProvider` is `.storybook/preview.js`, with the full
- * `defaultTheme`. A consumer that wants to override part of it uses
- * `PartialNtbTheme` + `applyDefaultTheme`, which is what every `.styled` file
- * here does.
- */
 export interface NtbTheme {
     getColor: GetColor;
     primaryFontFamily: string;
@@ -99,20 +52,7 @@ export interface NtbTheme {
     spacing: ThemeSpacing;
     colors: ThemeColors;
 }
-/** A theme override: any subset of `NtbTheme`. */
 export type PartialNtbTheme = Partial<NtbTheme>;
-/**
- * What `applyDefaultTheme` accepts.
- *
- * DELIBERATELY NOT `ExecutionProps & { theme?: PartialNtbTheme }`.
- * `ExecutionProps['theme']` is `DefaultTheme | undefined`, and after the
- * augmentation below `DefaultTheme` is `NtbTheme` with every member required —
- * so intersecting makes the override required again and the function's own
- * `theme = {}` default stops compiling (TS2322). Extra props still flow in
- * fine: this is a parameter position, so a caller passing the full styled
- * execution context is accepted and the runtime spreads the rest through
- * unchanged.
- */
 export interface ThemedProps {
     theme?: PartialNtbTheme;
 }
@@ -145,26 +85,7 @@ export declare const defaultTheme: {
         neutral90: string;
     };
 };
-/**
- * Applies a different css property value for dark and light mode.
- *
- * Read `ThemeProp` above before changing the signature — its JSDoc carries the
- * two conventions that the type system cannot enforce and that cause real
- * visual bugs when broken.
- */
 declare function themeProp(property: string, darkMode: ThemePropValue, lightMode: ThemePropValue, specificity?: number): RuleSet<object>;
-/**
- * `.attrs()` helper: merges a caller's partial theme over `defaultTheme` so
- * every interpolation can rely on the full contract.
- *
- * THE RETURN TYPE IS `{ theme: NtbTheme }` AND NOT `P & { theme: NtbTheme }`,
- * ON PURPOSE. `attrs` merges its result OVER the incoming props, so a declared
- * type only has to describe what this function CONTRIBUTES. Saying it also
- * returns the caller's props re-declares them from a position that knows nothing
- * about them, which is what produced the measured 25–31 TS2345 `.attrs()`
- * assignability errors. The runtime still spreads the rest through — that part
- * is unchanged, and 36 `.styled` files depend on it.
- */
 export declare function applyDefaultTheme({ theme, ...props }: ThemedProps): {
     theme: NtbTheme;
 };

package/types/utils/getElementRef.d.ts

@@ -1,21 +1,2 @@
 import * as React from 'react';
-/**
- * Reads a child element's `ref` across the peer range (`react >= 16.14`).
- *
- * `ref` is a regular prop only from React 19. Before that `createElement` moves it to
- * `element.ref`, so reading `element.props.ref` silently returns `undefined` and the
- * `cloneElement(children, { ref })` that follows destroys the child's ref.
- *
- * Neither location can be read unconditionally: React 19 warns on `element.ref`, React
- * 18.3 warns on `props.ref`. Both warnings are `console.error`, which the stories gate
- * fails on. The property SHAPE says which is live, measured on 19.2.4:
- *
- *   React 19, ref passed     props.ref data prop     element.ref warning getter
- *   React 19, no ref         props.ref absent        element.ref data prop (null)
- *   React <19                props.ref absent        element.ref data prop
- *   React 18.3, ref passed   props.ref warning get   element.ref data prop
- *
- * Returning early on React 19's data-property `props.ref` is what keeps every branch off
- * a warning getter.
- */
 export declare function getElementRef(element: React.ReactElement): React.Ref<unknown> | null;