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

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

@@ -0,0 +1,30 @@
+import React from 'react';
+import * as S from './ProgressBar.styled';
+type ProgressBarOwnProps = {
+    totalAssets: number;
+    completedAssets: number;
+    percentageText?: string;
+    barColor?: string;
+    height?: number;
+    label?: string;
+    type?: string;
+    linkText?: string;
+    onClick?: (...args: any[]) => any;
+};
+type Props = Omit<React.ComponentPropsWithoutRef<typeof S.Container>, keyof ProgressBarOwnProps> & ProgressBarOwnProps;
+/**
+ * ProgressBar that let you progress through a task.
+ *
+ *
+ * ### Import
+ *
+ * ``` js
+ * import { ProgressBar } from '@ntbjs/react-components/widgets/ProgressBar'
+ * // or
+ * import ProgressBar from '@ntbjs/react-components/widgets/ProgressBar'
+ * ```
+ *
+ *
+ */
+declare const ProgressBar: ({ totalAssets, completedAssets, percentageText, barColor, height, label, type, linkText, onClick, ...props }: Props) => React.JSX.Element;
+export default ProgressBar;

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

@@ -0,0 +1,78 @@
+/**
+ * `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?: 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?: 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?: 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?: string;
+    /** `(completedAssets / totalAssets) * 100`, interpolated as `${props.$percentage}%`, so
+     *  `number`. Not rounded — the rounding is only for the label text. */
+    $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?: 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;
+export declare const Container: 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>>, ProgressBarContainerStyleProps>, never>> & string;
+export declare const InnerContainer: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const MetricsContainer: 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>>, ProgressBarMetricsStyleProps>, never>> & string;
+export declare const Label: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const Percentage: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const ProgressBarTrack: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const Completed: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const PercentageIndicator: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const ExternalPercentageIndicator: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const ProgressBarFill: 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>>, ProgressBarFillStyleProps>, never>> & string;
+export declare const Link: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const ButtonLink: 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>>, ProgressBarHoverStyleProps>, never>> & string;
+export declare const StyledArrowIcon: 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").SVGProps<SVGSVGElement> & {
+    title?: string;
+}, import("react").SVGProps<SVGSVGElement> & {
+    title?: string;
+}>, ProgressBarHoverStyleProps>, never>> & string & Omit<import("react").FunctionComponent<import("react").SVGProps<SVGSVGElement> & {
+    title?: string;
+}>, keyof import("react").Component<any, {}, any>>;
+export {};

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

@@ -0,0 +1 @@
+export { default } from './ProgressBar';

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

@@ -0,0 +1,83 @@
+import React from 'react';
+import * as S from './SummaryCard.styled';
+type AssetSummaryCardOwnProps = {
+    /**
+     * Wether the SummaryCard is active or not.
+     */
+    activeSummaryCard?: boolean;
+    /**
+     * Title of the content
+     */
+    title?: string;
+    /**
+     * Description of the content
+     */
+    description?: string;
+    /**
+     * Special instructions for the content
+     */
+    instructions?: string;
+    /**
+     * Type of instructions
+     */
+    instructionSeverity?: 1 | 2 | 3 | 4 | 5;
+    /**
+     * One or more children to render in the left half of the header
+     */
+    headerLeft?: React.ReactNode;
+    /**
+     * One or more children to render in the right half of the header
+     */
+    headerRight?: React.ReactNode;
+    /**
+     * One or more children to render in the left half of the footer
+     */
+    footerLeft?: React.ReactNode;
+    /**
+     * One or more children to render in the right half of the footer
+     */
+    footerRight?: React.ReactNode;
+    /**
+     * Width of the card
+     */
+    width?: number;
+    /**
+     * Whether or not to use a border around the card
+     */
+    useBorder?: boolean;
+    /**
+     * Whether or not the Summary Card is within the CompactCard view or Grid view
+     */
+    view?: string;
+    /**
+     * Translated labels object for instruction(Info,Limited Use etc)
+     */
+    instructionLabels?: {
+        [key: string]: string;
+    };
+};
+/**
+ * ### Import
+ *
+ * ``` js
+ * import { SummaryCard } from '@ntbjs/react-components/widgets'
+ * // or
+ * import SummaryCard from '@ntbjs/react-components/widgets/SummaryCard'
+ * ```
+ *
+ * ### Props
+ * ```
+ * Pass `title="Title"` to set the title of the card.
+ * Pass `description="Description"` to set the description of the card.
+ * Pass `instructions="Instructions"` to set the instructions of the card.
+ * Pass 1-5 to `instructionSeverity` to reflect the severity of the instructions.
+ * Pass `headerLeft={<div>Left</div>}` to set the left header of the card.
+ * Pass `headerRight={<div>Right</div>}` to set the right header of the card.
+ * Pass `footerLeft={<div>Left</div>}` to set the left footer of the card.
+ * Pass `footerRight={<div>Right</div>}` to set the right footer of the card.
+ * Pass `width={300}` to set the width of the card.
+ * Pass `useBorder={true}` to set the border of the card.
+ * ```
+ */
+declare const SummaryCard: React.ForwardRefExoticComponent<Omit<Omit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<import("styled-components/dist/types").Substitute<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, S.SummaryCardStyleProps>, never>, "ref">, keyof AssetSummaryCardOwnProps> & AssetSummaryCardOwnProps & React.RefAttributes<any>>;
+export default SummaryCard;

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

