From b89ea540567ceb0311c364965c46d5bf50f1c786 Mon Sep 17 00:00:00 2001
From: PerishCode <perishcode@gmail.com>
Date: Thu, 11 Jun 2026 17:13:27 +0800
Subject: [PATCH] web: polish panel layout and textarea motion

---
 .../soma/web/src/components/ChatHeader.tsx    |   2 +-
 .../soma/web/src/components/ChatShell.tsx     |  52 +++--
 .../soma/web/src/components/Composer.tsx      |  56 +++---
 .../src/atoms/TextArea/TextArea.scss          |  38 ++++
 .../src/atoms/TextArea/TextArea.tsx           |  77 ++------
 .../TextArea/hooks/useTextAreaAutosize.ts     | 177 ++++++++++++++++++
 packages/components/src/index.ts              |   1 +
 .../SectionStackLayout.scss                   |  50 +++++
 .../SectionStackLayout/SectionStackLayout.tsx |  26 +++
 packages/components/src/theme/default.scss    |   5 +
 10 files changed, 372 insertions(+), 112 deletions(-)
 create mode 100644 packages/components/src/atoms/TextArea/hooks/useTextAreaAutosize.ts
 create mode 100644 packages/components/src/patterns/SectionStackLayout/SectionStackLayout.scss
 create mode 100644 packages/components/src/patterns/SectionStackLayout/SectionStackLayout.tsx

