@tcn/ui 0.16.0 → 0.18.0

package/src/themes/themes/ergo/parts/navigation.css

@@ -0,0 +1,104 @@
+@layer tcn-theme {
+  /* ===== Tabs ===== */
+  .tcn-tabs-bar {
+    .tcn-tabs-list {
+      .tcn-tab-item {
+        min-height: 24px;
+        padding: 0px var(--padding-medium);
+        text-decoration: none;
+        text-overflow: ellipsis;
+        overflow: hidden;
+        white-space: nowrap;
+      }
+    }
+  }
+
+  /* Default */
+  .tcn-tabs-bar[data-variant="default"] {
+    .tcn-tabs-list {
+      .tcn-tab-item {
+        box-sizing: border-box;
+        border: none;
+        padding: 0px var(--padding-medium);
+        border-radius: 0;
+      }
+      .tcn-tab-item[data-is-selected="true"] {
+        --mat: var(--tcn-button-color, var(--material));
+        --ink: var(--tcn-button-text-color, var(--ergo-primary));
+        --act: var(--ergo-primary);
+      }
+
+      .tcn-tab-item:focus-visible {
+        z-index: 2;
+      }
+      /* Hover Indicator */
+      .tcn-tab-item[data-is-selected="false"]:hover::after,
+      .tcn-tab-item[data-is-selected="false"]:focus-visible::after {
+        content: "";
+        display: block;
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: 0px;
+        height: 1px;
+        background: var(--ergo-accent-blue);
+        pointer-events: none;
+        width: 100%;
+        z-index: 3;
+      }
+
+      /* Indicator */
+      &::after {
+        content: "";
+        position: absolute;
+        bottom: -1px;
+        left: 0;
+        min-height: 2px;
+        transform: translateX(var(--tabs-active-rectangle-position-x, 0));
+        width: var(--tabs-active-rectangle-width, 0);
+        background: var(--ergo-primary);
+        pointer-events: none;
+        border-bottom-left-radius: 2px;
+        border-bottom-right-radius: 2px;
+        transition:
+          transform 300ms ease-in-out,
+          width 300ms ease-in-out;
+        will-change: transform, width;
+        z-index: 2;
+      }
+    }
+
+    /* Rail */
+    &::before {
+      content: "";
+      position: absolute;
+      bottom: 0px;
+      left: 0;
+      width: 100%;
+      height: 1px;
+      background: var(--ergo-material-divider);
+      pointer-events: none;
+      z-index: 1;
+    }
+  }
+
+  /* Inline  */
+  .tcn-tabs-bar[data-variant="inline"] {
+    font-size: 12px;
+    min-width: min-content;
+    width: auto;
+    flex-grow: 0;
+    border-radius: 6px;
+    border: 1px solid var(--on-material);
+    padding: 2px;
+
+    .tcn-tabs-list {
+      height: 20px;
+      gap: var(--ergo-spacing-xs);
+      .tcn-tab-item {
+        border-radius: var(--ergo-shape-radius-medium);
+        min-height: 20px;
+      }
+    }
+  }
+}

package/src/themes/themes/windows_98/windows_98.css

@@ -112,6 +112,37 @@
     outline: none;
   }
 
+  /* Utility button styles — selectors mirror hierarchy/hover combos above to win specificity */
+  .tcn-button[data-is-utility="true"],
+  .tcn-button[data-is-utility="true"][data-hierarchy="primary"],
+  .tcn-button[data-is-utility="true"][data-hierarchy="secondary"],
+  .tcn-button[data-is-utility="true"][data-hierarchy="primary"]:hover,
+  .tcn-button[data-is-utility="true"][data-hierarchy="secondary"]:hover {
+    padding: 2px;
+    min-width: 0;
+    min-height: 0;
+    height: auto;
+    width: auto;
+  }
+
+  .tcn-button[data-is-utility="true"][data-size="sm"],
+  .tcn-button[data-is-utility="true"][data-hierarchy="primary"][data-size="sm"]:hover,
+  .tcn-button[data-is-utility="true"][data-hierarchy="secondary"][data-size="sm"]:hover {
+    padding: 1px;
+  }
+
+  .tcn-button[data-is-utility="true"][data-size="md"],
+  .tcn-button[data-is-utility="true"][data-hierarchy="primary"][data-size="md"]:hover,
+  .tcn-button[data-is-utility="true"][data-hierarchy="secondary"][data-size="md"]:hover {
+    padding: 2px;
+  }
+
+  .tcn-button[data-is-utility="true"][data-size="lg"],
+  .tcn-button[data-is-utility="true"][data-hierarchy="primary"][data-size="lg"]:hover,
+  .tcn-button[data-is-utility="true"][data-hierarchy="secondary"][data-size="lg"]:hover {
+    padding: 4px;
+  }
+
   .tcn-button[data-is-disabled="true"] {
     text-shadow: 1px 1px 0 #fff;
   }
