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

package/types/utils/parseTrigger.d.ts

@@ -1,31 +1,3 @@
-/**
- * tippy's `trigger` space-string, parsed into the three discrete Floating UI
- * interaction hooks.
- *
- * WHY THIS EXISTS AS A SEPARATE, PURE FUNCTION. tippy takes ONE prop —
- * `trigger="mouseenter focus"` — and does its own tokenising
- * (`splitBySpaces(instance.props.trigger).forEach(...)` in
- * `tippy.js/dist/tippy.cjs.js`). Floating UI has no equivalent: it has three
- * separate Hooks (`useClick`, `useHover`, `useFocus`), each with its own
- * `enabled` flag. `Popover` and `Tooltip` both publish `trigger` as a documented
- * prop and 62 consumer call sites pass it, so the string has to survive — which
- * means exactly one place has to own the string → flags translation. This is it,
- * and it is a pure function so it can be reasoned about (and later tested)
- * without mounting anything.
- *
- * It lives in `src/utils/` rather than `src/hooks/` deliberately: it calls no
- * Hook, has no React import, and `useFloatingPopover` is not its only plausible
- * caller — a `<Popover>` that needs to know "does this trigger imply hover?" for
- * a styling decision can ask without pulling in a Hook.
- */
-/**
- * Which Floating UI interaction Hooks a tippy trigger string turns on.
- *
- * All three are REQUIRED and always present. This is a computed result, not a
- * bag of options: "the caller did not mention hover" and "hover is off" are the
- * same statement here, and an optional member would let a caller write
- * `if (parsed.hover === undefined)` as though there were a third state.
- */
 export interface ParsedTrigger {
     /** `click` token present → `useClick`. */
     click: boolean;
@@ -34,59 +6,17 @@ export interface ParsedTrigger {
     /** `focus` or `focusin` token present → `useFocus`. */
     focus: boolean;
 }
-/**
- * tippy's own default, measured — `tippy.js/dist/tippy.cjs.js`:
- *
- * ```js
- * var defaultProps = Object.assign({
- *   …
- *   trigger: 'mouseenter focus',
- *   …
- * }, pluginProps, renderProps);
- * ```
- *
- * `Tooltip.tsx` declares no default for `trigger` and passes `undefined`
- * straight through, so `undefined` HAS ALWAYS MEANT `'mouseenter focus'` for
- * every tooltip in the library and in both consumers. `parseTrigger(undefined)`
- * therefore has to return hover+focus, not nothing — see the `trigger`
- * parameter's note.
- *
- * (`Popover.tsx` declares its own default, `'click focus'`, so it never relies
- * on this one.)
- */
 export declare const TIPPY_DEFAULT_TRIGGER = "mouseenter focus";
 /**
- * Parses a tippy `trigger` prop into `{ click, hover, focus }`.
- *
- * THE THREE INPUTS THAT ARE EASY TO GET WRONG, all of them in use:
- *
- * - **`undefined`** (and `null`) means "tippy's default", i.e. hover+focus. It
- *   does NOT mean "no triggers". Every `<Tooltip>` in the library that does not
- *   pass `trigger` relies on this.
- * - **`''`** means NO TRIGGERS AT ALL, and it is used. Measured, in BOTH
- *   consumers — `mb-main-client/src/components/assets/sales_overlay.tsx:246` and
- *   `ntb-dam/client/src/components/assets/sales_overlay.js:245`:
- *
- *   ```jsx
- *   trigger={assetsHasAllRequiredData ? "" : "mouseenter focus"}
- *   ```
- *
- *   i.e. `''` is how that call site turns the tooltip OFF conditionally. Return
- *   anything truthy for it and a tooltip appears where the consumer suppressed
- *   one. `''.split(/\s+/)` is `['']`, which is why the `filter(Boolean)`
- *   below is load-bearing rather than tidiness — without it `''` would be
- *   treated as an unrecognised token, which happens to give the same answer here
- *   but would stop doing so the moment a token were matched loosely.
- * - **A controlled popover ignores the result entirely.** That decision is NOT
- *   made here: this function reports what the string says, and
- *   `useFloatingPopover` is what gates the Hooks off when `visible` is a
- *   boolean. Keeping the two apart means the parse stays testable and the
- *   controlled-mode rule lives in one place instead of two.
+ * Parses a tippy trigger string into Floating UI Hook flags.
  *
- * Whitespace is split on `/\s+/` and not `' '`, matching tippy's
- * `splitBySpaces`, so `'click\n  focus'` parses the same way tippy parses it.
+ * Three inputs are easy to get wrong: `undefined`/`null` → tippy default (hover+focus,
+ * NOT "no triggers"); `''` → no triggers (used in sales overlays to conditionally
+ * suppress tooltips); filter(Boolean) is load-bearing (empty string splits to ['']
+ * which would otherwise be treated as an unrecognised token). Controlled mode is
+ * NOT handled here — useFloatingPopover gates the Hooks based on visible.
  *
- * @param trigger tippy's `trigger` prop. `undefined`/`null` → the tippy default
- *                (`'mouseenter focus'`); `''` → nothing enabled
+ * @param trigger tippy's trigger prop; `undefined`/`null` → 'mouseenter focus';
+ *                `''` → all flags false
  */
 export declare function parseTrigger(trigger?: string | null): ParsedTrigger;