diff --git a/apps/client/soma/web/src/components/ChatHeader.tsx b/apps/client/soma/web/src/components/ChatHeader.tsx
index 48aa81d..bdc298f 100644
--- a/apps/client/soma/web/src/components/ChatHeader.tsx
+++ b/apps/client/soma/web/src/components/ChatHeader.tsx
@@ -42,7 +42,7 @@ export function ChatHeader(props: {
   }
 
   return (
-    <Pane border="bottom" padding="lg" tone="raised">
+    <Pane padding="lg">
       <Inline justify="between" align="start" wrap gap="md">
         <Stack gap="xs">
           <Text size="xs" tone="subtle">SESSION</Text>
diff --git a/apps/client/soma/web/src/components/ChatShell.tsx b/apps/client/soma/web/src/components/ChatShell.tsx
index 991fd46..c2f5d07 100644
--- a/apps/client/soma/web/src/components/ChatShell.tsx
+++ b/apps/client/soma/web/src/components/ChatShell.tsx
@@ -1,4 +1,4 @@
-import { GridRows, Notice, Pane, Stack, Text } from "@mini-stim/components";
+import { Pane, SectionStackLayout } from "@mini-stim/components";
 
 import { ChatHeader } from "./ChatHeader";
 import { Composer } from "./Composer";
@@ -19,34 +19,28 @@ export function ChatShell(props: {
 }) {
   return (
     <Pane chrome="panel" tone="subtle" grow>
-      <GridRows grow template="header-body-footer">
-        <ChatHeader
-          busy={props.busy}
-          connection={props.connection}
-          onTitleCommit={props.onTitleCommit}
-          selectedSessionId={props.selectedSessionId}
-          title={props.title}
-          titleValue={props.titleValue}
-        />
-        <Transcript timeline={props.timeline} />
-        <Stack gap="none">
-          {props.error ? (
-            <Pane padding="md">
-              <Notice tone="danger">
-                <Text>{props.error}</Text>
-              </Notice>
-            </Pane>
-          ) : null}
-          <Pane border="top" padding="md" tone="raised">
-            <Composer
-              value={props.draft}
-              disabled={props.busy}
-              onChange={props.onDraftChange}
-              onSubmit={props.onSend}
-            />
-          </Pane>
-        </Stack>
-      </GridRows>
+      <SectionStackLayout
+        top={(
+          <ChatHeader
+            busy={props.busy}
+            connection={props.connection}
+            onTitleCommit={props.onTitleCommit}
+            selectedSessionId={props.selectedSessionId}
+            title={props.title}
+            titleValue={props.titleValue}
+          />
+        )}
+        middle={<Transcript timeline={props.timeline} />}
+        bottom={(
+          <Composer
+            value={props.draft}
+            disabled={props.busy}
+            error={props.error}
+            onChange={props.onDraftChange}
+            onSubmit={props.onSend}
+          />
+        )}
+      />
     </Pane>
   );
 }
diff --git a/apps/client/soma/web/src/components/Composer.tsx b/apps/client/soma/web/src/components/Composer.tsx
index ac93160..b720afd 100644
--- a/apps/client/soma/web/src/components/Composer.tsx
+++ b/apps/client/soma/web/src/components/Composer.tsx
@@ -1,7 +1,8 @@
-import { Button, FieldActionLayout, SendIcon, TextArea } from "@mini-stim/components";
+import { Button, Inline, Notice, SendIcon, Stack, Text, TextArea } from "@mini-stim/components";
 
 export function Composer(props: {
   disabled?: boolean;
+  error?: string | null;
   onChange: (value: string) => void;
   onSubmit: () => void;
   value: string;
@@ -13,30 +14,35 @@ export function Composer(props: {
         props.onSubmit();
       }}
     >
-      <FieldActionLayout
-        actionWidth="lg"
-        action={(
-          <Button
-            type="submit"
-            tone="accent"
-            size="lg"
-            disabled={props.disabled || !props.value.trim()}
-          >
-            <SendIcon size="sm" />
-            Send
-          </Button>
-        )}
-      >
-        <TextArea
-          autosize={{ min: 1, max: 6 }}
-          value={props.value}
-          disabled={props.disabled}
-          placeholder="Message mini-stim and press Enter"
-          resize="none"
-          variant="composer"
-          onChange={(event) => props.onChange(event.currentTarget.value)}
-        />
-      </FieldActionLayout>
+      <Stack gap="sm">
+        {props.error ? (
+          <Notice tone="danger">
+            <Text>{props.error}</Text>
+          </Notice>
+        ) : null}
+          <Inline align="stretch" gap="sm">
+            <Stack grow gap="none">
+              <TextArea
+                autosize={{ min: 1, max: 6 }}
+                value={props.value}
+                disabled={props.disabled}
+                placeholder="Message mini-stim and press Enter"
+                resize="none"
+                variant="composer"
+                onChange={(event) => props.onChange(event.currentTarget.value)}
+              />
+            </Stack>
+            <Button
+              type="submit"
+              tone="accent"
+              size="lg"
+              disabled={props.disabled || !props.value.trim()}
+            >
+              <SendIcon size="sm" />
+              Send
+            </Button>
+          </Inline>
+      </Stack>
     </form>
   );
 }
diff --git a/packages/components/src/atoms/TextArea/TextArea.scss b/packages/components/src/atoms/TextArea/TextArea.scss
index 7f3bc55..286931f 100644
--- a/packages/components/src/atoms/TextArea/TextArea.scss
+++ b/packages/components/src/atoms/TextArea/TextArea.scss
@@ -1,9 +1,42 @@
 @use "../../theme/mixins" as *;
 
+.msTextAreaFrame {
+  --ms-textarea-frame-border: var(--ms-color-input-border);
+  --ms-textarea-frame-bg: var(--ms-color-input-bg);
+  --ms-textarea-frame-radius: var(--ms-radius-lg);
+  --ms-textarea-frame-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.75);
+
+  display: flex;
+  align-items: flex-end;
+  width: 100%;
+  min-width: 0;
+  overflow: hidden;
+  border: 1px solid var(--ms-textarea-frame-border);
+  border-radius: var(--ms-textarea-frame-radius);
+  background: var(--ms-textarea-frame-bg);
+  box-shadow: var(--ms-textarea-frame-shadow);
+  transition: height 180ms ease-out;
+
+  @include focus-ring("&:focus-within");
+
+  > .msTextArea {
+    border: 0;
+    border-radius: inherit;
+    background: transparent;
+    box-shadow: none;
+
+    &:focus {
+      box-shadow: none;
+    }
+  }
+}
+
 .msTextArea {
   display: block;
   width: 100%;
   min-height: 5.25rem;
+  overscroll-behavior: contain;
+  scrollbar-gutter: stable;
   border: 1px solid var(--ms-color-input-border);
   border-radius: var(--ms-radius-lg);
   background: var(--ms-color-input-bg);
@@ -30,6 +63,11 @@
   }
 
   &--variant-composer {
+    --ms-textarea-frame-border: var(--ms-color-dock-border);
+    --ms-textarea-frame-bg: var(--ms-color-input-dock-bg);
+    --ms-textarea-frame-shadow:
+      inset 0 1px 0 rgba(255, 255, 255, 0.9),
+      0 1px 0 var(--ms-color-border-faint);
     min-height: 3.5rem;
     border-color: var(--ms-color-dock-border);
     background: var(--ms-color-input-dock-bg);
diff --git a/packages/components/src/atoms/TextArea/TextArea.tsx b/packages/components/src/atoms/TextArea/TextArea.tsx
index 15ab893..28c6705 100644
--- a/packages/components/src/atoms/TextArea/TextArea.tsx
+++ b/packages/components/src/atoms/TextArea/TextArea.tsx
@@ -1,19 +1,12 @@
-import {
-  useLayoutEffect,
-  useRef,
-  type TextareaHTMLAttributes,
-} from "react";
+import { type TextareaHTMLAttributes } from "react";
 
 import { cx } from "../../internal/cx";
+import {
+  type TextAreaAutosize,
+  useTextAreaAutosize,
+} from "./hooks/useTextAreaAutosize";
 import "./TextArea.scss";
 
-type TextAreaAutosize =
-  | boolean
-  | {
-      max: number;
-      min: number;
-    };
-
 type TextAreaProps = TextareaHTMLAttributes<HTMLTextAreaElement> & {
   autosize?: TextAreaAutosize;
   resize?: "none" | "vertical";
@@ -30,37 +23,14 @@ export function TextArea({
   value,
   ...props
 }: TextAreaProps) {
-  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
-  const autosizeConfig = resolveAutosize(autosize);
-  const resolvedRows = autosizeConfig?.min ?? rows;
-
-  useLayoutEffect(() => {
-    const element = textareaRef.current;
-    if (!element || !autosizeConfig) {
-      return;
-    }
-
-    const computed = window.getComputedStyle(element);
-    const borderBox =
-      parseFloat(computed.borderTopWidth) + parseFloat(computed.borderBottomWidth);
-    const paddingBox =
-      parseFloat(computed.paddingTop) + parseFloat(computed.paddingBottom);
-    const lineHeight = parseFloat(computed.lineHeight);
-
-    if (!Number.isFinite(lineHeight) || lineHeight <= 0) {
-      return;
-    }
-
-    const minHeight = lineHeight * autosizeConfig.min + paddingBox + borderBox;
-    const maxHeight = lineHeight * autosizeConfig.max + paddingBox + borderBox;
-
-    element.style.height = "auto";
-    const nextHeight = Math.min(Math.max(element.scrollHeight, minHeight), maxHeight);
-    element.style.height = `${nextHeight}px`;
-    element.style.overflowY = element.scrollHeight > maxHeight ? "auto" : "hidden";
-  }, [autosizeConfig, value]);
-
-  return (
+  const { autosizeConfig, frameElementRef, resolvedRows, textareaRef } =
+    useTextAreaAutosize({
+      autosize,
+      rows,
+      value,
+    });
+
+  const textarea = (
     <textarea
       {...props}
       ref={textareaRef}
@@ -76,21 +46,14 @@ export function TextArea({
       )}
     />
   );
-}
-
-function resolveAutosize(input: TextAreaAutosize) {
-  if (!input) {
-    return null;
-  }
 
-  if (input === true) {
-    return { min: 1, max: 6 };
+  if (!autosizeConfig) {
+    return textarea;
   }
 
-  const min = Number.isFinite(input.min) ? Math.max(1, Math.floor(input.min)) : 1;
-  const max = Number.isFinite(input.max)
-    ? Math.max(min, Math.floor(input.max))
-    : Math.max(min, 6);
-
-  return { min, max };
+  return (
+    <div ref={frameElementRef} className="msTextAreaFrame">
+      {textarea}
+    </div>
+  );
 }
diff --git a/packages/components/src/atoms/TextArea/hooks/useTextAreaAutosize.ts b/packages/components/src/atoms/TextArea/hooks/useTextAreaAutosize.ts
new file mode 100644
index 0000000..9af2d31
--- /dev/null
+++ b/packages/components/src/atoms/TextArea/hooks/useTextAreaAutosize.ts
@@ -0,0 +1,177 @@
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+} from "react";
+
+export type TextAreaAutosize =
+  | boolean
+  | {
+      max: number;
+      min: number;
+    };
+
+export function useTextAreaAutosize(input: {
+  autosize: TextAreaAutosize;
+  rows: number;
+  value: string | number | readonly string[] | undefined;
+}) {
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null);
+  const frameElementRef = useRef<HTMLDivElement | null>(null);
+  const frameRef = useRef<number | null>(null);
+  const scrollFrameRef = useRef<number | null>(null);
+  const motionTimeoutRef = useRef<number | null>(null);
+  const initializedRef = useRef(false);
+  const overflowActiveRef = useRef(false);
+  const autosizeConfig = resolveAutosize(input.autosize);
+  const resolvedRows = autosizeConfig?.min ?? input.rows;
+
+  useEffect(() => {
+    return () => {
+      if (frameRef.current !== null) {
+        window.cancelAnimationFrame(frameRef.current);
+      }
+      if (scrollFrameRef.current !== null) {
+        window.cancelAnimationFrame(scrollFrameRef.current);
+      }
+      if (motionTimeoutRef.current !== null) {
+        window.clearTimeout(motionTimeoutRef.current);
+      }
+    };
+  }, []);
+
+  useLayoutEffect(() => {
+    const element = textareaRef.current;
+    const frameElement = frameElementRef.current;
+    if (!element || !frameElement || !autosizeConfig) {
+      return;
+    }
+
+    const computed = window.getComputedStyle(element);
+    const borderBox =
+      parseFloat(computed.borderTopWidth) + parseFloat(computed.borderBottomWidth);
+    const paddingBox =
+      parseFloat(computed.paddingTop) + parseFloat(computed.paddingBottom);
+    const lineHeight = parseFloat(computed.lineHeight);
+
+    if (!Number.isFinite(lineHeight) || lineHeight <= 0) {
+      return;
+    }
+
+    const minHeight = lineHeight * autosizeConfig.min + paddingBox + borderBox;
+    const maxHeight = lineHeight * autosizeConfig.max + paddingBox + borderBox;
+
+    if (frameRef.current !== null) {
+      window.cancelAnimationFrame(frameRef.current);
+      frameRef.current = null;
+    }
+    if (scrollFrameRef.current !== null) {
+      window.cancelAnimationFrame(scrollFrameRef.current);
+      scrollFrameRef.current = null;
+    }
+    if (motionTimeoutRef.current !== null) {
+      window.clearTimeout(motionTimeoutRef.current);
+      motionTimeoutRef.current = null;
+    }
+
+    const previousHeight = frameElement.getBoundingClientRect().height;
+    const selectionAtEnd =
+      element.selectionStart === element.selectionEnd &&
+      element.selectionEnd === element.value.length;
+    const pinnedToBottom =
+      element.scrollTop + element.clientHeight >= element.scrollHeight - 1;
+
+    element.style.height = "auto";
+    const overflowEnabled = element.scrollHeight > maxHeight;
+    const overflowJustEnabled = overflowEnabled && !overflowActiveRef.current;
+    element.style.overflowY = overflowEnabled ? "auto" : "hidden";
+
+    const targetHeight = Math.min(
+      Math.max(element.scrollHeight + borderBox, minHeight),
+      maxHeight,
+    );
+
+    element.style.height = `${targetHeight}px`;
+    syncScrollAnchor(element, overflowEnabled, selectionAtEnd || pinnedToBottom);
+    overflowActiveRef.current = overflowEnabled;
+
+    if (!initializedRef.current) {
+      frameElement.dataset.motion = "idle";
+      frameElement.style.height = `${targetHeight}px`;
+      initializedRef.current = true;
+      return;
+    }
+
+    if (Math.abs(previousHeight - targetHeight) < 0.5) {
+      frameElement.dataset.motion = "idle";
+      frameElement.style.height = `${targetHeight}px`;
+      return;
+    }
+
+    if (targetHeight < previousHeight) {
+      frameElement.dataset.motion = "idle";
+      frameElement.style.height = `${targetHeight}px`;
+      return;
+    }
+
+    frameElement.dataset.motion = "expand";
+    frameElement.style.height = `${previousHeight}px`;
+    void frameElement.offsetHeight;
+    frameRef.current = window.requestAnimationFrame(() => {
+      frameElement.style.height = `${targetHeight}px`;
+      syncScrollAnchor(element, overflowEnabled, selectionAtEnd || pinnedToBottom);
+      if (overflowJustEnabled && (selectionAtEnd || pinnedToBottom)) {
+        scrollFrameRef.current = window.requestAnimationFrame(() => {
+          syncScrollAnchor(element, true, true);
+          scrollFrameRef.current = null;
+        });
+      }
+      motionTimeoutRef.current = window.setTimeout(() => {
+        if (frameElementRef.current === frameElement) {
+          frameElement.dataset.motion = "idle";
+        }
+        motionTimeoutRef.current = null;
+      }, 180);
+      frameRef.current = null;
+    });
+  }, [autosizeConfig, input.value]);
+
+  return {
+    autosizeConfig,
+    frameElementRef,
+    resolvedRows,
+    textareaRef,
+  };
+}
+
+function resolveAutosize(input: TextAreaAutosize) {
+  if (!input) {
+    return null;
+  }
+
+  if (input === true) {
+    return { min: 1, max: 6 };
+  }
+
+  const min = Number.isFinite(input.min) ? Math.max(1, Math.floor(input.min)) : 1;
+  const max = Number.isFinite(input.max)
+    ? Math.max(min, Math.floor(input.max))
+    : Math.max(min, 6);
+
+  return { min, max };
+}
+
+function syncScrollAnchor(
+  element: HTMLTextAreaElement,
+  overflowEnabled: boolean,
+  anchorToBottom: boolean,
+) {
+  if (!overflowEnabled) {
+    element.scrollTop = 0;
+    return;
+  }
+
+  if (anchorToBottom) {
+    element.scrollTop = Math.max(0, element.scrollHeight - element.clientHeight);
+  }
+}
diff --git a/packages/components/src/index.ts b/packages/components/src/index.ts
index 5e2c65a..243f739 100644
--- a/packages/components/src/index.ts
+++ b/packages/components/src/index.ts
@@ -3,6 +3,7 @@ export { Badge } from "./atoms/Badge/Badge";
 export { Button } from "./atoms/Button/Button";
 export { CodeBlock } from "./atoms/CodeBlock/CodeBlock";
 export { FieldActionLayout } from "./patterns/FieldActionLayout/FieldActionLayout";
+export { SectionStackLayout } from "./patterns/SectionStackLayout/SectionStackLayout";
 export { Grid, GridItem } from "./atoms/Grid/Grid";
 export { GridRows } from "./atoms/GridRows/GridRows";
 export { Heading } from "./atoms/Heading/Heading";
diff --git a/packages/components/src/patterns/SectionStackLayout/SectionStackLayout.scss b/packages/components/src/patterns/SectionStackLayout/SectionStackLayout.scss
new file mode 100644
index 0000000..bd862f5
--- /dev/null
+++ b/packages/components/src/patterns/SectionStackLayout/SectionStackLayout.scss
@@ -0,0 +1,50 @@
+.msSectionStackLayout {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  padding: var(--ms-space-3);
+
+  &__top,
+  &__middle,
+  &__bottom {
+    display: flex;
+    flex: 0 0 auto;
+    min-width: 0;
+    padding: 0;
+    width: 100%;
+  }
+
+  &__top,
+  &__bottom {
+    position: relative;
+  }
+
+  &__middle {
+    flex: 1 1 auto;
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  &__top::after {
+    content: "";
+    position: absolute;
+    left: 0;
+    right: 0;
+    height: 1px;
+    background: var(--ms-color-border-faint);
+    pointer-events: none;
+  }
+
+  &__top::after {
+    bottom: calc(var(--ms-space-3) * -0.5);
+  }
+
+  &__top > *,
+  &__middle > *,
+  &__bottom > * {
+    min-width: 0;
+    width: 100%;
+  }
+}
diff --git a/packages/components/src/patterns/SectionStackLayout/SectionStackLayout.tsx b/packages/components/src/patterns/SectionStackLayout/SectionStackLayout.tsx
new file mode 100644
index 0000000..3b3b4ba
--- /dev/null
+++ b/packages/components/src/patterns/SectionStackLayout/SectionStackLayout.tsx
@@ -0,0 +1,26 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+
+import { cx } from "../../internal/cx";
+import "./SectionStackLayout.scss";
+
+type SectionStackLayoutProps = Omit<ComponentPropsWithoutRef<"div">, "children"> & {
+  bottom: ReactNode;
+  middle: ReactNode;
+  top: ReactNode;
+};
+
+export function SectionStackLayout({
+  bottom,
+  className,
+  middle,
+  top,
+  ...props
+}: SectionStackLayoutProps) {
+  return (
+    <div {...props} className={cx("msSectionStackLayout", className)}>
+      <div className="msSectionStackLayout__top">{top}</div>
+      <div className="msSectionStackLayout__middle">{middle}</div>
+      <div className="msSectionStackLayout__bottom">{bottom}</div>
+    </div>
+  );
+}
diff --git a/packages/components/src/theme/default.scss b/packages/components/src/theme/default.scss
index d440014..765cdc0 100644
--- a/packages/components/src/theme/default.scss
+++ b/packages/components/src/theme/default.scss
@@ -38,6 +38,11 @@ body {
 }
 
 button,
+form,
 textarea {
   font: inherit;
 }
+
+form {
+  margin: 0;
+}