@@ -0,0 +1,68 @@
+/** The card root, i.e. 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?: 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?: 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?: boolean;
+}
+/**
+ * `Gutter`, the spacer component. `SummaryCard.tsx` renders it seven times and passes
+ * `$gutter` every time.
+ */
+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?: 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?: 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;
+export declare const Gutter: 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>>, SummaryCardGutterStyleProps>, never>> & string;
+export declare const Header: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const HeaderLeft: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const HeaderRight: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const Title: 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<HTMLSpanElement>, HTMLSpanElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, never>, never>> & string;
+export declare const Description: 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<HTMLSpanElement>, HTMLSpanElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>>, never>, never>> & string;
+export declare const Instruction: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const Footer: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const FooterLeft: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const FooterRight: 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<HTMLDivElement>, HTMLDivElement>, import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>>, never>, never>> & string;
+export declare const StyledFloatingArrow: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("styled-components/dist/types").Substitute<Omit<import("@floating-ui/react").FloatingArrowProps, "ref"> & import("react").RefAttributes<SVGSVGElement>, Omit<import("@floating-ui/react").FloatingArrowProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>, never>, never>> & string & Omit<import("react").ForwardRefExoticComponent<Omit<import("@floating-ui/react").FloatingArrowProps, "ref"> & import("react").RefAttributes<SVGSVGElement>>, keyof import("react").Component<any, {}, any>>;
+export {};

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

@@ -0,0 +1 @@
+export { default } from './SummaryCard';

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

@@ -0,0 +1,11 @@
+export { default as AssetGallery } from './AssetGallery';
+export { default as ContextMenu } from './ContextMenu';
+export { default as ContextMenuItem } from './ContextMenu/ContextMenuItem';
+export { default as ContextMenuItemsGroup } from './ContextMenu/ContextMenuItemsGroup';
+export { default as AssetPreviewTopBar } from './AssetPreview/AssetPreviewTopBar';
+export { default as SummaryCard } from './SummaryCard';
+export { default as AssetActionBase } from './AssetActionsBase';
+export { default as AssetAction } from './AssetAction';
+export { default as ProgressBar } from './ProgressBar';
+export { default as InfoCard } from './InfoCard';
+export { default as InstructionSeverityDisplay } from './InstructionSeverityDisplay';

package/types/hooks/useElementSize.d.ts

@@ -0,0 +1,25 @@
+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.
+ *
+ * `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.
+ *
+ * @param ref                     element to measure
+ * @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;

package/types/hooks/useEventListner.d.ts

@@ -0,0 +1,46 @@
+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.
+ *
+ * @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`
+ */
+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

