@diskette/use-render 0.8.0 → 0.9.0

package/README.md

@@ -136,3 +136,54 @@ These extend the element's native props, adding `render` and (for stateful hooks
 - **Ref composition** — refs from consumer, base props, and options are merged
 - **Event handler chaining** — consumer handlers run first, then base handlers
 - **className/style merging** — static values combine; functions receive state and the resolved base value as parameters
+
+## Ref Composition
+
+Component libraries often need internal ref access for focus management, measurements, or imperative APIs—while still letting consumers attach their own refs. The hooks handle this automatically.
+
+**Component author:**
+
+```tsx
+import { useRef, useImperativeHandle } from 'react'
+import { useRender, ComponentProps } from '@diskette/use-render'
+
+type State = { open: boolean }
+type ComboboxProps = ComponentProps<'input', State>
+
+export interface ComboboxRef {
+  focus: () => void
+  clear: () => void
+}
+
+function Combobox({ ref, ...props }: ComboboxProps & { ref?: React.Ref<ComboboxRef> }) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const state: State = { open: false }
+
+  // Expose imperative API to consumers
+  useImperativeHandle(ref, () => ({
+    focus: () => inputRef.current?.focus(),
+    clear: () => {
+      if (inputRef.current) inputRef.current.value = ''
+    },
+  }))
+
+  // Internal ref composes with any ref passed through props
+  return useRender('input', state, { props, ref: inputRef })
+}
+```
+
+**Consumer:**
+
+```tsx
+const inputRef = useRef<HTMLInputElement>(null)
+const comboboxRef = useRef<ComboboxRef>(null)
+
+// Direct element access
+<Combobox ref={inputRef} />
+
+// Imperative handle access
+<Combobox ref={comboboxRef} />
+comboboxRef.current?.focus()
+```
+
+The `options.ref` parameter accepts a single ref or an array of refs. All refs—from `options.ref`, `baseProps.ref`, and consumer `props.ref`—are composed into a single callback ref that updates all sources and handles cleanup.

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type Style<State> = ((state: State, baseStyle?: CSSProperties) => CSSProp
 export type ComponentRenderer<S> = (props: HTMLAttributes<any> & {
     ref?: Ref<any> | undefined;
 }, state: S) => ReactNode;
-export type DataAttributes = Record<`data-${string}`, string | number | boolean>;
+export type DataAttributes = Record<`data-${string}`, string | number | boolean | undefined>;
 export type BaseComponentProps<T extends ElementType> = Omit<ComponentPropsWithRef<T>, 'children' | 'className' | 'style'>;
 export type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
     children?: ReactNode | {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@diskette/use-render",
   "type": "module",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "exports": "./dist/index.js",
   "files": [
     "dist"
@@ -21,18 +21,18 @@
     }
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.7",
-    "@types/react": "^19.2.6",
+    "@changesets/cli": "^2.29.8",
+    "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
-    "@vitest/browser-playwright": "^4.0.13",
-    "oxlint": "^1.29.0",
-    "oxlint-tsgolint": "^0.8.1",
-    "prettier": "^3.6.2",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/browser-playwright": "^4.0.15",
+    "oxlint": "^1.32.0",
+    "oxlint-tsgolint": "^0.8.6",
+    "prettier": "^3.7.4",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.13",
+    "vitest": "^4.0.15",
     "vitest-browser-react": "^2.0.2"
   },
   "description": "_description_",