@@ -289,43 +320,6 @@
     pointer-events: none;
   }
 
-  /* Slim button styles */
-  .tcn-slim-button,
-  .tcn-slim-button[data-hierarchy="primary"],
-  .tcn-slim-button[data-hierarchy="secondary"],
-  .tcn-slim-button[data-hierarchy="primary"]:hover,
-  .tcn-slim-button[data-hierarchy="secondary"]:hover {
-    padding: 2px;
-    min-width: 0;
-    min-height: 0;
-    height: auto;
-    width: auto;
-  }
-
-  .tcn-slim-button[data-size="sm"],
-  .tcn-slim-button[data-hierarchy="primary"][data-size="sm"],
-  .tcn-slim-button[data-hierarchy="secondary"][data-size="sm"],
-  .tcn-slim-button[data-hierarchy="primary"][data-size="sm"]:hover,
-  .tcn-slim-button[data-hierarchy="secondary"][data-size="sm"]:hover {
-    padding: 1px;
-  }
-
-  .tcn-slim-button[data-size="md"],
-  .tcn-slim-button[data-hierarchy="primary"][data-size="md"],
-  .tcn-slim-button[data-hierarchy="secondary"][data-size="md"],
-  .tcn-slim-button[data-hierarchy="primary"][data-size="md"]:hover,
-  .tcn-slim-button[data-hierarchy="secondary"][data-size="md"]:hover {
-    padding: 2px;
-  }
-
-  .tcn-slim-button[data-size="lg"],
-  .tcn-slim-button[data-hierarchy="primary"][data-size="lg"],
-  .tcn-slim-button[data-hierarchy="secondary"][data-size="lg"],
-  .tcn-slim-button[data-hierarchy="primary"][data-size="lg"]:hover,
-  .tcn-slim-button[data-hierarchy="secondary"][data-size="lg"]:hover {
-    padding: 4px;
-  }
-
   /* Select group styles */
   .tcn-select-group .tcn-button[data-hierarchy="primary"],
   .tcn-select-group .tcn-button[data-hierarchy="primary"]:hover,
@@ -682,6 +676,7 @@
     margin-top: 10px;
     border-radius: 0;
     background: #c0c0c0;
+    gap: 8px;
     box-shadow:
       inset 1px 1px #808080,
       inset -1px -1px #f5f5f5,
@@ -689,12 +684,6 @@
       inset -2px -2px #808080;
   }
 