@@ -0,0 +1,242 @@
+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 {
+    /**
+     * Preferred placement, in the shared Popper/Floating UI vocabulary. `auto`,
+     * `auto-start` and `auto-end` swap `flip()` for `autoPlacement()`.
+     *
+     * @default 'bottom'
+     */
+    placement?: PopoverPlacement;
+    /**
+     * Controlled open state — our `visible` prop. `undefined` (the default) means
+     * UNCONTROLLED: the hook owns the state and the parsed `trigger` drives it. Any
+     * boolean, INCLUDING `false`, means controlled and turns the trigger Hooks off;
+     * see rule 1 in the file header.
+     */
+    open?: boolean;
+    /**
+     * Called on every open-state change, controlled or not, with Floating UI's
+     * `reason`. `reason === 'outside-press'` is what `Popover`'s `onClickOutside`
+     * prop maps onto.
+     */
+    onOpenChange?: (open: boolean, event?: Event, reason?: OpenChangeReason) => void;
+    /**
+     * tippy's `trigger` space-string, e.g. `'click focus'`, `'mouseenter'`, `''`.
+     * `undefined` means tippy's default (`'mouseenter focus'`) and `''` means no
+     * triggers at all — `parseTrigger` owns both rules and documents where `''` is
+     * used in the consumers.
+     */
+    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.
+     *
+     * @default [0, 0]
+     */
+    offset?: PopperOffset;
+    /**
+     * Whether an arrow is rendered. The hook does not render it — it only adds the
+     * `arrow()` middleware, exposes `arrowRef`, and adds `arrowHeight` to the
+     * main-axis offset.
+     *
+     * @default false
+     */
+    arrow?: boolean;
+    /**
+     * Height in px of the arrow the caller renders, i.e. how far it protrudes from
+     * the floating element. Only read when `arrow` is `true`.
+     *
+     * @default DEFAULT_ARROW_HEIGHT (15 — the popover arrow; see its derivation)
+     */
+    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.
+     *
+     * @default false
+     */
+    interactive?: boolean;
+    /**
+     * tippy's `disabled`: can never open. Forces the resolved open state to `false`
+     * and disables every interaction Hook (rule 2 in the file header).
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Transition duration in ms — our `duration` prop, fed to
+     * `useTransitionStyles`. tippy's own default is the asymmetric `[300, 250]`;
+     * both our components default it to `350`, so there is no default here and the
+     * caller states it.
+     */
+    duration?: UseTransitionStylesProps['duration'];
+    /**
+     * Overrides for the transition. `initial` defaults to a placement-aware
+     * reproduction of tippy's `animation="shift-away-subtle"`, which both
+     * components hardcode.
+     */
+    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.
+     */
+    dismiss?: Omit<UseDismissProps, 'enabled'>;
+    /** `useHover` overrides, e.g. `restMs`. `enabled` and `handleClose` are owned here. */
+    hover?: Omit<UseHoverProps, 'enabled' | 'handleClose'>;
+    /** `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"`.
+     */
+    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.
+     *
+     * @default false
+     */
+    constrainHeight?: boolean;
+    /** `padding` for the height cap. @default 10, from the modifier it replaces */
+    maxHeightPadding?: number;
+    /** `padding` for `flip()` / `shift()`. @default 5 */
+    collisionPadding?: number;
+    /**
+     * `FloatingTree` node id, for nested context-menu submenus. Passed straight to
+     * `useFloating`; unused until the `contextMenuSublevel` work (plan C5).
+     */
+    nodeId?: string;
+    /** Extra middleware, appended last. */
+    middleware?: Middleware[];
+}
+/** What `useFloatingPopover` returns. */
+export interface UseFloatingPopoverReturn {
+    /** `refs.setReference` / `refs.setFloating`, straight from `useFloating`. */
+    refs: UseFloatingReturn['refs'];
+    /** Absolute-position styles for the floating element. */
+    floatingStyles: UseFloatingReturn['floatingStyles'];
+    /** The Floating UI context — needed by `FloatingArrow`, `FloatingPortal`, `FloatingTree`. */
+    context: UseFloatingReturn['context'];
+    /** Spread onto the reference element. */
+    getReferenceProps: ReturnType<typeof useInteractions>['getReferenceProps'];
+    /** Spread onto the floating element. */
+    getFloatingProps: ReturnType<typeof useInteractions>['getFloatingProps'];
+    /** `true` while the element should be in the DOM, including during the close transition. */
+    isMounted: boolean;
+    /**
+     * The transition styles for the current phase. Named `transitionStyles` and not
+     * `styles` so a call site cannot confuse it with `floatingStyles` — the two are
+     * applied to different elements (position on the outer, transition on the
+     * inner) in all three existing implementations.
+     */
+    transitionStyles: ReturnType<typeof useTransitionStyles>['styles'];
+    /** Attach to the rendered arrow. Already wired into the `arrow()` middleware. */
+    arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+    /** The resolved open state, after `disabled` and controlled/uncontrolled resolution. */
+    isOpen: boolean;
+    /**
+     * Imperative open/close, honouring controlled mode by reporting through
+     * `onOpenChange`. This is what replaces the `_tippy.hide()` + `[data-tippy-root]`
+     * DOM sweep in `Popover.tsx`'s `handleContextMenuItemClick`.
+     */
+    setOpen: (open: boolean, event?: Event, reason?: OpenChangeReason) => void;
+    /** The placement actually used after `flip()` / `autoPlacement()` resolved it. */
+    placement: Placement;
+    /**
+     * `'none'` when `interactive` is `false`, otherwise `undefined`. tippy sets
+     * `pointer-events: none` on the popper root of a non-interactive instance; the
+     * hook reports the value rather than applying it, because which element carries
+     * it differs per call site.
+     */
+    pointerEvents: 'none' | undefined;
+}
+/**
+ * Positions and drives one floating element.
+ *
+ * @param options see `UseFloatingPopoverOptions`; every member is optional
+ */
+export declare function useFloatingPopover(options?: UseFloatingPopoverOptions): UseFloatingPopoverReturn;
+export default useFloatingPopover;

package/types/hooks/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,26 @@
+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;