@telegraph/helpers 0.0.13 → 0.0.15

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @telegraph/helpers
 
+## 0.0.15
+
+### Patch Changes
+
+- [#653](https://github.com/knocklabs/telegraph/pull/653) [`d6c6aa9`](https://github.com/knocklabs/telegraph/commit/d6c6aa9cb0e11ba96df7d7efd479c8e4652fc029) Thanks [@dependabot](https://github.com/apps/dependabot)! - chore(deps): bump react and @types/react
+
+## 0.0.14
+
+### Patch Changes
+
+- [#650](https://github.com/knocklabs/telegraph/pull/650) [`c7ffe1d`](https://github.com/knocklabs/telegraph/commit/c7ffe1d85a0320dec6a05b1fd386ba0092c48e37) Thanks [@kylemcd](https://github.com/kylemcd)! - fix: infinite render issue with RefToTgphRef's interaction with radix's ref
+
 ## 0.0.13
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,582 @@
+# 🛠️ Helpers
+
+> TypeScript utilities, React components, and hooks for building robust Telegraph components.
+
 ![Telegraph by Knock](https://github.com/knocklabs/telegraph/assets/29106675/9b5022e3-b02c-4582-ba57-3d6171e45e44)
 
 [![npm version](https://img.shields.io/npm/v/@telegraph/helpers.svg)](https://www.npmjs.com/package/@telegraph/helpers)
+[![minzipped size](https://img.shields.io/bundlephobia/minzip/@telegraph/helpers)](https://bundlephobia.com/result?p=@telegraph/helpers)
+[![license](https://img.shields.io/npm/l/@telegraph/helpers)](https://github.com/knocklabs/telegraph/blob/main/LICENSE)
+
+## Installation
+
+```bash
+npm install @telegraph/helpers
+```
+
+> **Note**: This package contains TypeScript utilities and React helpers. No stylesheets required.
+
+## Quick Start
+
+```tsx
+import {
+  PolymorphicProps,
+  RefToTgphRef,
+  useDeterminateState,
+} from "@telegraph/helpers";
+
+// Type-safe polymorphic component
+type ButtonProps<T extends TgphElement> = PolymorphicProps<T> & {
+  variant?: "solid" | "outline";
+};
+
+// Hook for loading states with minimum duration
+const { state } = useDeterminateState({
+  value: isLoading ? "loading" : "idle",
+  determinateValue: "loading",
+  minDurationMs: 1000,
+});
+```
+
+## API Reference
+
+### Type Utilities
+
+#### `Required<T, K>`
+
+Make specific properties of a type required.
+
+```tsx
+import { Required } from "@telegraph/helpers";
+
+type User = {
+  name?: string;
+  email?: string;
+  age?: number;
+};
+
+// Make name and email required
+type UserWithRequiredFields = Required<User, "name" | "email">;
+// Result: { name: string; email: string; age?: number; }
+```
+
+#### `Optional<T, K>`
+
+Make specific properties of a type optional.
+
+```tsx
+import { Optional } from "@telegraph/helpers";
+
+type User = {
+  name: string;
+  email: string;
+  age: number;
+};
+
+// Make age optional
+type UserWithOptionalAge = Optional<User, "age">;
+// Result: { name: string; email: string; age?: number; }
+```
+
+#### `RemappedOmit<T, K>`
+
+Enhanced version of TypeScript's `Omit` that ensures complete field removal.
+
+```tsx
+import { RemappedOmit } from "@telegraph/helpers";
+
+type User = {
+  id: string;
+  name: string;
+  password: string;
+};
+
+// Remove sensitive fields
+type PublicUser = RemappedOmit<User, "password">;
+// Result: { id: string; name: string; }
+```
+
+### Polymorphic Component Types
+
+#### `TgphElement`
+
+Type alias for `React.ElementType` used throughout Telegraph.
+
+```tsx
+import { TgphElement } from "@telegraph/helpers";
+
+type ComponentProps<T extends TgphElement> = {
+  as?: T;
+  children: React.ReactNode;
+};
+```
+
+#### `TgphComponentProps<T>`
+
+Type alias for `React.ComponentProps<T>`.
+
+```tsx
+import { TgphComponentProps } from "@telegraph/helpers";
+
+type ButtonProps = TgphComponentProps<"button"> & {
+  variant?: string;
+};
+```
+
+#### `AsProp<C>`
+
+Type for the `as` prop used in polymorphic components.
+
+```tsx
+import { AsProp } from "@telegraph/helpers";
+
+type BaseProps = AsProp<React.ElementType> & {
+  children: React.ReactNode;
+};
+```
+
+#### `PolymorphicProps<E>`
+
+Complete props type for polymorphic components.
+
+```tsx
+import { PolymorphicProps, TgphElement } from "@telegraph/helpers";
+
+type BoxProps<T extends TgphElement> = PolymorphicProps<T> & {
+  padding?: string;
+  margin?: string;
+};
+
+const Box = <T extends TgphElement = "div">({
+  as,
+  padding,
+  margin,
+  ...props
+}: BoxProps<T>) => {
+  const Component = as || "div";
+  return <Component style={{ padding, margin }} {...props} />;
+};
+
+// Usage examples:
+<Box>Default div</Box>
+<Box as="section">Semantic section</Box>
+<Box as="button" onClick={() => {}}>Button element</Box>
+```
+
+#### `PolymorphicPropsWithTgphRef<E, R>`
+
+Polymorphic props with Telegraph-specific ref handling.
+
+```tsx
+import { PolymorphicPropsWithTgphRef, TgphElement } from "@telegraph/helpers";
+
+type InputProps<T extends TgphElement> = PolymorphicPropsWithTgphRef<
+  T,
+  HTMLInputElement
+> & {
+  placeholder?: string;
+};
+
+const Input = <T extends TgphElement = "input">({
+  as,
+  tgphRef,
+  ...props
+}: InputProps<T>) => {
+  const Component = as || "input";
+  return <Component ref={tgphRef} {...props} />;
+};
+```
+
+#### `PropsWithAs<C, P>`
+
+Utility for combining element props with custom props.
+
+```tsx
+import { PropsWithAs } from "@telegraph/helpers";
+
+type CustomButtonProps = PropsWithAs<
+  "button",
+  {
+    variant: "primary" | "secondary";
+    loading?: boolean;
+  }
+>;
+
+const CustomButton = ({
+  as: Component = "button",
+  variant,
+  loading,
+  ...props
+}: CustomButtonProps) => {
+  return <Component disabled={loading} data-variant={variant} {...props} />;
+};
+```
+
+## React Components
+
+### `RefToTgphRef`
+
+Component for handling ref forwarding between external libraries (like Radix) and Telegraph components.
+
+```tsx
+import * as Popover from "@radix-ui/react-popover";
+import { Button } from "@telegraph/button";
+import { RefToTgphRef } from "@telegraph/helpers";
+
+// Radix expects a `ref` prop, but Telegraph uses `tgphRef`
+<Popover.Trigger asChild>
+  <RefToTgphRef>
+    <Button>Open Popover</Button>
+  </RefToTgphRef>
+</Popover.Trigger>;
+```
+
+#### Use Cases
+
+**With Radix UI Primitives:**
+
+```tsx
+import * as Dialog from "@radix-ui/react-dialog";
+import { Button } from "@telegraph/button";
+import { RefToTgphRef } from "@telegraph/helpers";
+
+const DialogExample = () => (
+  <Dialog.Root>
+    <Dialog.Trigger asChild>
+      <RefToTgphRef>
+        <Button>Open Dialog</Button>
+      </RefToTgphRef>
+    </Dialog.Trigger>
+    <Dialog.Content>{/* Dialog content */}</Dialog.Content>
+  </Dialog.Root>
+);
+```
+
+**With Form Libraries:**
+
+```tsx
+import { RefToTgphRef } from "@telegraph/helpers";
+import { Input } from "@telegraph/input";
+import { Controller, useForm } from "react-hook-form";
+
+const FormExample = () => {
+  const { control } = useForm();
+
+  return (
+    <Controller
+      name="email"
+      control={control}
+      render={({ field }) => (
+        <RefToTgphRef>
+          <Input {...field} placeholder="Email" />
+        </RefToTgphRef>
+      )}
+    />
+  );
+};
+```
+
+## React Hooks
+
+### `useDeterminateState`
+
+Hook for managing state transitions with minimum duration guarantees.
+
+```tsx
+import { useDeterminateState } from "@telegraph/helpers";
+
+const useDeterminateState = <T>({
+  value: T;                    // Current value
+  determinateValue: T;         // Value that should persist for minimum duration
+  minDurationMs?: number;      // Minimum duration (default: 1000ms)
+}): T
+```
+
+#### Basic Usage
+
+```tsx
+import { useDeterminateState } from "@telegraph/helpers";
+import { useState } from "react";
+
+const LoadingButton = () => {
+  const [isLoading, setIsLoading] = useState(false);
+
+  // Ensure loading state persists for at least 1 second
+  const buttonState = useDeterminateState({
+    value: isLoading ? "loading" : "idle",
+    determinateValue: "loading",
+    minDurationMs: 1000,
+  });
+
+  const handleClick = async () => {
+    setIsLoading(true);
+    try {
+      await someAsyncOperation();
+    } finally {
+      setIsLoading(false); // Will transition back after minimum duration
+    }
+  };
+
+  return (
+    <button onClick={handleClick} disabled={buttonState === "loading"}>
+      {buttonState === "loading" ? "Loading..." : "Click me"}
+    </button>
+  );
+};
+```
+
+#### Advanced Usage
+
+```tsx
+import { useDeterminateState } from "@telegraph/helpers";
+
+type FormState = "idle" | "submitting" | "success" | "error";
+
+const FormWithFeedback = () => {
+  const [formState, setFormState] = useState<FormState>("idle");
+
+  // Ensure success/error states are visible for at least 2 seconds
+  const displayState = useDeterminateState({
+    value: formState,
+    determinateValue:
+      formState === "success" || formState === "error" ? formState : "idle",
+    minDurationMs: 2000,
+  });
+
+  const handleSubmit = async () => {
+    setFormState("submitting");
+    try {
+      await submitForm();
+      setFormState("success");
+      // Auto-reset after success is shown
+      setTimeout(() => setFormState("idle"), 2500);
+    } catch (error) {
+      setFormState("error");
+      setTimeout(() => setFormState("idle"), 2500);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <button disabled={displayState === "submitting"}>
+        {displayState === "submitting" && "Submitting..."}
+        {displayState === "success" && "✓ Saved!"}
+        {displayState === "error" && "✗ Error"}
+        {displayState === "idle" && "Save"}
+      </button>
+    </form>
+  );
+};
+```
+
+## Advanced Usage
+
+### Creating Polymorphic Components
+
+```tsx
+import { forwardRef } from "react";
+import { PolymorphicPropsWithTgphRef, TgphElement } from "@telegraph/helpers";
+
+type TextProps<T extends TgphElement> = PolymorphicPropsWithTgphRef<T, HTMLElement> & {
+  size?: "small" | "medium" | "large";
+  weight?: "normal" | "bold";
+  color?: string;
+};
+
+const Text = forwardRef<HTMLElement, TextProps<TgphElement>>(
+  <T extends TgphElement = "span">({
+    as,
+    size = "medium",
+    weight = "normal",
+    color,
+    tgphRef,
+    style,
+    ...props
+  }: TextProps<T>, ref) => {
+    const Component = as || "span";
+
+    return (
+      <Component
+        ref={tgphRef || ref}
+        style={{
+          fontSize: size === "small" ? "12px" : size === "large" ? "18px" : "14px",
+          fontWeight: weight === "bold" ? "bold" : "normal",
+          color,
+          ...style,
+        }}
+        {...props}
+      />
+    );
+  }
+);
+
+// Usage examples:
+<Text>Default span text</Text>
+<Text as="p" size="large" weight="bold">Paragraph text</Text>
+<Text as="h1" color="blue">Heading text</Text>
+<Text as={Link} href="/about">Link text</Text>
+```
+
+### Type-Safe Component APIs
+
+```tsx
+import { Required, Optional, TgphComponentProps } from "@telegraph/helpers";
+
+// Base props with all optional styling
+type BaseCardProps = {
+  padding?: string;
+  shadow?: boolean;
+  rounded?: boolean;
+  background?: string;
+};
+
+// Card variant that requires certain props
+type PrimaryCardProps = Required<BaseCardProps, "background"> & {
+  variant: "primary";
+};
+
+// Card variant with some optional props
+type SecondaryCardProps = Optional<BaseCardProps, "padding"> & {
+  variant: "secondary";
+};
+
+type CardProps = (PrimaryCardProps | SecondaryCardProps) & {
+  children: React.ReactNode;
+};
+
+const Card = ({ variant, children, ...props }: CardProps) => {
+  if (variant === "primary") {
+    // TypeScript knows `background` is required here
+    return <div style={{ background: props.background }} />;
+  }
+
+  // Handle secondary variant
+  return <div>{children}</div>;
+};
+
+// Usage:
+<Card variant="primary" background="white">Content</Card> // ✓ Valid
+<Card variant="primary">Content</Card> // ✗ TypeScript error - missing background
+```
+
+### Integration with External Libraries
+
+```tsx
+import * as RadixPopover from "@radix-ui/react-popover";
+import { Button } from "@telegraph/button";
+import { PolymorphicProps, RefToTgphRef } from "@telegraph/helpers";
+
+type PopoverProps = PolymorphicProps<"div"> & {
+  trigger: React.ReactNode;
+  content: React.ReactNode;
+};
+
+const Popover = ({ trigger, content, ...props }: PopoverProps) => (
+  <RadixPopover.Root>
+    <RadixPopover.Trigger asChild>
+      <RefToTgphRef>{trigger}</RefToTgphRef>
+    </RadixPopover.Trigger>
+    <RadixPopover.Content {...props}>{content}</RadixPopover.Content>
+  </RadixPopover.Root>
+);
+
+// Usage:
+<Popover
+  trigger={<Button>Open Menu</Button>}
+  content={<div>Popover content</div>}
+/>;
+```
+
+## TypeScript
+
+### Utility Type Examples
+
+```tsx
+import { Optional, RemappedOmit, Required } from "@telegraph/helpers";
+
+// API response type
+type User = {
+  id: string;
+  name: string;
+  email: string;
+  avatar?: string;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+// Create user payload (remove server-generated fields)
+type CreateUserPayload = RemappedOmit<User, "id" | "createdAt" | "updatedAt">;
+
+// Update user payload (make all fields optional except id)
+type UpdateUserPayload = Required<
+  Optional<User, "name" | "email" | "avatar">,
+  "id"
+>;
+
+// Public user (safe for client-side)
+type PublicUser = RemappedOmit<User, "email">;
+```
+
+### Component Prop Patterns
+
+```tsx
+import {
+  PolymorphicProps,
+  TgphComponentProps,
+  TgphElement,
+} from "@telegraph/helpers";
+
+// Pattern 1: Simple polymorphic component
+type SimpleProps<T extends TgphElement> = PolymorphicProps<T> & {
+  variant?: string;
+};
+
+// Pattern 2: Component with ref forwarding
+type WithRefProps<T extends TgphElement> = PolymorphicPropsWithTgphRef<
+  T,
+  HTMLElement
+> & {
+  variant?: string;
+};
+
+// Pattern 3: Extending native element props
+type NativeProps = TgphComponentProps<"button"> & {
+  loading?: boolean;
+};
+
+// Pattern 4: Conditional props based on variant
+type ConditionalProps<T extends TgphElement> = PolymorphicProps<T> &
+  (
+    | { variant: "icon"; icon: React.ComponentType; label?: never }
+    | { variant: "text"; label: string; icon?: never }
+  );
+```
+
+## Best Practices
+
+### Type Utility Guidelines
+
+1. **Use `RemappedOmit` over `Omit`**: Ensures complete field removal
+2. **Prefer `Required`/`Optional` for partial updates**: More explicit than `Partial`
+3. **Use `PolymorphicProps` for flexible components**: Enables `as` prop pattern
+4. **Always provide default `TgphElement`**: Improves TypeScript inference
+
+### Component Development
+
+1. **Use `RefToTgphRef` with external libraries**: Ensures ref compatibility
+2. **Implement `useDeterminateState` for loading states**: Improves UX with minimum durations
+3. **Type polymorphic components properly**: Use appropriate helper types
+4. **Test type constraints**: Verify TypeScript catches errors correctly
+
+## References
+
+- [TypeScript Handbook - Utility Types](https://www.typescriptlang.org/docs/handbook/utility-types.html)
+- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/)
+
+## Contributing
 
-# @telegraph/helpers
-> Internal helpers for use in telegraph
+See our [Contributing Guide](../../CONTRIBUTING.md) for more details.
 
+## License
 
+MIT License - see [LICENSE](../../LICENSE) for details.

package/dist/cjs/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("react"),p=Symbol.for("react.forward_ref"),R=(e,o)=>{const r={...o};for(const s in o){const t=e[s],n=o[s];/^on[A-Z]/.test(s)?t&&n?r[s]=(...i)=>{n(...i),t(...i)}:t&&(r[s]=t):s==="style"?r[s]={...t,...n}:s==="className"&&(r[s]=[t,n].filter(Boolean).join(" "))}return{...e,...r}},m=({children:e,...o},r)=>e?c.Children.toArray(e).map(t=>{if(c.isValidElement(t)){const n=t,l=n.$$typeof,i=n.type.$$typeof,f=n.props,u=f.tgphRef;return l===p||i===p?c.cloneElement(n,{...R(o,f),tgphRef:u||r,ref:u||r}):c.cloneElement(n,{...R(o,f),tgphRef:u||r})}return t}):null,y=c.forwardRef(({children:e,...o},r)=>m({children:e,...o},r)),T=({value:e,determinateValue:o,minDurationMs:r=1e3})=>{const[s,t]=c.useState(e),n=c.useRef(null),l=c.useRef(null),i=()=>{n.current&&(clearTimeout(n.current),n.current=null)},f=c.useCallback(()=>{if(e===o)i(),t(o),l.current=Date.now();else if(l.current!==null){const u=Date.now()-l.current,a=r-u;a>0?(i(),n.current=setTimeout(()=>{t(e),l.current=null},a)):(t(e),l.current=null)}else t(e)},[e,o,r]);return c.useEffect(()=>(f(),i),[e,f]),s};exports.RefToTgphRef=y;exports.useDeterminateState=T;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const f=require("react"),p=Symbol.for("react.forward_ref"),R=(s,l)=>{const e={...l};for(const c in l){const t=s[c],r=l[c];/^on[A-Z]/.test(c)?t&&r?e[c]=(...o)=>{r(...o),t(...o)}:t&&(e[c]=t):c==="style"?e[c]={...t,...r}:c==="className"&&(e[c]=[t,r].filter(Boolean).join(" "))}return{...s,...e}},y=({children:s,...l},e)=>s?f.Children.toArray(s).map(t=>{if(f.isValidElement(t)){const r=t,n=r.$$typeof,o=r.type.$$typeof,u=r.props,i=u.tgphRef;return n===p||o===p?f.cloneElement(r,{...R(l,u),tgphRef:i||e,ref:i||e}):f.cloneElement(r,{...R(l,u),tgphRef:i||e})}return t}):null,m=f.forwardRef(({children:s,...l},e)=>{const c=f.useRef(e),t=f.useRef(null);f.useEffect(()=>{const n=c.current,o=t.current;n!==e&&o&&(typeof n=="function"?n(null):n&&(n.current=null),typeof e=="function"?e(o):e&&(e.current=o)),c.current=e});const r=f.useCallback(n=>{t.current=n;const o=c.current;typeof o=="function"?o(n):o&&(o.current=n)},[]);return y({children:s,...l},r)}),T=({value:s,determinateValue:l,minDurationMs:e=1e3})=>{const[c,t]=f.useState(s),r=f.useRef(null),n=f.useRef(null),o=()=>{r.current&&(clearTimeout(r.current),r.current=null)},u=f.useCallback(()=>{if(s===l)o(),t(l),n.current=Date.now();else if(n.current!==null){const i=Date.now()-n.current,a=e-i;a>0?(o(),r.current=setTimeout(()=>{t(s),n.current=null},a)):(t(s),n.current=null)}else t(s)},[s,l,e]);return f.useEffect(()=>(u(),o),[s,u]),c};exports.RefToTgphRef=m;exports.useDeterminateState=T;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../src/components/RefToTgphRef/RefToTgphRef.tsx","../../src/hooks/useDeterminateState.ts"],"sourcesContent":["//\n// When interacting with components like a Radix.Trigger, they assume that\n// our components accept a `ref` prop. This is not the case with our components\n// because we use the `tgphRef` prop instead. To work around this, we can create\n// a new component that accepts a `ref` prop and forwards it to the `tgphRef`\n// prop.\n//\nimport React from \"react\";\n\nconst FORWARD_REF_SYMBOL = Symbol.for(\"react.forward_ref\");\n\ntype ApplyRefPropsProps = {\n  children: React.ReactNode;\n};\n\ntype Child = React.ReactElement & {\n  $$typeof: symbol;\n  type: { $$typeof: symbol };\n};\n\n// Merge props the same way that radix slot does\n// https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/Slot.tsx\nconst mergeProps = (\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  slotProps: Record<string, any>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  childProps: Record<string, any>,\n) => {\n  // all child props should override\n  const overrideProps = { ...childProps };\n\n  for (const propName in childProps) {\n    const slotPropValue = slotProps[propName];\n    const childPropValue = childProps[propName];\n\n    const isHandler = /^on[A-Z]/.test(propName);\n    if (isHandler) {\n      // if the handler exists on both, we compose them\n      if (slotPropValue && childPropValue) {\n        overrideProps[propName] = (...args: unknown[]) => {\n          childPropValue(...args);\n          slotPropValue(...args);\n        };\n      }\n      // but if it exists only on the slot, we use only this one\n      else if (slotPropValue) {\n        overrideProps[propName] = slotPropValue;\n      }\n    }\n    // if it's `style`, we merge them\n    else if (propName === \"style\") {\n      overrideProps[propName] = { ...slotPropValue, ...childPropValue };\n    } else if (propName === \"className\") {\n      overrideProps[propName] = [slotPropValue, childPropValue]\n        .filter(Boolean)\n        .join(\" \");\n    }\n  }\n\n  return { ...slotProps, ...overrideProps };\n};\n\nconst applyRefProps = (\n  { children, ...props }: ApplyRefPropsProps,\n  ref: React.Ref<unknown>,\n) => {\n  if (!children) return null;\n  const childrenArray = React.Children.toArray(children);\n  return childrenArray.map((child) => {\n    if (React.isValidElement(child)) {\n      const validChild = child as Child;\n      const $$typeof = validChild.$$typeof;\n      const $$typeofType = validChild.type.$$typeof;\n      const childProps = validChild.props;\n      const tgphRef = childProps.tgphRef;\n\n      // If we detect that the child is a forwardRef, we to pass the `ref` prop\n      // to it so that components that exist outside of our library can still\n      // receive the ref. We do it this way in order to avoid this warning:\n      // \"Function components cannot be given refs. Attempts to access this ref will fail.\n      // Did you mean to use React.forwardRef()\"\n      if (\n        $$typeof === FORWARD_REF_SYMBOL ||\n        $$typeofType === FORWARD_REF_SYMBOL\n      ) {\n        return React.cloneElement(validChild, {\n          ...mergeProps(props, childProps),\n          tgphRef: tgphRef || ref,\n          ref: tgphRef || ref,\n        });\n      }\n\n      // Otherwise, we can just pass the `tgphRef` prop to the child.\n      return React.cloneElement(validChild, {\n        ...mergeProps(props, childProps),\n        tgphRef: tgphRef || ref,\n      });\n    }\n\n    // If the child is not a valid element, we can just return it.\n    return child;\n  });\n};\n\n// We can't generate the type of the ref because it's a forwardRef so any\n// works for this use case\n//\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst RefToTgphRef = React.forwardRef<any, any>(\n  ({ children: childrenProp, ...props }, ref) => {\n    return applyRefProps({ children: childrenProp, ...props }, ref);\n  },\n);\n\nexport { RefToTgphRef };\n","/*\n * useDeterminateState\n *\n * A hook that returns a state transitioning to a determinate value after a minimum duration.\n * For example, you could use this hook with a button that transitions into a \"loading\" state,\n * ensuring it remains in the \"loading\" state for at least 1000ms. This provides clear feedback\n * to the user that the action is being processed.\n *\n */\nimport React from \"react\";\n\ntype UseDeterminateStateParams<T> = {\n  value: T;\n  determinateValue: T;\n  minDurationMs?: number;\n};\n\nconst useDeterminateState = <T>({\n  value,\n  determinateValue,\n  minDurationMs = 1000,\n}: UseDeterminateStateParams<T>): T => {\n  const [state, setState] = React.useState<T>(value);\n  const timeoutRef = React.useRef<NodeJS.Timeout | null>(null);\n  const startTimeRef = React.useRef<number | null>(null);\n\n  const clearExistingTimeout = () => {\n    if (timeoutRef.current) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n  };\n\n  const handleTransition = React.useCallback(() => {\n    if (value === determinateValue) {\n      clearExistingTimeout();\n      setState(determinateValue);\n      startTimeRef.current = Date.now();\n    } else if (startTimeRef.current !== null) {\n      const elapsedTime = Date.now() - startTimeRef.current;\n      const remainingTime = minDurationMs - elapsedTime;\n\n      if (remainingTime > 0) {\n        clearExistingTimeout();\n        timeoutRef.current = setTimeout(() => {\n          setState(value);\n          startTimeRef.current = null;\n        }, remainingTime);\n      } else {\n        setState(value);\n        startTimeRef.current = null;\n      }\n    } else {\n      setState(value);\n    }\n  }, [value, determinateValue, minDurationMs]);\n\n  React.useEffect(() => {\n    handleTransition();\n    return clearExistingTimeout;\n  }, [value, handleTransition]);\n\n  return state;\n};\n\nexport { useDeterminateState };\n"],"names":["FORWARD_REF_SYMBOL","mergeProps","slotProps","childProps","overrideProps","propName","slotPropValue","childPropValue","args","applyRefProps","children","props","ref","React","child","validChild","$$typeof","$$typeofType","tgphRef","RefToTgphRef","childrenProp","useDeterminateState","value","determinateValue","minDurationMs","state","setState","timeoutRef","startTimeRef","clearExistingTimeout","handleTransition","elapsedTime","remainingTime"],"mappings":"yGASMA,EAAqB,OAAO,IAAI,mBAAmB,EAanDC,EAAa,CAEjBC,EAEAC,IACG,CAEG,MAAAC,EAAgB,CAAE,GAAGD,CAAW,EAEtC,UAAWE,KAAYF,EAAY,CAC3B,MAAAG,EAAgBJ,EAAUG,CAAQ,EAClCE,EAAiBJ,EAAWE,CAAQ,EAExB,WAAW,KAAKA,CAAQ,EAGpCC,GAAiBC,EACLH,EAAAC,CAAQ,EAAI,IAAIG,IAAoB,CAChDD,EAAe,GAAGC,CAAI,EACtBF,EAAc,GAAGE,CAAI,CACvB,EAGOF,IACPF,EAAcC,CAAQ,EAAIC,GAIrBD,IAAa,QACpBD,EAAcC,CAAQ,EAAI,CAAE,GAAGC,EAAe,GAAGC,CAAe,EACvDF,IAAa,cACRD,EAAAC,CAAQ,EAAI,CAACC,EAAeC,CAAc,EACrD,OAAO,OAAO,EACd,KAAK,GAAG,EACb,CAGF,MAAO,CAAE,GAAGL,EAAW,GAAGE,CAAc,CAC1C,EAEMK,EAAgB,CACpB,CAAE,SAAAC,EAAU,GAAGC,CAAA,EACfC,IAEKF,EACiBG,EAAM,SAAS,QAAQH,CAAQ,EAChC,IAAKI,GAAU,CAC9B,GAAAD,EAAM,eAAeC,CAAK,EAAG,CAC/B,MAAMC,EAAaD,EACbE,EAAWD,EAAW,SACtBE,EAAeF,EAAW,KAAK,SAC/BZ,EAAaY,EAAW,MACxBG,EAAUf,EAAW,QAQzB,OAAAa,IAAahB,GACbiB,IAAiBjB,EAEVa,EAAM,aAAaE,EAAY,CACpC,GAAGd,EAAWU,EAAOR,CAAU,EAC/B,QAASe,GAAWN,EACpB,IAAKM,GAAWN,CAAA,CACjB,EAIIC,EAAM,aAAaE,EAAY,CACpC,GAAGd,EAAWU,EAAOR,CAAU,EAC/B,QAASe,GAAWN,CAAA,CACrB,CAAA,CAII,OAAAE,CAAA,CACR,EAnCqB,KA0ClBK,EAAeN,EAAM,WACzB,CAAC,CAAE,SAAUO,EAAc,GAAGT,CAAA,EAASC,IAC9BH,EAAc,CAAE,SAAUW,EAAc,GAAGT,GAASC,CAAG,CAElE,EC/FMS,EAAsB,CAAI,CAC9B,MAAAC,EACA,iBAAAC,EACA,cAAAC,EAAgB,GAClB,IAAuC,CACrC,KAAM,CAACC,EAAOC,CAAQ,EAAIb,EAAM,SAAYS,CAAK,EAC3CK,EAAad,EAAM,OAA8B,IAAI,EACrDe,EAAef,EAAM,OAAsB,IAAI,EAE/CgB,EAAuB,IAAM,CAC7BF,EAAW,UACb,aAAaA,EAAW,OAAO,EAC/BA,EAAW,QAAU,KAEzB,EAEMG,EAAmBjB,EAAM,YAAY,IAAM,CAC/C,GAAIS,IAAUC,EACSM,EAAA,EACrBH,EAASH,CAAgB,EACZK,EAAA,QAAU,KAAK,IAAI,UACvBA,EAAa,UAAY,KAAM,CACxC,MAAMG,EAAc,KAAK,IAAI,EAAIH,EAAa,QACxCI,EAAgBR,EAAgBO,EAElCC,EAAgB,GACGH,EAAA,EACVF,EAAA,QAAU,WAAW,IAAM,CACpCD,EAASJ,CAAK,EACdM,EAAa,QAAU,MACtBI,CAAa,IAEhBN,EAASJ,CAAK,EACdM,EAAa,QAAU,KACzB,MAEAF,EAASJ,CAAK,CAEf,EAAA,CAACA,EAAOC,EAAkBC,CAAa,CAAC,EAE3C,OAAAX,EAAM,UAAU,KACGiB,EAAA,EACVD,GACN,CAACP,EAAOQ,CAAgB,CAAC,EAErBL,CACT"}
+{"version":3,"file":"index.js","sources":["../../src/components/RefToTgphRef/RefToTgphRef.tsx","../../src/hooks/useDeterminateState.ts"],"sourcesContent":["/**\n * RefToTgphRef Component\n *\n * PURPOSE:\n * ========\n * This component bridges the gap between third-party libraries (like Radix UI) and\n * Telegraph components. Third-party libraries expect components to accept a standard\n * React `ref` prop, but Telegraph components use a custom `tgphRef` prop instead.\n *\n * Without this adapter, using Telegraph components with libraries like Radix would fail\n * because Radix would try to pass a `ref` that Telegraph components wouldn't receive.\n *\n * EXAMPLE USAGE:\n * ==============\n * ```tsx\n * <RadixTooltip.Trigger asChild>\n *   <RefToTgphRef>\n *     <Button>Hover me</Button>  // Button uses tgphRef internally\n *   </RefToTgphRef>\n * </RadixTooltip.Trigger>\n * ```\n *\n * WHAT IT DOES:\n * =============\n * 1. Receives a `ref` from the parent (e.g., Radix)\n * 2. Forwards it as both `ref` AND `tgphRef` to Telegraph children\n * 3. Merges any additional props from the parent with child props\n * 4. Handles both forwardRef components and regular components appropriately\n *\n * THE INFINITE LOOP PROBLEM:\n * ==========================\n * Radix and other libraries often pass ref callbacks that are recreated on every render\n * (new function references). When we pass these unstable refs to children via\n * React.cloneElement, it causes the child to re-render with \"new\" props even though\n * the ref functionality hasn't actually changed. This can trigger infinite render loops.\n *\n * THE SOLUTION:\n * =============\n * We create a STABLE ref callback using useCallback with an empty dependency array,\n * so the function reference never changes. We store the actual (unstable) ref in a\n * mutable ref (refStorage) and update it on every render. When our stable callback\n * is invoked, it reads from refStorage to get the latest ref and calls it.\n *\n * We also track the DOM node so that if the ref callback itself changes (rare but\n * possible), we can properly cleanup the old ref by calling it with null, and then\n * call the new ref with the current node. This matches React's standard ref behavior.\n */\nimport React from \"react\";\n\nconst FORWARD_REF_SYMBOL = Symbol.for(\"react.forward_ref\");\n\ntype ApplyRefPropsProps = {\n  children: React.ReactNode;\n};\n\ntype Child = React.ReactElement & {\n  $$typeof: symbol;\n  type: { $$typeof: symbol };\n};\n\n/**\n * mergeProps\n *\n * Merges props from the slot (parent/wrapper) with props from the child component.\n * This follows the same approach as Radix's Slot component to ensure compatibility.\n *\n * MERGE STRATEGY:\n * - Event handlers (onX): Compose them so both parent and child handlers run\n * - style: Merge objects (child styles override parent styles with same keys)\n * - className: Concatenate both class strings\n * - Other props: Child props override parent props\n *\n * @see https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/Slot.tsx\n */\nconst mergeProps = (\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  slotProps: Record<string, any>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  childProps: Record<string, any>,\n) => {\n  // all child props should override\n  const overrideProps = { ...childProps };\n\n  for (const propName in childProps) {\n    const slotPropValue = slotProps[propName];\n    const childPropValue = childProps[propName];\n\n    const isHandler = /^on[A-Z]/.test(propName);\n    if (isHandler) {\n      // if the handler exists on both, we compose them\n      if (slotPropValue && childPropValue) {\n        overrideProps[propName] = (...args: unknown[]) => {\n          childPropValue(...args);\n          slotPropValue(...args);\n        };\n      }\n      // but if it exists only on the slot, we use only this one\n      else if (slotPropValue) {\n        overrideProps[propName] = slotPropValue;\n      }\n    }\n    // if it's `style`, we merge them\n    else if (propName === \"style\") {\n      overrideProps[propName] = { ...slotPropValue, ...childPropValue };\n    } else if (propName === \"className\") {\n      overrideProps[propName] = [slotPropValue, childPropValue]\n        .filter(Boolean)\n        .join(\" \");\n    }\n  }\n\n  return { ...slotProps, ...overrideProps };\n};\n\n/**\n * applyRefProps\n *\n * Clones child elements and applies the forwarded ref and any merged props to them.\n *\n * KEY DECISIONS:\n *\n * 1. ForwardRef Detection:\n *    We check if a child is a forwardRef component by inspecting its $$typeof symbol.\n *    This is necessary because forwardRef components EXPECT a `ref` prop, while\n *    regular function components would throw a warning if given one.\n *\n * 2. Dual Ref Forwarding (forwardRef components):\n *    For forwardRef components, we pass BOTH `ref` and `tgphRef` because:\n *    - They might be third-party components that only understand `ref`\n *    - They might be Telegraph components that need `tgphRef`\n *    - Passing both ensures compatibility with all cases\n *\n * 3. Single Ref Forwarding (regular components):\n *    For non-forwardRef components, we only pass `tgphRef` to avoid React warnings\n *    about function components receiving refs.\n *\n * 4. Ref Priority:\n *    If a child already has a `tgphRef`, we use that instead of the forwarded ref.\n *    This allows child components to override ref behavior if needed.\n */\nconst applyRefProps = (\n  { children, ...props }: ApplyRefPropsProps,\n  ref: React.Ref<unknown>,\n) => {\n  if (!children) return null;\n  const childrenArray = React.Children.toArray(children);\n  return childrenArray.map((child) => {\n    if (React.isValidElement(child)) {\n      const validChild = child as Child;\n      const $$typeof = validChild.$$typeof;\n      const $$typeofType = validChild.type.$$typeof;\n      const childProps = validChild.props as Record<string, unknown>;\n      const tgphRef = childProps.tgphRef;\n\n      // CASE 1: ForwardRef Component\n      // Pass both `ref` and `tgphRef` to ensure compatibility with both\n      // Telegraph components and third-party forwardRef components.\n      if (\n        $$typeof === FORWARD_REF_SYMBOL ||\n        $$typeofType === FORWARD_REF_SYMBOL\n      ) {\n        return React.cloneElement(validChild, {\n          ...mergeProps(props, childProps as Record<string, unknown>),\n          tgphRef: tgphRef || ref,\n          ref: tgphRef || ref,\n        } as Record<string, unknown>);\n      }\n\n      // CASE 2: Regular Component\n      // Only pass `tgphRef` to avoid React warnings about function components\n      // receiving refs (which would happen if we passed `ref`).\n      return React.cloneElement(validChild, {\n        ...mergeProps(props, childProps as Record<string, unknown>),\n        tgphRef: tgphRef || ref,\n      } as Record<string, unknown>);\n    }\n\n    // CASE 3: Non-element children (strings, numbers, etc.)\n    // Return as-is since they can't receive refs or props.\n    return child;\n  });\n};\n\n/**\n * RefToTgphRef Component Implementation\n *\n * TYPE CONSTRAINTS:\n * We use `any` for the ref type because this component must accept refs of any type\n * (HTMLButtonElement, HTMLDivElement, custom component refs, etc.). Since we're\n * forwarding refs generically, there's no way to statically type this without\n * making the API cumbersome.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst RefToTgphRef = React.forwardRef<any, any>(\n  ({ children: childrenProp, ...props }, ref) => {\n    /**\n     * REF STABILIZATION ARCHITECTURE\n     *\n     * PROBLEM:\n     * Libraries like Radix create new ref callback functions on every render.\n     * If we pass these unstable refs directly to children via React.cloneElement,\n     * React sees the props object as changed (new function reference), causing\n     * unnecessary re-renders and potential infinite loops.\n     *\n     * SOLUTION OVERVIEW:\n     * Create a stable callback (stableRef) that never changes (empty deps array),\n     * but internally reads from a mutable storage to get the latest ref. This way:\n     * - Children receive the same function reference every render (no infinite loops)\n     * - The function still forwards to the latest ref (functionality preserved)\n     *\n     */\n\n    // Storage for the latest ref callback/object from parent (e.g., Radix)\n    // This gets updated on every render but doesn't cause re-renders since it's\n    // a mutable ref, not state.\n    const refStorage = React.useRef(ref);\n\n    // Storage for the current DOM node/component instance\n    // We need this to handle ref changes properly (cleanup old, set new)\n    const nodeStorage = React.useRef<unknown>(null);\n\n    /**\n     * REF CHANGE HANDLING\n     *\n     * When the parent ref changes (rare, but possible), we need to:\n     * 1. Call the OLD ref with null (cleanup - standard React behavior)\n     * 2. Call the NEW ref with the current node (re-attach)\n     *\n     * This matches React's native behavior when a ref prop changes.\n     *\n     * WHY IN useEffect:\n     * We use useEffect (not direct assignment) because we need to detect when\n     * the ref has actually changed between renders and perform cleanup/setup.\n     */\n    React.useEffect(() => {\n      const prevRef = refStorage.current;\n      const currentNode = nodeStorage.current;\n\n      // Detect ref change\n      if (prevRef !== ref && currentNode) {\n        // Step 1: Cleanup old ref (call with null)\n        if (typeof prevRef === \"function\") {\n          prevRef(null);\n        } else if (prevRef) {\n          (prevRef as React.MutableRefObject<unknown>).current = null;\n        }\n\n        // Step 2: Set new ref with current node\n        if (typeof ref === \"function\") {\n          ref(currentNode);\n        } else if (ref) {\n          (ref as React.MutableRefObject<unknown>).current = currentNode;\n        }\n      }\n\n      // Update storage with latest ref for next render\n      refStorage.current = ref;\n    });\n\n    /**\n     * STABLE REF CALLBACK\n     *\n     * This is the key to preventing infinite loops. The function reference\n     * returned by useCallback with an empty dependency array NEVER changes.\n     *\n     * When called (by React when attaching/detaching from DOM):\n     * 1. Store the node so we can handle ref changes\n     * 2. Read the LATEST ref from refStorage\n     * 3. Forward the call to that ref\n     *\n     * This indirection gives us stability (no infinite loops) while maintaining\n     * correctness (always calls the latest ref).\n     */\n    const stableRef = React.useCallback((node: unknown) => {\n      // Store node for ref change handling\n      nodeStorage.current = node;\n\n      // Get the current ref (might have been updated since last call)\n      const currentRef = refStorage.current;\n\n      // Forward to the actual ref (handle both callback refs and ref objects)\n      if (typeof currentRef === \"function\") {\n        currentRef(node);\n      } else if (currentRef) {\n        (currentRef as React.MutableRefObject<unknown>).current = node;\n      }\n    }, []); // Empty deps = stable function reference forever\n\n    // Apply the stable ref and merged props to children\n    return applyRefProps({ children: childrenProp, ...props }, stableRef);\n  },\n);\n\nexport { RefToTgphRef };\n","/*\n * useDeterminateState\n *\n * A hook that returns a state transitioning to a determinate value after a minimum duration.\n * For example, you could use this hook with a button that transitions into a \"loading\" state,\n * ensuring it remains in the \"loading\" state for at least 1000ms. This provides clear feedback\n * to the user that the action is being processed.\n *\n */\nimport React from \"react\";\n\ntype UseDeterminateStateParams<T> = {\n  value: T;\n  determinateValue: T;\n  minDurationMs?: number;\n};\n\nconst useDeterminateState = <T>({\n  value,\n  determinateValue,\n  minDurationMs = 1000,\n}: UseDeterminateStateParams<T>): T => {\n  const [state, setState] = React.useState<T>(value);\n  const timeoutRef = React.useRef<NodeJS.Timeout | null>(null);\n  const startTimeRef = React.useRef<number | null>(null);\n\n  const clearExistingTimeout = () => {\n    if (timeoutRef.current) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n  };\n\n  const handleTransition = React.useCallback(() => {\n    if (value === determinateValue) {\n      clearExistingTimeout();\n      setState(determinateValue);\n      startTimeRef.current = Date.now();\n    } else if (startTimeRef.current !== null) {\n      const elapsedTime = Date.now() - startTimeRef.current;\n      const remainingTime = minDurationMs - elapsedTime;\n\n      if (remainingTime > 0) {\n        clearExistingTimeout();\n        timeoutRef.current = setTimeout(() => {\n          setState(value);\n          startTimeRef.current = null;\n        }, remainingTime);\n      } else {\n        setState(value);\n        startTimeRef.current = null;\n      }\n    } else {\n      setState(value);\n    }\n  }, [value, determinateValue, minDurationMs]);\n\n  React.useEffect(() => {\n    handleTransition();\n    return clearExistingTimeout;\n  }, [value, handleTransition]);\n\n  return state;\n};\n\nexport { useDeterminateState };\n"],"names":["FORWARD_REF_SYMBOL","mergeProps","slotProps","childProps","overrideProps","propName","slotPropValue","childPropValue","args","applyRefProps","children","props","ref","React","child","validChild","$$typeof","$$typeofType","tgphRef","RefToTgphRef","childrenProp","refStorage","nodeStorage","prevRef","currentNode","stableRef","node","currentRef","useDeterminateState","value","determinateValue","minDurationMs","state","setState","timeoutRef","startTimeRef","clearExistingTimeout","handleTransition","elapsedTime","remainingTime"],"mappings":"yGAiDMA,EAAqB,OAAO,IAAI,mBAAmB,EAyBnDC,EAAa,CAEjBC,EAEAC,IACG,CAEH,MAAMC,EAAgB,CAAE,GAAGD,CAAA,EAE3B,UAAWE,KAAYF,EAAY,CACjC,MAAMG,EAAgBJ,EAAUG,CAAQ,EAClCE,EAAiBJ,EAAWE,CAAQ,EAExB,WAAW,KAAKA,CAAQ,EAGpCC,GAAiBC,EACnBH,EAAcC,CAAQ,EAAI,IAAIG,IAAoB,CAChDD,EAAe,GAAGC,CAAI,EACtBF,EAAc,GAAGE,CAAI,CACvB,EAGOF,IACPF,EAAcC,CAAQ,EAAIC,GAIrBD,IAAa,QACpBD,EAAcC,CAAQ,EAAI,CAAE,GAAGC,EAAe,GAAGC,CAAA,EACxCF,IAAa,cACtBD,EAAcC,CAAQ,EAAI,CAACC,EAAeC,CAAc,EACrD,OAAO,OAAO,EACd,KAAK,GAAG,EAEf,CAEA,MAAO,CAAE,GAAGL,EAAW,GAAGE,CAAA,CAC5B,EA4BMK,EAAgB,CACpB,CAAE,SAAAC,EAAU,GAAGC,CAAA,EACfC,IAEKF,EACiBG,EAAM,SAAS,QAAQH,CAAQ,EAChC,IAAKI,GAAU,CAClC,GAAID,EAAM,eAAeC,CAAK,EAAG,CAC/B,MAAMC,EAAaD,EACbE,EAAWD,EAAW,SACtBE,EAAeF,EAAW,KAAK,SAC/BZ,EAAaY,EAAW,MACxBG,EAAUf,EAAW,QAK3B,OACEa,IAAahB,GACbiB,IAAiBjB,EAEVa,EAAM,aAAaE,EAAY,CACpC,GAAGd,EAAWU,EAAOR,CAAqC,EAC1D,QAASe,GAAWN,EACpB,IAAKM,GAAWN,CAAA,CACU,EAMvBC,EAAM,aAAaE,EAAY,CACpC,GAAGd,EAAWU,EAAOR,CAAqC,EAC1D,QAASe,GAAWN,CAAA,CACM,CAC9B,CAIA,OAAOE,CACT,CAAC,EApCqB,KAiDlBK,EAAeN,EAAM,WACzB,CAAC,CAAE,SAAUO,EAAc,GAAGT,CAAA,EAASC,IAAQ,CAqB7C,MAAMS,EAAaR,EAAM,OAAOD,CAAG,EAI7BU,EAAcT,EAAM,OAAgB,IAAI,EAe9CA,EAAM,UAAU,IAAM,CACpB,MAAMU,EAAUF,EAAW,QACrBG,EAAcF,EAAY,QAG5BC,IAAYX,GAAOY,IAEjB,OAAOD,GAAY,WACrBA,EAAQ,IAAI,EACHA,IACRA,EAA4C,QAAU,MAIrD,OAAOX,GAAQ,WACjBA,EAAIY,CAAW,EACNZ,IACRA,EAAwC,QAAUY,IAKvDH,EAAW,QAAUT,CACvB,CAAC,EAgBD,MAAMa,EAAYZ,EAAM,YAAaa,GAAkB,CAErDJ,EAAY,QAAUI,EAGtB,MAAMC,EAAaN,EAAW,QAG1B,OAAOM,GAAe,WACxBA,EAAWD,CAAI,EACNC,IACRA,EAA+C,QAAUD,EAE9D,EAAG,CAAA,CAAE,EAGL,OAAOjB,EAAc,CAAE,SAAUW,EAAc,GAAGT,CAAA,EAASc,CAAS,CACtE,CACF,EClRMG,EAAsB,CAAI,CAC9B,MAAAC,EACA,iBAAAC,EACA,cAAAC,EAAgB,GAClB,IAAuC,CACrC,KAAM,CAACC,EAAOC,CAAQ,EAAIpB,EAAM,SAAYgB,CAAK,EAC3CK,EAAarB,EAAM,OAA8B,IAAI,EACrDsB,EAAetB,EAAM,OAAsB,IAAI,EAE/CuB,EAAuB,IAAM,CAC7BF,EAAW,UACb,aAAaA,EAAW,OAAO,EAC/BA,EAAW,QAAU,KAEzB,EAEMG,EAAmBxB,EAAM,YAAY,IAAM,CAC/C,GAAIgB,IAAUC,EACZM,EAAA,EACAH,EAASH,CAAgB,EACzBK,EAAa,QAAU,KAAK,IAAA,UACnBA,EAAa,UAAY,KAAM,CACxC,MAAMG,EAAc,KAAK,IAAA,EAAQH,EAAa,QACxCI,EAAgBR,EAAgBO,EAElCC,EAAgB,GAClBH,EAAA,EACAF,EAAW,QAAU,WAAW,IAAM,CACpCD,EAASJ,CAAK,EACdM,EAAa,QAAU,IACzB,EAAGI,CAAa,IAEhBN,EAASJ,CAAK,EACdM,EAAa,QAAU,KAE3B,MACEF,EAASJ,CAAK,CAElB,EAAG,CAACA,EAAOC,EAAkBC,CAAa,CAAC,EAE3C,OAAAlB,EAAM,UAAU,KACdwB,EAAA,EACOD,GACN,CAACP,EAAOQ,CAAgB,CAAC,EAErBL,CACT"}

package/dist/esm/index.mjs

@@ -1,47 +1,59 @@
-import c from "react";
-const p = Symbol.for("react.forward_ref"), m = (e, o) => {
-  const r = { ...o };
-  for (const s in o) {
-    const t = e[s], n = o[s];
-    /^on[A-Z]/.test(s) ? t && n ? r[s] = (...f) => {
-      n(...f), t(...f);
-    } : t && (r[s] = t) : s === "style" ? r[s] = { ...t, ...n } : s === "className" && (r[s] = [t, n].filter(Boolean).join(" "));
+import f from "react";
+const p = Symbol.for("react.forward_ref"), R = (s, l) => {
+  const e = { ...l };
+  for (const c in l) {
+    const t = s[c], r = l[c];
+    /^on[A-Z]/.test(c) ? t && r ? e[c] = (...o) => {
+      r(...o), t(...o);
+    } : t && (e[c] = t) : c === "style" ? e[c] = { ...t, ...r } : c === "className" && (e[c] = [t, r].filter(Boolean).join(" "));
   }
-  return { ...e, ...r };
-}, R = ({ children: e, ...o }, r) => e ? c.Children.toArray(e).map((t) => {
-  if (c.isValidElement(t)) {
-    const n = t, l = n.$$typeof, f = n.type.$$typeof, i = n.props, u = i.tgphRef;
-    return l === p || f === p ? c.cloneElement(n, {
-      ...m(o, i),
-      tgphRef: u || r,
-      ref: u || r
-    }) : c.cloneElement(n, {
-      ...m(o, i),
-      tgphRef: u || r
+  return { ...s, ...e };
+}, m = ({ children: s, ...l }, e) => s ? f.Children.toArray(s).map((t) => {
+  if (f.isValidElement(t)) {
+    const r = t, n = r.$$typeof, o = r.type.$$typeof, u = r.props, i = u.tgphRef;
+    return n === p || o === p ? f.cloneElement(r, {
+      ...R(l, u),
+      tgphRef: i || e,
+      ref: i || e
+    }) : f.cloneElement(r, {
+      ...R(l, u),
+      tgphRef: i || e
     });
   }
   return t;
-}) : null, d = c.forwardRef(
-  ({ children: e, ...o }, r) => R({ children: e, ...o }, r)
+}) : null, d = f.forwardRef(
+  ({ children: s, ...l }, e) => {
+    const c = f.useRef(e), t = f.useRef(null);
+    f.useEffect(() => {
+      const n = c.current, o = t.current;
+      n !== e && o && (typeof n == "function" ? n(null) : n && (n.current = null), typeof e == "function" ? e(o) : e && (e.current = o)), c.current = e;
+    });
+    const r = f.useCallback((n) => {
+      t.current = n;
+      const o = c.current;
+      typeof o == "function" ? o(n) : o && (o.current = n);
+    }, []);
+    return m({ children: s, ...l }, r);
+  }
 ), T = ({
-  value: e,
-  determinateValue: o,
-  minDurationMs: r = 1e3
+  value: s,
+  determinateValue: l,
+  minDurationMs: e = 1e3
 }) => {
-  const [s, t] = c.useState(e), n = c.useRef(null), l = c.useRef(null), f = () => {
-    n.current && (clearTimeout(n.current), n.current = null);
-  }, i = c.useCallback(() => {
-    if (e === o)
-      f(), t(o), l.current = Date.now();
-    else if (l.current !== null) {
-      const u = Date.now() - l.current, a = r - u;
-      a > 0 ? (f(), n.current = setTimeout(() => {
-        t(e), l.current = null;
-      }, a)) : (t(e), l.current = null);
+  const [c, t] = f.useState(s), r = f.useRef(null), n = f.useRef(null), o = () => {
+    r.current && (clearTimeout(r.current), r.current = null);
+  }, u = f.useCallback(() => {
+    if (s === l)
+      o(), t(l), n.current = Date.now();
+    else if (n.current !== null) {
+      const i = Date.now() - n.current, a = e - i;
+      a > 0 ? (o(), r.current = setTimeout(() => {
+        t(s), n.current = null;
+      }, a)) : (t(s), n.current = null);
     } else
-      t(e);
-  }, [e, o, r]);
-  return c.useEffect(() => (i(), f), [e, i]), s;
+      t(s);
+  }, [s, l, e]);
+  return f.useEffect(() => (u(), o), [s, u]), c;
 };
 export {
   d as RefToTgphRef,

package/dist/esm/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":["../../src/components/RefToTgphRef/RefToTgphRef.tsx","../../src/hooks/useDeterminateState.ts"],"sourcesContent":["//\n// When interacting with components like a Radix.Trigger, they assume that\n// our components accept a `ref` prop. This is not the case with our components\n// because we use the `tgphRef` prop instead. To work around this, we can create\n// a new component that accepts a `ref` prop and forwards it to the `tgphRef`\n// prop.\n//\nimport React from \"react\";\n\nconst FORWARD_REF_SYMBOL = Symbol.for(\"react.forward_ref\");\n\ntype ApplyRefPropsProps = {\n  children: React.ReactNode;\n};\n\ntype Child = React.ReactElement & {\n  $$typeof: symbol;\n  type: { $$typeof: symbol };\n};\n\n// Merge props the same way that radix slot does\n// https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/Slot.tsx\nconst mergeProps = (\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  slotProps: Record<string, any>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  childProps: Record<string, any>,\n) => {\n  // all child props should override\n  const overrideProps = { ...childProps };\n\n  for (const propName in childProps) {\n    const slotPropValue = slotProps[propName];\n    const childPropValue = childProps[propName];\n\n    const isHandler = /^on[A-Z]/.test(propName);\n    if (isHandler) {\n      // if the handler exists on both, we compose them\n      if (slotPropValue && childPropValue) {\n        overrideProps[propName] = (...args: unknown[]) => {\n          childPropValue(...args);\n          slotPropValue(...args);\n        };\n      }\n      // but if it exists only on the slot, we use only this one\n      else if (slotPropValue) {\n        overrideProps[propName] = slotPropValue;\n      }\n    }\n    // if it's `style`, we merge them\n    else if (propName === \"style\") {\n      overrideProps[propName] = { ...slotPropValue, ...childPropValue };\n    } else if (propName === \"className\") {\n      overrideProps[propName] = [slotPropValue, childPropValue]\n        .filter(Boolean)\n        .join(\" \");\n    }\n  }\n\n  return { ...slotProps, ...overrideProps };\n};\n\nconst applyRefProps = (\n  { children, ...props }: ApplyRefPropsProps,\n  ref: React.Ref<unknown>,\n) => {\n  if (!children) return null;\n  const childrenArray = React.Children.toArray(children);\n  return childrenArray.map((child) => {\n    if (React.isValidElement(child)) {\n      const validChild = child as Child;\n      const $$typeof = validChild.$$typeof;\n      const $$typeofType = validChild.type.$$typeof;\n      const childProps = validChild.props;\n      const tgphRef = childProps.tgphRef;\n\n      // If we detect that the child is a forwardRef, we to pass the `ref` prop\n      // to it so that components that exist outside of our library can still\n      // receive the ref. We do it this way in order to avoid this warning:\n      // \"Function components cannot be given refs. Attempts to access this ref will fail.\n      // Did you mean to use React.forwardRef()\"\n      if (\n        $$typeof === FORWARD_REF_SYMBOL ||\n        $$typeofType === FORWARD_REF_SYMBOL\n      ) {\n        return React.cloneElement(validChild, {\n          ...mergeProps(props, childProps),\n          tgphRef: tgphRef || ref,\n          ref: tgphRef || ref,\n        });\n      }\n\n      // Otherwise, we can just pass the `tgphRef` prop to the child.\n      return React.cloneElement(validChild, {\n        ...mergeProps(props, childProps),\n        tgphRef: tgphRef || ref,\n      });\n    }\n\n    // If the child is not a valid element, we can just return it.\n    return child;\n  });\n};\n\n// We can't generate the type of the ref because it's a forwardRef so any\n// works for this use case\n//\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst RefToTgphRef = React.forwardRef<any, any>(\n  ({ children: childrenProp, ...props }, ref) => {\n    return applyRefProps({ children: childrenProp, ...props }, ref);\n  },\n);\n\nexport { RefToTgphRef };\n","/*\n * useDeterminateState\n *\n * A hook that returns a state transitioning to a determinate value after a minimum duration.\n * For example, you could use this hook with a button that transitions into a \"loading\" state,\n * ensuring it remains in the \"loading\" state for at least 1000ms. This provides clear feedback\n * to the user that the action is being processed.\n *\n */\nimport React from \"react\";\n\ntype UseDeterminateStateParams<T> = {\n  value: T;\n  determinateValue: T;\n  minDurationMs?: number;\n};\n\nconst useDeterminateState = <T>({\n  value,\n  determinateValue,\n  minDurationMs = 1000,\n}: UseDeterminateStateParams<T>): T => {\n  const [state, setState] = React.useState<T>(value);\n  const timeoutRef = React.useRef<NodeJS.Timeout | null>(null);\n  const startTimeRef = React.useRef<number | null>(null);\n\n  const clearExistingTimeout = () => {\n    if (timeoutRef.current) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n  };\n\n  const handleTransition = React.useCallback(() => {\n    if (value === determinateValue) {\n      clearExistingTimeout();\n      setState(determinateValue);\n      startTimeRef.current = Date.now();\n    } else if (startTimeRef.current !== null) {\n      const elapsedTime = Date.now() - startTimeRef.current;\n      const remainingTime = minDurationMs - elapsedTime;\n\n      if (remainingTime > 0) {\n        clearExistingTimeout();\n        timeoutRef.current = setTimeout(() => {\n          setState(value);\n          startTimeRef.current = null;\n        }, remainingTime);\n      } else {\n        setState(value);\n        startTimeRef.current = null;\n      }\n    } else {\n      setState(value);\n    }\n  }, [value, determinateValue, minDurationMs]);\n\n  React.useEffect(() => {\n    handleTransition();\n    return clearExistingTimeout;\n  }, [value, handleTransition]);\n\n  return state;\n};\n\nexport { useDeterminateState };\n"],"names":["FORWARD_REF_SYMBOL","mergeProps","slotProps","childProps","overrideProps","propName","slotPropValue","childPropValue","args","applyRefProps","children","props","ref","React","child","validChild","$$typeof","$$typeofType","tgphRef","RefToTgphRef","childrenProp","useDeterminateState","value","determinateValue","minDurationMs","state","setState","timeoutRef","startTimeRef","clearExistingTimeout","handleTransition","elapsedTime","remainingTime"],"mappings":";AASA,MAAMA,IAAqB,OAAO,IAAI,mBAAmB,GAanDC,IAAa,CAEjBC,GAEAC,MACG;AAEG,QAAAC,IAAgB,EAAE,GAAGD,EAAW;AAEtC,aAAWE,KAAYF,GAAY;AAC3B,UAAAG,IAAgBJ,EAAUG,CAAQ,GAClCE,IAAiBJ,EAAWE,CAAQ;AAG1C,IADkB,WAAW,KAAKA,CAAQ,IAGpCC,KAAiBC,IACLH,EAAAC,CAAQ,IAAI,IAAIG,MAAoB;AAChD,MAAAD,EAAe,GAAGC,CAAI,GACtBF,EAAc,GAAGE,CAAI;AAAA,IACvB,IAGOF,MACPF,EAAcC,CAAQ,IAAIC,KAIrBD,MAAa,UACpBD,EAAcC,CAAQ,IAAI,EAAE,GAAGC,GAAe,GAAGC,EAAe,IACvDF,MAAa,gBACRD,EAAAC,CAAQ,IAAI,CAACC,GAAeC,CAAc,EACrD,OAAO,OAAO,EACd,KAAK,GAAG;AAAA,EACb;AAGF,SAAO,EAAE,GAAGL,GAAW,GAAGE,EAAc;AAC1C,GAEMK,IAAgB,CACpB,EAAE,UAAAC,GAAU,GAAGC,EAAA,GACfC,MAEKF,IACiBG,EAAM,SAAS,QAAQH,CAAQ,EAChC,IAAI,CAACI,MAAU;AAC9B,MAAAD,EAAM,eAAeC,CAAK,GAAG;AAC/B,UAAMC,IAAaD,GACbE,IAAWD,EAAW,UACtBE,IAAeF,EAAW,KAAK,UAC/BZ,IAAaY,EAAW,OACxBG,IAAUf,EAAW;AAQzB,WAAAa,MAAahB,KACbiB,MAAiBjB,IAEVa,EAAM,aAAaE,GAAY;AAAA,MACpC,GAAGd,EAAWU,GAAOR,CAAU;AAAA,MAC/B,SAASe,KAAWN;AAAA,MACpB,KAAKM,KAAWN;AAAA,IAAA,CACjB,IAIIC,EAAM,aAAaE,GAAY;AAAA,MACpC,GAAGd,EAAWU,GAAOR,CAAU;AAAA,MAC/B,SAASe,KAAWN;AAAA,IAAA,CACrB;AAAA,EAAA;AAII,SAAAE;AAAA,CACR,IAnCqB,MA0ClBK,IAAeN,EAAM;AAAA,EACzB,CAAC,EAAE,UAAUO,GAAc,GAAGT,EAAA,GAASC,MAC9BH,EAAc,EAAE,UAAUW,GAAc,GAAGT,KAASC,CAAG;AAElE,GC/FMS,IAAsB,CAAI;AAAA,EAC9B,OAAAC;AAAA,EACA,kBAAAC;AAAA,EACA,eAAAC,IAAgB;AAClB,MAAuC;AACrC,QAAM,CAACC,GAAOC,CAAQ,IAAIb,EAAM,SAAYS,CAAK,GAC3CK,IAAad,EAAM,OAA8B,IAAI,GACrDe,IAAef,EAAM,OAAsB,IAAI,GAE/CgB,IAAuB,MAAM;AACjC,IAAIF,EAAW,YACb,aAAaA,EAAW,OAAO,GAC/BA,EAAW,UAAU;AAAA,EAEzB,GAEMG,IAAmBjB,EAAM,YAAY,MAAM;AAC/C,QAAIS,MAAUC;AACS,MAAAM,EAAA,GACrBH,EAASH,CAAgB,GACZK,EAAA,UAAU,KAAK,IAAI;AAAA,aACvBA,EAAa,YAAY,MAAM;AACxC,YAAMG,IAAc,KAAK,IAAI,IAAIH,EAAa,SACxCI,IAAgBR,IAAgBO;AAEtC,MAAIC,IAAgB,KACGH,EAAA,GACVF,EAAA,UAAU,WAAW,MAAM;AACpC,QAAAD,EAASJ,CAAK,GACdM,EAAa,UAAU;AAAA,SACtBI,CAAa,MAEhBN,EAASJ,CAAK,GACdM,EAAa,UAAU;AAAA,IACzB;AAEA,MAAAF,EAASJ,CAAK;AAAA,EAEf,GAAA,CAACA,GAAOC,GAAkBC,CAAa,CAAC;AAE3C,SAAAX,EAAM,UAAU,OACGiB,EAAA,GACVD,IACN,CAACP,GAAOQ,CAAgB,CAAC,GAErBL;AACT;"}
+{"version":3,"file":"index.mjs","sources":["../../src/components/RefToTgphRef/RefToTgphRef.tsx","../../src/hooks/useDeterminateState.ts"],"sourcesContent":["/**\n * RefToTgphRef Component\n *\n * PURPOSE:\n * ========\n * This component bridges the gap between third-party libraries (like Radix UI) and\n * Telegraph components. Third-party libraries expect components to accept a standard\n * React `ref` prop, but Telegraph components use a custom `tgphRef` prop instead.\n *\n * Without this adapter, using Telegraph components with libraries like Radix would fail\n * because Radix would try to pass a `ref` that Telegraph components wouldn't receive.\n *\n * EXAMPLE USAGE:\n * ==============\n * ```tsx\n * <RadixTooltip.Trigger asChild>\n *   <RefToTgphRef>\n *     <Button>Hover me</Button>  // Button uses tgphRef internally\n *   </RefToTgphRef>\n * </RadixTooltip.Trigger>\n * ```\n *\n * WHAT IT DOES:\n * =============\n * 1. Receives a `ref` from the parent (e.g., Radix)\n * 2. Forwards it as both `ref` AND `tgphRef` to Telegraph children\n * 3. Merges any additional props from the parent with child props\n * 4. Handles both forwardRef components and regular components appropriately\n *\n * THE INFINITE LOOP PROBLEM:\n * ==========================\n * Radix and other libraries often pass ref callbacks that are recreated on every render\n * (new function references). When we pass these unstable refs to children via\n * React.cloneElement, it causes the child to re-render with \"new\" props even though\n * the ref functionality hasn't actually changed. This can trigger infinite render loops.\n *\n * THE SOLUTION:\n * =============\n * We create a STABLE ref callback using useCallback with an empty dependency array,\n * so the function reference never changes. We store the actual (unstable) ref in a\n * mutable ref (refStorage) and update it on every render. When our stable callback\n * is invoked, it reads from refStorage to get the latest ref and calls it.\n *\n * We also track the DOM node so that if the ref callback itself changes (rare but\n * possible), we can properly cleanup the old ref by calling it with null, and then\n * call the new ref with the current node. This matches React's standard ref behavior.\n */\nimport React from \"react\";\n\nconst FORWARD_REF_SYMBOL = Symbol.for(\"react.forward_ref\");\n\ntype ApplyRefPropsProps = {\n  children: React.ReactNode;\n};\n\ntype Child = React.ReactElement & {\n  $$typeof: symbol;\n  type: { $$typeof: symbol };\n};\n\n/**\n * mergeProps\n *\n * Merges props from the slot (parent/wrapper) with props from the child component.\n * This follows the same approach as Radix's Slot component to ensure compatibility.\n *\n * MERGE STRATEGY:\n * - Event handlers (onX): Compose them so both parent and child handlers run\n * - style: Merge objects (child styles override parent styles with same keys)\n * - className: Concatenate both class strings\n * - Other props: Child props override parent props\n *\n * @see https://github.com/radix-ui/primitives/blob/main/packages/react/slot/src/Slot.tsx\n */\nconst mergeProps = (\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  slotProps: Record<string, any>,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  childProps: Record<string, any>,\n) => {\n  // all child props should override\n  const overrideProps = { ...childProps };\n\n  for (const propName in childProps) {\n    const slotPropValue = slotProps[propName];\n    const childPropValue = childProps[propName];\n\n    const isHandler = /^on[A-Z]/.test(propName);\n    if (isHandler) {\n      // if the handler exists on both, we compose them\n      if (slotPropValue && childPropValue) {\n        overrideProps[propName] = (...args: unknown[]) => {\n          childPropValue(...args);\n          slotPropValue(...args);\n        };\n      }\n      // but if it exists only on the slot, we use only this one\n      else if (slotPropValue) {\n        overrideProps[propName] = slotPropValue;\n      }\n    }\n    // if it's `style`, we merge them\n    else if (propName === \"style\") {\n      overrideProps[propName] = { ...slotPropValue, ...childPropValue };\n    } else if (propName === \"className\") {\n      overrideProps[propName] = [slotPropValue, childPropValue]\n        .filter(Boolean)\n        .join(\" \");\n    }\n  }\n\n  return { ...slotProps, ...overrideProps };\n};\n\n/**\n * applyRefProps\n *\n * Clones child elements and applies the forwarded ref and any merged props to them.\n *\n * KEY DECISIONS:\n *\n * 1. ForwardRef Detection:\n *    We check if a child is a forwardRef component by inspecting its $$typeof symbol.\n *    This is necessary because forwardRef components EXPECT a `ref` prop, while\n *    regular function components would throw a warning if given one.\n *\n * 2. Dual Ref Forwarding (forwardRef components):\n *    For forwardRef components, we pass BOTH `ref` and `tgphRef` because:\n *    - They might be third-party components that only understand `ref`\n *    - They might be Telegraph components that need `tgphRef`\n *    - Passing both ensures compatibility with all cases\n *\n * 3. Single Ref Forwarding (regular components):\n *    For non-forwardRef components, we only pass `tgphRef` to avoid React warnings\n *    about function components receiving refs.\n *\n * 4. Ref Priority:\n *    If a child already has a `tgphRef`, we use that instead of the forwarded ref.\n *    This allows child components to override ref behavior if needed.\n */\nconst applyRefProps = (\n  { children, ...props }: ApplyRefPropsProps,\n  ref: React.Ref<unknown>,\n) => {\n  if (!children) return null;\n  const childrenArray = React.Children.toArray(children);\n  return childrenArray.map((child) => {\n    if (React.isValidElement(child)) {\n      const validChild = child as Child;\n      const $$typeof = validChild.$$typeof;\n      const $$typeofType = validChild.type.$$typeof;\n      const childProps = validChild.props as Record<string, unknown>;\n      const tgphRef = childProps.tgphRef;\n\n      // CASE 1: ForwardRef Component\n      // Pass both `ref` and `tgphRef` to ensure compatibility with both\n      // Telegraph components and third-party forwardRef components.\n      if (\n        $$typeof === FORWARD_REF_SYMBOL ||\n        $$typeofType === FORWARD_REF_SYMBOL\n      ) {\n        return React.cloneElement(validChild, {\n          ...mergeProps(props, childProps as Record<string, unknown>),\n          tgphRef: tgphRef || ref,\n          ref: tgphRef || ref,\n        } as Record<string, unknown>);\n      }\n\n      // CASE 2: Regular Component\n      // Only pass `tgphRef` to avoid React warnings about function components\n      // receiving refs (which would happen if we passed `ref`).\n      return React.cloneElement(validChild, {\n        ...mergeProps(props, childProps as Record<string, unknown>),\n        tgphRef: tgphRef || ref,\n      } as Record<string, unknown>);\n    }\n\n    // CASE 3: Non-element children (strings, numbers, etc.)\n    // Return as-is since they can't receive refs or props.\n    return child;\n  });\n};\n\n/**\n * RefToTgphRef Component Implementation\n *\n * TYPE CONSTRAINTS:\n * We use `any` for the ref type because this component must accept refs of any type\n * (HTMLButtonElement, HTMLDivElement, custom component refs, etc.). Since we're\n * forwarding refs generically, there's no way to statically type this without\n * making the API cumbersome.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nconst RefToTgphRef = React.forwardRef<any, any>(\n  ({ children: childrenProp, ...props }, ref) => {\n    /**\n     * REF STABILIZATION ARCHITECTURE\n     *\n     * PROBLEM:\n     * Libraries like Radix create new ref callback functions on every render.\n     * If we pass these unstable refs directly to children via React.cloneElement,\n     * React sees the props object as changed (new function reference), causing\n     * unnecessary re-renders and potential infinite loops.\n     *\n     * SOLUTION OVERVIEW:\n     * Create a stable callback (stableRef) that never changes (empty deps array),\n     * but internally reads from a mutable storage to get the latest ref. This way:\n     * - Children receive the same function reference every render (no infinite loops)\n     * - The function still forwards to the latest ref (functionality preserved)\n     *\n     */\n\n    // Storage for the latest ref callback/object from parent (e.g., Radix)\n    // This gets updated on every render but doesn't cause re-renders since it's\n    // a mutable ref, not state.\n    const refStorage = React.useRef(ref);\n\n    // Storage for the current DOM node/component instance\n    // We need this to handle ref changes properly (cleanup old, set new)\n    const nodeStorage = React.useRef<unknown>(null);\n\n    /**\n     * REF CHANGE HANDLING\n     *\n     * When the parent ref changes (rare, but possible), we need to:\n     * 1. Call the OLD ref with null (cleanup - standard React behavior)\n     * 2. Call the NEW ref with the current node (re-attach)\n     *\n     * This matches React's native behavior when a ref prop changes.\n     *\n     * WHY IN useEffect:\n     * We use useEffect (not direct assignment) because we need to detect when\n     * the ref has actually changed between renders and perform cleanup/setup.\n     */\n    React.useEffect(() => {\n      const prevRef = refStorage.current;\n      const currentNode = nodeStorage.current;\n\n      // Detect ref change\n      if (prevRef !== ref && currentNode) {\n        // Step 1: Cleanup old ref (call with null)\n        if (typeof prevRef === \"function\") {\n          prevRef(null);\n        } else if (prevRef) {\n          (prevRef as React.MutableRefObject<unknown>).current = null;\n        }\n\n        // Step 2: Set new ref with current node\n        if (typeof ref === \"function\") {\n          ref(currentNode);\n        } else if (ref) {\n          (ref as React.MutableRefObject<unknown>).current = currentNode;\n        }\n      }\n\n      // Update storage with latest ref for next render\n      refStorage.current = ref;\n    });\n\n    /**\n     * STABLE REF CALLBACK\n     *\n     * This is the key to preventing infinite loops. The function reference\n     * returned by useCallback with an empty dependency array NEVER changes.\n     *\n     * When called (by React when attaching/detaching from DOM):\n     * 1. Store the node so we can handle ref changes\n     * 2. Read the LATEST ref from refStorage\n     * 3. Forward the call to that ref\n     *\n     * This indirection gives us stability (no infinite loops) while maintaining\n     * correctness (always calls the latest ref).\n     */\n    const stableRef = React.useCallback((node: unknown) => {\n      // Store node for ref change handling\n      nodeStorage.current = node;\n\n      // Get the current ref (might have been updated since last call)\n      const currentRef = refStorage.current;\n\n      // Forward to the actual ref (handle both callback refs and ref objects)\n      if (typeof currentRef === \"function\") {\n        currentRef(node);\n      } else if (currentRef) {\n        (currentRef as React.MutableRefObject<unknown>).current = node;\n      }\n    }, []); // Empty deps = stable function reference forever\n\n    // Apply the stable ref and merged props to children\n    return applyRefProps({ children: childrenProp, ...props }, stableRef);\n  },\n);\n\nexport { RefToTgphRef };\n","/*\n * useDeterminateState\n *\n * A hook that returns a state transitioning to a determinate value after a minimum duration.\n * For example, you could use this hook with a button that transitions into a \"loading\" state,\n * ensuring it remains in the \"loading\" state for at least 1000ms. This provides clear feedback\n * to the user that the action is being processed.\n *\n */\nimport React from \"react\";\n\ntype UseDeterminateStateParams<T> = {\n  value: T;\n  determinateValue: T;\n  minDurationMs?: number;\n};\n\nconst useDeterminateState = <T>({\n  value,\n  determinateValue,\n  minDurationMs = 1000,\n}: UseDeterminateStateParams<T>): T => {\n  const [state, setState] = React.useState<T>(value);\n  const timeoutRef = React.useRef<NodeJS.Timeout | null>(null);\n  const startTimeRef = React.useRef<number | null>(null);\n\n  const clearExistingTimeout = () => {\n    if (timeoutRef.current) {\n      clearTimeout(timeoutRef.current);\n      timeoutRef.current = null;\n    }\n  };\n\n  const handleTransition = React.useCallback(() => {\n    if (value === determinateValue) {\n      clearExistingTimeout();\n      setState(determinateValue);\n      startTimeRef.current = Date.now();\n    } else if (startTimeRef.current !== null) {\n      const elapsedTime = Date.now() - startTimeRef.current;\n      const remainingTime = minDurationMs - elapsedTime;\n\n      if (remainingTime > 0) {\n        clearExistingTimeout();\n        timeoutRef.current = setTimeout(() => {\n          setState(value);\n          startTimeRef.current = null;\n        }, remainingTime);\n      } else {\n        setState(value);\n        startTimeRef.current = null;\n      }\n    } else {\n      setState(value);\n    }\n  }, [value, determinateValue, minDurationMs]);\n\n  React.useEffect(() => {\n    handleTransition();\n    return clearExistingTimeout;\n  }, [value, handleTransition]);\n\n  return state;\n};\n\nexport { useDeterminateState };\n"],"names":["FORWARD_REF_SYMBOL","mergeProps","slotProps","childProps","overrideProps","propName","slotPropValue","childPropValue","args","applyRefProps","children","props","ref","React","child","validChild","$$typeof","$$typeofType","tgphRef","RefToTgphRef","childrenProp","refStorage","nodeStorage","prevRef","currentNode","stableRef","node","currentRef","useDeterminateState","value","determinateValue","minDurationMs","state","setState","timeoutRef","startTimeRef","clearExistingTimeout","handleTransition","elapsedTime","remainingTime"],"mappings":"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"}

package/dist/types/components/RefToTgphRef/RefToTgphRef.d.ts

@@ -1,4 +1,13 @@
 import { default as React } from 'react';
+/**
+ * RefToTgphRef Component Implementation
+ *
+ * TYPE CONSTRAINTS:
+ * We use `any` for the ref type because this component must accept refs of any type
+ * (HTMLButtonElement, HTMLDivElement, custom component refs, etc.). Since we're
+ * forwarding refs generically, there's no way to statically type this without
+ * making the API cumbersome.
+ */
 declare const RefToTgphRef: React.ForwardRefExoticComponent<Omit<any, "ref"> & React.RefAttributes<any>>;
 export { RefToTgphRef };
 //# sourceMappingURL=RefToTgphRef.d.ts.map

package/dist/types/components/RefToTgphRef/RefToTgphRef.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefToTgphRef.d.ts","sourceRoot":"","sources":["../../../../src/components/RefToTgphRef/RefToTgphRef.tsx"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,OAAO,CAAC;AAqG1B,QAAA,MAAM,YAAY,8EAIjB,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"RefToTgphRef.d.ts","sourceRoot":"","sources":["../../../../src/components/RefToTgphRef/RefToTgphRef.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAwI1B;;;;;;;;GAQG;AAEH,QAAA,MAAM,YAAY,8EAkGjB,CAAC;AAEF,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/types/hooks/useDeterminateState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useDeterminateState.d.ts","sourceRoot":"","sources":["../../../src/hooks/useDeterminateState.ts"],"names":[],"mappings":"AAWA,KAAK,yBAAyB,CAAC,CAAC,IAAI;IAClC,KAAK,EAAE,CAAC,CAAC;IACT,gBAAgB,EAAE,CAAC,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,QAAA,MAAM,mBAAmB,GAAI,CAAC,+CAI3B,yBAAyB,CAAC,CAAC,CAAC,KAAG,CA0CjC,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"useDeterminateState.d.ts","sourceRoot":"","sources":["../../../src/hooks/useDeterminateState.ts"],"names":[],"mappings":"AAWA,KAAK,yBAAyB,CAAC,CAAC,IAAI;IAClC,KAAK,EAAE,CAAC,CAAC;IACT,gBAAgB,EAAE,CAAC,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,QAAA,MAAM,mBAAmB,GAAI,CAAC,EAAE,6CAI7B,yBAAyB,CAAC,CAAC,CAAC,KAAG,CA0CjC,CAAC;AAEF,OAAO,EAAE,mBAAmB,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telegraph/helpers",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "repository": "https://github.com/knocklabs/telegraph/tree/main/packages/helpers",
   "author": "@knocklabs",
   "license": "MIT",
@@ -29,16 +29,16 @@
     "preview": "vite preview"
   },
   "devDependencies": {
-    "@knocklabs/eslint-config": "^0.0.4",
+    "@knocklabs/eslint-config": "^0.0.5",
     "@knocklabs/typescript-config": "^0.0.2",
     "@telegraph/prettier-config": "^0.0.7",
     "@telegraph/vite-config": "^0.0.15",
-    "@types/react": "^18.3.18",
+    "@types/react": "^19.2.9",
     "eslint": "^8.56.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "typescript": "^5.7.3",
-    "vite": "^6.0.11"
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",