docs(hooks): add useMergedRefs AutoGrowTextArea example block

.changeset/use-merged-refs-example.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] A `useMergedRefs — AutoGrowTextArea` example block: an AutoGrowTextArea forwards the caller's ref and keeps its own ref to measure its height, and the merged ref attaches both to the same textarea, so it resizes itself while a parent button focuses it through the forwarded ref. Copy it with `astryx template useMergedRefsHookUsage <path>`.
+
+@Sainath-Reddy7

apps/sandbox/scripts/next-export-routes.json

@@ -794,6 +794,7 @@
     "/templates/useKeyboardHintHookUsage/",
     "/templates/useListFocusHookUsage/",
     "/templates/useLocaleHookUsage/",
+    "/templates/useMergedRefsHookUsage/",
     "/templates/useOutlineFromMarkdownHookUsage/",
     "/templates/useOverflowHookUsage/",
     "/templates/usePressFeedbackHookUsage/",

internal/shadcn-registry/routes.lock.json

@@ -3721,6 +3721,11 @@
       "path": "examples/use-locale/invoice-summary",
       "aliases": []
     },
+    {
+      "name": "example-use-merged-refs-auto-grow-text-area",
+      "path": "examples/use-merged-refs/auto-grow-text-area",
+      "aliases": []
+    },
     {
       "name": "example-use-outline-from-markdown-docs-article",
       "path": "examples/use-outline-from-markdown/docs-article",

packages/cli/assets/templates/blocks/components/Hooks/useMergedRefsHookUsage.doc.mjs

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+  type: 'block',
+  exampleFor: 'useMergedRefs',
+  name: 'useMergedRefs — AutoGrowTextArea',
+  displayName: 'useMergedRefs — AutoGrowTextArea',
+  description:
+    "An AutoGrowTextArea that forwards the caller's ref and also keeps its own ref to measure scrollHeight. The merged ref attaches both to the same textarea: it resizes itself while a parent button focuses it through the forwarded ref.",
+  isReady: true,
+  aspectRatio: 4 / 3,
+  componentsUsed: ['Card', 'Button', 'Layout'],
+};

packages/cli/assets/templates/blocks/components/Hooks/useMergedRefsHookUsage.tsx

@@ -0,0 +1,78 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {forwardRef, useEffect, useRef, useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {useMergedRefs} from '@astryxdesign/core/hooks';
+import {VStack} from '@astryxdesign/core/Layout';
+
+type AutoGrowTextAreaProps = {
+  value: string;
+  onChange: (value: string) => void;
+};
+
+// Forwards the caller's ref and also keeps its own ref to measure
+// scrollHeight; useMergedRefs attaches both to the same textarea.
+const AutoGrowTextArea = forwardRef<HTMLTextAreaElement, AutoGrowTextAreaProps>(
+  function AutoGrowTextArea({value, onChange}, forwardedRef) {
+    const keptRef = useRef<HTMLTextAreaElement>(null);
+    const mergedRef = useMergedRefs(forwardedRef, keptRef);
+
+    // Syncs the textarea's inline height with the committed value.
+    // scrollHeight is right only after React writes the new text.
+    useEffect(() => {
+      const el = keptRef.current;
+      if (!el) {
+        return;
+      }
+      el.style.height = 'auto';
+      el.style.height = `${el.scrollHeight}px`;
+    }, [value]);
+
+    return (
+      <textarea
+        ref={mergedRef}
+        value={value}
+        onChange={event => onChange(event.target.value)}
+        rows={1}
+        aria-label="Auto-growing message"
+        placeholder="Type — the box grows itself"
+        style={{
+          width: '100%',
+          padding: 8,
+          borderRadius: 8,
+          border: '1px solid',
+          resize: 'none',
+          overflow: 'hidden',
+          fontFamily: 'inherit',
+          fontSize: 14,
+          lineHeight: '20px',
+          color: 'inherit',
+          background: 'transparent',
+        }}
+      />
+    );
+  },
+);
+
+export default function UseMergedRefsHookUsage() {
+  const areaRef = useRef<HTMLTextAreaElement>(null);
+  const [value, setValue] = useState(
+    'This box keeps its own ref to measure and grow. The button focuses it through the forwarded ref.',
+  );
+
+  return (
+    <Card width={360} padding={4}>
+      <VStack gap={3}>
+        <AutoGrowTextArea ref={areaRef} value={value} onChange={setValue} />
+        <Button
+          label="Focus via forwarded ref"
+          size="sm"
+          onClick={() => areaRef.current?.focus()}
+        />
+      </VStack>
+    </Card>
+  );
+}