-  .tcn-field-set > .tcn-field-set-body {
-    background: transparent;
-    padding: 0;
-    gap: 8px;
-  }
-
   .tcn-field-set > .tcn-field-set-legend {
     position: relative;
     top: -7px;

package/src/tokens/chip/chip.stories.tsx

@@ -1,7 +1,7 @@
 import { HStack } from '../../stacks/h_stack.js';
 import { Spacer } from '../../stacks/spacer.js';
 import React from 'react';
-import { SlimButton } from '../../actions/index.js';
+import { Button } from '../../actions/index.js';
 import { Chip } from './chip.js';
 import { BodyText } from '../../typography/index.js';
 import { CrossIcon } from '@tcn/icons/cross_icon.js';
@@ -21,9 +21,9 @@ export const WithIcon = () => (
     <HStack>
       <BodyText padStart="8px">Hola Mundo</BodyText>
       <Spacer width="8px" />
-      <SlimButton size="sm" hierarchy="tertiary">
+      <Button utility size="sm" hierarchy="tertiary">
         <CrossIcon size="sm" />
-      </SlimButton>
+      </Button>
     </HStack>
   </Chip>
 );
@@ -40,9 +40,9 @@ export const AllVariations = () => (
   //         <HStack>
   //           <BodyText padStart="8px">Hola Mundo</BodyText>
   //           <Spacer width="8px" />
-  //           <SlimButton size="sm" hierarchy="tertiary">
+  //           <Button utility size="sm" hierarchy="tertiary">
   //             <CrossIcon size="sm" />
-  //           </SlimButton>
+  //           </Button>
   //         </HStack>
   //       </Chip>
   //     }

package/src/utils/decorators/DECORATOR_PATTERN.md

@@ -0,0 +1,86 @@
+# Decorator Pattern
+
+Decorators are components that wrap exactly one child element via `React.cloneElement`, inject behavior (props, refs, classNames, CSS variables), and provide a context for sub-components (handles, controls).
+
+## What Makes a Decorator
+
+- Wraps a single child element using `cloneElement`
+- Injects props onto the child without the child's knowledge
+- Can provide a React context consumed by sub-components (e.g. `ResizeHandle` reads `ResizableContext`)
+- Is composable by stacking: `<Draggable><Resizable><div /></Resizable></Draggable>`
+
+Decorators are distinct from **listeners** (which monitor external events like clicks-outside or scrolls without using `cloneElement`).
+
+## cloneElement Rules
+
+When cloning the child element:
+
+1. **Merge `className`** via `clsx` -- never replace the child's existing classes
+2. **Fork `ref`** via `useForkRef` -- preserve both the decorator's internal ref and the consumer's forwarded ref
+3. **Spread `style`** -- merge into the child's existing style, never replace
+4. **Use `tcn-*` CSS class** -- add a `tcn-<decorator-name>` class for external styling hooks
+5. **Use `data-*` attributes** for state (`data-is-dragging`, `data-is-resizable`, etc.)
+
+The shared utility `clone_with_decorator.ts` consolidates this boilerplate.
+
+## Context Pattern
+
+Each decorator provides its own context:
+
+```tsx
+// context.ts
+export const ResizableContext = createContext<ResizableContextValue | undefined>(undefined);
+export const useResizable = makeContextHook(ResizableContext, 'ResizableContext');
+```
+
+Sub-components (handles, controls) consume this context to coordinate with their parent decorator.
+
+## displayName Discrimination
+
+When a decorator needs to separate its own sub-components from other children, use `displayName` matching:
+
+```tsx
+function isResizeHandle(child: React.ReactNode): boolean {
+  return (type as { displayName?: string }).displayName === 'ResizeHandle';
+}
+```
+
+Always set `displayName` on sub-components. Note: wrapping a sub-component in a HOC can break `displayName` matching -- keep sub-components as direct exports.
+
+## Stacking Decorators
+
+Decorators compose cleanly by stacking:
+
+```tsx
+<Draggable>
+  <Resizable>
+    <div>content</div>
+  </Resizable>
+</Draggable>
+```
+
+This works because:
+- Each decorator forks the ref chain independently via `useForkRef`
+- Props are merged (className via clsx, style via spread), not replaced
+- Each decorator provides its own isolated context
+
+No optimization for single-`cloneElement` composition is needed -- `cloneElement` is synchronous and cheap.
+
+## Creating a New Decorator
+
+Checklist:
+
+1. Create a directory under `utils/decorators/<name>/`
+2. Use `cloneWithDecorator()` from `clone_with_decorator.ts` for the cloneElement boilerplate
+3. (Optional) Create a context + `makeContextHook` for sub-component communication
+4. Set `displayName` on all sub-components
+5. Add `tcn-<name>` CSS class on the target element
+6. Add `data-*` attributes for observable state
+7. Write stories for solo usage and stacked usage with other decorators
+8. Export from the decorator's `index.ts` barrel
+9. Re-export from `utils/decorators/index.ts`
+
+## Current Decorators
+
+- **Resizable** (`decorators/resizable/`) -- makes an element resizable via drag handles
+- **Draggable** (`decorators/draggable/`) -- makes an element draggable via drag handles

package/src/utils/decorators/clone_with_decorator.ts

@@ -0,0 +1,47 @@
+import React from 'react';
+import type { ClassValue } from 'clsx';
+import { clsx } from 'clsx';
+
+/**
+ * Shared utility for decorator-pattern components that wrap a child via cloneElement.
+ *
+ * Consolidates the boilerplate: merges className via clsx, spreads style,
+ * accepts a pre-forked ref (callers must invoke useForkRef themselves),
+ * and optionally appends extra children (e.g. handles).
+ *
+ * Internal only — not exported from the package.
+ */
+
+interface DecoratorProps {
+  className?: ClassValue;
+  style?: React.CSSProperties;
+  ref?: React.Ref<unknown>;
+  children?: React.ReactNode;
+  [key: string]: unknown;
+}
+
+export function cloneWithDecorator(
+  child: React.ReactElement,
+  injectedProps: DecoratorProps,
+  extraChildren?: React.ReactNode[]
+): React.ReactElement {
+  const { className, style, ref, children, ...rest } = injectedProps;
+
+  const mergedProps: Record<string, unknown> = {
+    ...rest,
+    className: clsx(child.props.className, className),
+    style: { ...child.props.style, ...(style as object) },
+  };
+
+  if (ref !== undefined) {
+    mergedProps.ref = ref;
+  }
+
+  const childContent = children ?? child.props.children;
+
+  if (extraChildren && extraChildren.length > 0) {
+    return React.cloneElement(child, mergedProps, childContent, ...extraChildren);
+  }
+
+  return React.cloneElement(child, mergedProps);
+}

package/src/utils/{dnd → decorators/draggable}/__stories__/draggable.stories.tsx

@@ -1,11 +1,11 @@
-import { Button } from '../../../actions/button/button/button.js';
-import { Box } from '../../../stacks/box/box.js';
-import { VStack } from '../../../stacks/v_stack.js';
-import { ZStack } from '../../../stacks/z_stack.js';
-import { BodyText } from '../../../typography/index.js';
+import { Button } from '../../../../actions/button/button/button.js';
+import { Box } from '../../../../stacks/box/box.js';
+import { VStack } from '../../../../stacks/v_stack.js';
+import { ZStack } from '../../../../stacks/z_stack.js';
+import { BodyText } from '../../../../typography/index.js';
 import { useDragContainer } from '../context.js';
-import { Draggable } from '../draggable/draggable.js';
-import { DragHandle } from '../handle.js';
+import { Draggable } from '../draggable.js';
+import { DragHandle } from '../drag_handle.js';
 import styles from './draggable_stories.module.css';
 
 export default {

package/src/utils/{dnd → decorators/draggable}/__stories__/use_draggable.stories.tsx

@@ -1,6 +1,6 @@
 import React, { useState, useRef } from 'react';
-import { useDraggable } from '../hooks/use_draggable';
-import { Box } from '../../../stacks/box/box.js';
+import { useDraggable } from '../use_draggable.js';
+import { Box } from '../../../../stacks/box/box.js';
 
 export default {
   title: 'Utils/useDraggable',

package/src/utils/{dnd/handle.tsx → decorators/draggable/drag_handle.tsx}

@@ -1,7 +1,7 @@
 import React, { useEffect, useRef } from 'react';
 import clsx from 'clsx';
 import { useDragContainer } from './context.js';
-import { useForkRef } from '../hooks/use_fork_ref.js';
+import { useForkRef } from '../../hooks/use_fork_ref.js';
 
 export interface DragHandleProps {
   children: React.ReactElement;

package/src/utils/{dnd → decorators}/draggable/draggable.tsx

@@ -1,8 +1,8 @@
 import React, { useMemo, type CSSProperties } from 'react';
 
-import { DragContainerContext } from '../context.js';
+import { DragContainerContext } from './context.js';
 import clsx from 'clsx';
-import { useMakeDragContainer } from '../hooks/use_drag_container.js';
+import { useMakeDragContainer } from './use_drag_container.js';
 
 import styles from './draggable.module.css';
 

package/src/utils/decorators/draggable/index.ts

@@ -0,0 +1,15 @@
+export { Draggable } from './draggable.js';
+export type { DraggableProps } from './draggable.js';
+
+export { DragHandle } from './drag_handle.js';
+export type { DragHandleProps } from './drag_handle.js';
+
+export { useDragContainer, DragContainerContext } from './context.js';
+
+export { useDraggable } from './use_draggable.js';
+export type { UseDraggableOptions } from './use_draggable.js';
+
+export { useMakeDragContainer } from './use_drag_container.js';
+export type { UseDragContainerOptions } from './use_drag_container.js';
+
+export type { DragContainer } from './types.js';

package/src/utils/{dnd → decorators/draggable}/types.ts

@@ -1,4 +1,4 @@
-import type { Position } from '../types/dimensions.js';
+import type { Position } from '../../types/dimensions.js';
 
 export interface DragContainer {
   registerHandle: (handle: React.RefObject<HTMLElement>) => void;

package/src/utils/{dnd/hooks → decorators/draggable}/use_drag_container.ts

@@ -1,6 +1,6 @@
 import { useCallback, useRef, useState } from 'react';
-import type { Position } from '../../index.js';
-import type { DragContainer } from '../types.js';
+import type { Position } from '../../types/dimensions.js';
+import type { DragContainer } from './types.js';
 import { useDraggable } from './use_draggable.js';
 
 export interface UseDragContainerOptions {

package/src/utils/decorators/index.ts

@@ -0,0 +1,2 @@
+export * from './resizable/index.js';
+export * from './draggable/index.js';

package/src/utils/decorators/resizable/__stories__/resizable.stories.tsx

@@ -0,0 +1,214 @@
+import { useRef, useState } from 'react';
+import { Resizable } from '../resizable.js';
+import { ResizeHandle } from '../resize_handle.js';
+import { Box } from '../../../../stacks/box/box.js';
+import { VStack } from '../../../../stacks/v_stack.js';
+import { BodyText } from '../../../../typography/index.js';
+import styles from './resizable_stories.module.css';
+
+export default {
+  title: 'Utils/Resizable',
+  component: Resizable,
+  tags: ['autodocs'],
+};
+
+export const HorizontalResize = () => {
+  const [width, setWidth] = useState(300);
+
+  return (
+    <VStack gap="8px" padding="16px" minHeight="400px">
+      <BodyText>Drag the end edge to resize horizontally.</BodyText>
+      <Resizable onWidthResize={({ width: w }) => setWidth(Math.round(w))}>
+        <Box width={`${width}px`} height="200px" className={styles['demo-box']}>
+          <BodyText>Resizable content</BodyText>
+          <div className={styles['size-display']}>width: {width}px</div>
+        </Box>
+        <ResizeHandle position="end" className={styles['demo-handle']} />
+      </Resizable>
+    </VStack>
+  );
+};
+
+export const VerticalResize = () => {
+  const [height, setHeight] = useState(200);
+
+  return (
+    <VStack gap="8px" padding="16px" minHeight="600px">
+      <BodyText>Drag the bottom edge to resize vertically.</BodyText>
+      <Resizable onHeightResize={({ height: h }) => setHeight(Math.round(h))}>
+        <Box width="400px" height={`${height}px`} className={styles['demo-box']}>
+          <BodyText>Resizable content</BodyText>
+          <div className={styles['size-display']}>height: {height}px</div>
+        </Box>
+        <ResizeHandle position="bottom" className={styles['demo-handle']} />
+      </Resizable>
+    </VStack>
+  );
+};
+
+export const CornerResize = () => {
+  const [width, setWidth] = useState(300);
+  const [height, setHeight] = useState(200);
+
+  return (
+    <VStack gap="8px" padding="16px" minHeight="600px">
+      <BodyText>
+        Drag the bottom-right corner to resize both axes simultaneously.
+      </BodyText>
+      <Resizable
+        onWidthResize={({ width: w }) => setWidth(Math.round(w))}
+        onHeightResize={({ height: h }) => setHeight(Math.round(h))}
+      >
+        <Box width={`${width}px`} height={`${height}px`} className={styles['demo-box']}>
+          <BodyText>Resizable content</BodyText>
+          <div className={styles['size-display']}>
+            {width}px × {height}px
+          </div>
+        </Box>
+        <ResizeHandle position="bottom-end" className={styles['demo-handle']} />
+      </Resizable>
+    </VStack>
+  );
+};
+
+export const MultipleHandles = () => {
+  const [width, setWidth] = useState(400);
+  const [height, setHeight] = useState(300);
+
+  return (
+    <VStack gap="8px" padding="16px" minHeight="600px">
+      <BodyText>Start, end, bottom edges and bottom-end corner — all active.</BodyText>
+      <Resizable
+        onWidthResize={({ width: w }) => setWidth(Math.round(w))}
+        onHeightResize={({ height: h }) => setHeight(Math.round(h))}
+      >
+        <Box width={`${width}px`} height={`${height}px`} className={styles['demo-box']}>
+          <BodyText>Resizable content</BodyText>
+          <div className={styles['size-display']}>
+            {width}px × {height}px
+          </div>
+        </Box>
+        <ResizeHandle position="start" className={styles['demo-handle']} />
+        <ResizeHandle position="end" className={styles['demo-handle']} />
+        <ResizeHandle position="bottom" className={styles['demo-handle']} />
+        <ResizeHandle
+          position="bottom-end"
+          className={styles['demo-handle']}
+          style={{
+            zIndex: 2,
+          }}
+        />
+      </Resizable>
+    </VStack>
+  );
+};
+
+export const RTL = () => {
+  const [widthStart, setWidthStart] = useState(300);
+  const [widthEnd, setWidthEnd] = useState(300);
+
+  return (
+    <VStack gap="16px" padding="16px" minHeight="400px">
+      <BodyText>
+        RTL context: &quot;start&quot; flips to the right edge, &quot;end&quot; flips to
+        the left edge.
+      </BodyText>
+      <div className={styles['rtl-container']}>
+        <VStack gap="16px">
+          <BodyText>position=&quot;start&quot; (flips to right edge in RTL)</BodyText>
+          <Resizable onWidthResize={({ width: w }) => setWidthStart(Math.round(w))}>
+            <Box width={`${widthStart}px`} height="100px" className={styles['demo-box']}>
+              <div className={styles['size-display']}>start handle: {widthStart}px</div>
+            </Box>
+            <ResizeHandle position="start" className={styles['demo-handle']} />
+          </Resizable>
+
+          <BodyText>position=&quot;end&quot; (flips to left edge in RTL)</BodyText>
+          <Resizable onWidthResize={({ width: w }) => setWidthEnd(Math.round(w))}>
+            <Box width={`${widthEnd}px`} height="100px" className={styles['demo-box']}>
+              <div className={styles['size-display']}>end handle: {widthEnd}px</div>
+            </Box>
+            <ResizeHandle position="end" className={styles['demo-handle']} />
+          </Resizable>
+        </VStack>
+      </div>
+    </VStack>
+  );
+};
+
+export const NestedResizable = () => {
+  const [outerWidth, setOuterWidth] = useState(500);
+  const [innerWidth, setInnerWidth] = useState(250);
+
+  return (
+    <VStack gap="8px" padding="16px" minHeight="400px">
+      <BodyText>Nested: each handle binds to its nearest Resizable provider.</BodyText>
+      <Resizable onWidthResize={({ width: w }) => setOuterWidth(Math.round(w))}>
+        <Box width={`${outerWidth}px`} height="300px" className={styles['nested-outer']}>
+          <BodyText>Outer ({outerWidth}px)</BodyText>
+          <Resizable onWidthResize={({ width: w }) => setInnerWidth(Math.round(w))}>
+            <Box
+              width={`${innerWidth}px`}
+              height="150px"
+              className={styles['nested-inner']}
+            >
+              <BodyText>Inner ({innerWidth}px)</BodyText>
+            </Box>
+            <ResizeHandle position="end" className={styles['demo-handle']} />
+          </Resizable>
+        </Box>
+        <ResizeHandle position="end" className={styles['demo-handle']} />
+      </Resizable>
+    </VStack>
+  );
+};
+
+export const OverflowHidden = () => {
+  const [width, setWidth] = useState(300);
+
+  return (
+    <VStack gap="8px" padding="16px" minHeight="400px">
+      <BodyText>
+        Outer box is the resize target (minWidth: 100px). Inner box clips content with
+        overflow:hidden. Shrink below 200px to clip the purple box. It stops at 100px due
+        to the min-width constraint.
+      </BodyText>
+      <Resizable onWidthResize={({ width: w }) => setWidth(Math.round(w))}>
+        <Box width={`${width}px`} minWidth="100px" height="200px">
+          <Box height="100%" overflow="hidden" className={styles['demo-box']}>
+            <Box minWidth="200px" height="80px" className={styles['clip-target']} />
+            <div className={styles['size-display']}>width: {width}px</div>
+          </Box>
+        </Box>
+        <ResizeHandle position="end" className={styles['demo-handle']} />
+      </Resizable>
+    </VStack>
+  );
+};
+
+export const CustomHandle = () => {
+  const handleRef = useRef<HTMLDivElement>(null);
+  const [width, setWidth] = useState(300);
+
+  return (
+    <VStack gap="8px" padding="16px" minHeight="400px">
+      <BodyText>Custom styled handle with forwarded ref and aria attributes.</BodyText>
+      <Resizable onWidthResize={({ width: w }) => setWidth(Math.round(w))}>
+        <Box width={`${width}px`} height="200px" className={styles['demo-box']}>
+          <BodyText>Resizable content</BodyText>
+          <div className={styles['size-display']}>width: {width}px</div>
+        </Box>
+        <ResizeHandle
+          ref={handleRef}
+          position="end"
+          style={{
+            background: 'rgba(234, 67, 53, 0.4)',
+            width: '8px',
+          }}
+          aria-label="Resize handle"
+          data-testid="custom-handle"
+        />
+      </Resizable>
+    </VStack>
+  );
+};