@tcn/ui 0.16.0 → 0.18.0

package/src/utils/decorators/resizable/__stories__/resizable_stories.module.css

@@ -0,0 +1,47 @@
+@layer tcn-system {
+  :where(.demo-box) {
+    background: var(--tcn-color-surface-secondary, #f0f0f0);
+    border: 1px solid var(--tcn-color-border, #ccc);
+    padding: 16px;
+    position: relative;
+  }
+
+  :where(.demo-handle) {
+    background: rgba(0, 120, 212, 0.3);
+  }
+
+  :where(.demo-handle:hover) {
+    background: rgba(0, 120, 212, 0.6);
+  }
+
+  :where(.size-display) {
+    font-family: monospace;
+    font-size: 12px;
+    color: var(--tcn-color-text-secondary, #666);
+    margin-top: 8px;
+  }
+
+  :where(.rtl-container) {
+    direction: rtl;
+    border: 2px dashed #999;
+    padding: 16px;
+  }
+
+  :where(.clip-target) {
+    background: #7b1fa2;
+    border-radius: 4px;
+    flex-shrink: 0;
+  }
+
+  :where(.nested-outer) {
+    background: #e8f0fe;
+    border: 2px solid #4285f4;
+    padding: 24px;
+  }
+
+  :where(.nested-inner) {
+    background: #fce8e6;
+    border: 2px solid #ea4335;
+    padding: 16px;
+  }
+}

package/src/utils/decorators/resizable/__tests__/handle_config.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect } from 'vitest';
+import {
+  getHandleConfig,
+  resolveDirection,
+  resolveHandleConfig,
+  computeResizeState,
+} from '../handle_config.js';
+
+describe('getHandleConfig', () => {
+  describe('edge positions', () => {
+    it('start → horizontal, origin start, invert true, disableDirection false', () => {
+      const config = getHandleConfig('start');
+      expect(config.horizontal).toEqual({
+        origin: 'start',
+        invert: true,
+        disableDirection: false,
+      });
+      expect(config.vertical).toBeUndefined();
+    });
+
+    it('end → horizontal, origin end, invert false, disableDirection false', () => {
+      const config = getHandleConfig('end');
+      expect(config.horizontal).toEqual({
+        origin: 'end',
+        invert: false,
+        disableDirection: false,
+      });
+      expect(config.vertical).toBeUndefined();
+    });
+
+    it('top → vertical, origin top, invert true', () => {
+      const config = getHandleConfig('top');
+      expect(config.vertical).toEqual({
+        origin: 'top',
+        invert: true,
+        disableDirection: true,
+      });
+      expect(config.horizontal).toBeUndefined();
+    });
+
+    it('bottom → vertical, origin bottom, invert false', () => {
+      const config = getHandleConfig('bottom');
+      expect(config.vertical).toEqual({
+        origin: 'bottom',
+        invert: false,
+        disableDirection: true,
+      });
+      expect(config.horizontal).toBeUndefined();
+    });
+  });
+
+  describe('corner positions', () => {
+    it('top-start → horizontal disableDirection false', () => {
+      const config = getHandleConfig('top-start');
+      expect(config.horizontal?.disableDirection).toBe(false);
+      expect(config.vertical?.disableDirection).toBe(true);
+    });
+
+    it('top-end → horizontal disableDirection false', () => {
+      const config = getHandleConfig('top-end');
+      expect(config.horizontal?.disableDirection).toBe(false);
+      expect(config.vertical?.disableDirection).toBe(true);
+    });
+
+    it('bottom-start → horizontal disableDirection false', () => {
+      const config = getHandleConfig('bottom-start');
+      expect(config.horizontal?.disableDirection).toBe(false);
+      expect(config.vertical?.disableDirection).toBe(true);
+    });
+
+    it('bottom-end → horizontal disableDirection false', () => {
+      const config = getHandleConfig('bottom-end');
+      expect(config.horizontal?.disableDirection).toBe(false);
+      expect(config.vertical?.disableDirection).toBe(true);
+    });
+  });
+});
+
+describe('resolveDirection', () => {
+  describe('LTR', () => {
+    it('invert=false → +1', () => {
+      expect(resolveDirection('ltr', false, false)).toBe(1);
+    });
+
+    it('invert=true → -1', () => {
+      expect(resolveDirection('ltr', true, false)).toBe(-1);
+    });
+
+    it('disableDirection has no effect in LTR', () => {
+      expect(resolveDirection('ltr', false, true)).toBe(1);
+      expect(resolveDirection('ltr', true, true)).toBe(-1);
+    });
+  });
+
+  describe('RTL', () => {
+    it('invert=false, disableDirection=false → flipped to -1', () => {
+      expect(resolveDirection('rtl', false, false)).toBe(-1);
+    });
+
+    it('invert=true, disableDirection=false → flipped to +1', () => {
+      expect(resolveDirection('rtl', true, false)).toBe(1);
+    });
+
+    it('disableDirection=true → no flip, same as LTR', () => {
+      expect(resolveDirection('rtl', false, true)).toBe(1);
+      expect(resolveDirection('rtl', true, true)).toBe(-1);
+    });
+  });
+});
+
+describe('computeResizeState', () => {
+  it('computes positive delta when moving in direction', () => {
+    const result = computeResizeState(200, 100, 150, 1, 200);
+    expect(result.newSize).toBe(250);
+    expect(result.totalDelta).toBe(50);
+    expect(result.currentDelta).toBe(50);
+  });
+
+  it('computes negative delta when moving against direction', () => {
+    const result = computeResizeState(200, 100, 50, 1, 200);
+    expect(result.newSize).toBe(150);
+    expect(result.totalDelta).toBe(-50);
+    expect(result.currentDelta).toBe(-50);
+  });
+
+  it('respects direction multiplier', () => {
+    const result = computeResizeState(200, 100, 150, -1, 200);
+    expect(result.newSize).toBe(150);
+    expect(result.totalDelta).toBe(-50);
+    expect(result.currentDelta).toBe(-50);
+  });
+
+  it('tracks currentDelta relative to previousSize', () => {
+    // First move: 200 → 250
+    const first = computeResizeState(200, 100, 150, 1, 200);
+    expect(first.newSize).toBe(250);
+    expect(first.currentDelta).toBe(50);
+
+    // Second move: 200 → 260 (10px further), previous was 250
+    const second = computeResizeState(200, 100, 160, 1, 250);
+    expect(second.newSize).toBe(260);
+    expect(second.totalDelta).toBe(60);
+    expect(second.currentDelta).toBe(10);
+  });
+
+  it('handles zero movement', () => {
+    const result = computeResizeState(200, 100, 100, 1, 200);
+    expect(result.newSize).toBe(200);
+    expect(result.totalDelta).toBe(0);
+    expect(result.currentDelta).toBe(0);
+  });
+});
+
+describe('resolveHandleConfig', () => {
+  it('resolves end edge with direction in LTR', () => {
+    const config = resolveHandleConfig('end', 'ltr');
+    expect(config.horizontal).toEqual({ origin: 'end', direction: 1 });
+    expect(config.vertical).toBeUndefined();
+  });
+
+  it('resolves start edge with direction in LTR (inverted)', () => {
+    const config = resolveHandleConfig('start', 'ltr');
+    expect(config.horizontal).toEqual({ origin: 'start', direction: -1 });
+  });
+
+  it('start flips direction in RTL', () => {
+    const ltr = resolveHandleConfig('start', 'ltr');
+    const rtl = resolveHandleConfig('start', 'rtl');
+    expect(ltr.horizontal?.direction).toBe(-1);
+    expect(rtl.horizontal?.direction).toBe(1);
+  });
+
+  it('end flips direction in RTL', () => {
+    const ltr = resolveHandleConfig('end', 'ltr');
+    const rtl = resolveHandleConfig('end', 'rtl');
+    expect(ltr.horizontal?.direction).toBe(1);
+    expect(rtl.horizontal?.direction).toBe(-1);
+  });
+
+  it('resolves corner with both axes', () => {
+    const config = resolveHandleConfig('bottom-end', 'ltr');
+    expect(config.horizontal).toEqual({ origin: 'end', direction: 1 });
+    expect(config.vertical).toEqual({ origin: 'bottom', direction: 1 });
+  });
+
+  it('corner horizontal flips in RTL, vertical does not', () => {
+    const config = resolveHandleConfig('bottom-start', 'rtl');
+    expect(config.horizontal?.direction).toBe(1);
+    expect(config.vertical?.direction).toBe(1);
+  });
+});

package/src/utils/decorators/resizable/__tests__/resize_strategy.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect } from 'vitest';
+import { ResizeHandleStrategy } from '../resize_strategy.js';
+import type { StartResizeParams } from '../resize_strategy.js';
+
+const defaults: StartResizeParams = {
+  rectangle: {
+    dimensions: { width: 300, height: 200 },
+    position: { x: 100, y: 100 },
+  },
+  languageDirection: 'ltr',
+};
+
+function start(
+  strategy: ResizeHandleStrategy,
+  overrides: Partial<StartResizeParams> = {}
+) {
+  strategy.startResize({ ...defaults, ...overrides });
+}
+
+describe('ResizeHandleStrategy', () => {
+  describe('horizontal edge (end)', () => {
+    it('computes positive resize when dragging right', () => {
+      const strategy = new ResizeHandleStrategy('end');
+      start(strategy);
+
+      const result = strategy.resize({ x: 150, y: 100 });
+      expect(result.horizontal).toBeDefined();
+      expect(result.horizontal?.newSize).toBe(350);
+      expect(result.horizontal?.origin).toBe('end');
+      expect(result.horizontal?.totalDelta).toBe(50);
+      expect(result.horizontal?.currentDelta).toBe(50);
+      expect(result.vertical).toBeUndefined();
+    });
+
+    it('computes negative resize when dragging left', () => {
+      const strategy = new ResizeHandleStrategy('end');
+      start(strategy);
+
+      const result = strategy.resize({ x: 50, y: 100 });
+      expect(result.horizontal?.newSize).toBe(250);
+      expect(result.horizontal?.totalDelta).toBe(-50);
+    });
+  });
+
+  describe('horizontal edge (start, inverted)', () => {
+    it('shrinks when dragging right', () => {
+      const strategy = new ResizeHandleStrategy('start');
+      start(strategy);
+
+      const result = strategy.resize({ x: 150, y: 100 });
+      expect(result.horizontal?.newSize).toBe(250);
+      expect(result.horizontal?.origin).toBe('start');
+    });
+
+    it('grows when dragging left', () => {
+      const strategy = new ResizeHandleStrategy('start');
+      start(strategy);
+
+      const result = strategy.resize({ x: 50, y: 100 });
+      expect(result.horizontal?.newSize).toBe(350);
+    });
+  });
+
+  describe('vertical edge (bottom)', () => {
+    it('computes vertical resize only', () => {
+      const strategy = new ResizeHandleStrategy('bottom');
+      start(strategy);
+
+      const result = strategy.resize({ x: 100, y: 150 });
+      expect(result.horizontal).toBeUndefined();
+      expect(result.vertical).toBeDefined();
+      expect(result.vertical?.newSize).toBe(250);
+      expect(result.vertical?.origin).toBe('bottom');
+    });
+  });
+
+  describe('corner (bottom-end)', () => {
+    it('computes both axes simultaneously', () => {
+      const strategy = new ResizeHandleStrategy('bottom-end');
+      start(strategy);
+
+      const result = strategy.resize({ x: 160, y: 140 });
+      expect(result.horizontal?.newSize).toBe(360);
+      expect(result.horizontal?.origin).toBe('end');
+      expect(result.vertical?.newSize).toBe(240);
+      expect(result.vertical?.origin).toBe('bottom');
+    });
+  });
+
+  describe('RTL', () => {
+    it('start handle flips direction in RTL', () => {
+      const strategy = new ResizeHandleStrategy('start');
+      start(strategy, { languageDirection: 'rtl' });
+
+      const result = strategy.resize({ x: 150, y: 100 });
+      expect(result.horizontal?.newSize).toBe(350);
+    });
+
+    it('start handle does not flip in LTR', () => {
+      const strategy = new ResizeHandleStrategy('start');
+      start(strategy);
+
+      const result = strategy.resize({ x: 150, y: 100 });
+      expect(result.horizontal?.newSize).toBe(250);
+    });
+
+    it('end handle flips direction in RTL', () => {
+      const strategy = new ResizeHandleStrategy('end');
+      start(strategy, { languageDirection: 'rtl' });
+
+      const result = strategy.resize({ x: 150, y: 100 });
+      expect(result.horizontal?.newSize).toBe(250);
+    });
+  });
+
+  describe('commitResize — tracks applied dimensions', () => {
+    it('currentDelta tracks committed size', () => {
+      const strategy = new ResizeHandleStrategy('end');
+      start(strategy);
+
+      strategy.resize({ x: 150, y: 100 });
+      strategy.commitResize({ width: 350, height: 200 });
+
+      const second = strategy.resize({ x: 170, y: 100 });
+      expect(second.horizontal?.newSize).toBe(370);
+      expect(second.horizontal?.currentDelta).toBe(20);
+    });
+
+    it('currentDelta is correct when previous resize was clamped', () => {
+      const strategy = new ResizeHandleStrategy('end');
+      start(strategy);
+
+      strategy.resize({ x: 150, y: 100 });
+      strategy.commitResize({ width: 320, height: 200 });
+
+      const result = strategy.resize({ x: 160, y: 100 });
+      expect(result.horizontal?.newSize).toBe(360);
+      expect(result.horizontal?.currentDelta).toBe(40);
+    });
+  });
+
+  describe('endResize', () => {
+    it('returns committed sizes and origins', () => {
+      const strategy = new ResizeHandleStrategy('bottom-end');
+      start(strategy);
+
+      strategy.resize({ x: 180, y: 160 });
+      strategy.commitResize({ width: 380, height: 260 });
+
+      const result = strategy.endResize();
+      expect(result.horizontal).toEqual({ width: 380, origin: 'end' });
+      expect(result.vertical).toEqual({ height: 260, origin: 'bottom' });
+    });
+
+    it('returns start sizes if no resize occurred', () => {
+      const strategy = new ResizeHandleStrategy('end');
+      start(strategy);
+
+      const result = strategy.endResize();
+      expect(result.horizontal).toEqual({ width: 300, origin: 'end' });
+    });
+  });
+});

package/src/utils/decorators/resizable/context.ts

@@ -0,0 +1,9 @@
+import { createContext } from 'react';
+import { makeContextHook } from '../../hooks/make_context_hook.js';
+import type { ResizableContextValue } from './types.js';
+
+export const ResizableContext = createContext<ResizableContextValue | undefined>(
+  undefined
+);
+
+export const useResizable = makeContextHook(ResizableContext, 'ResizableContext');

package/src/utils/decorators/resizable/handle_config.ts

@@ -0,0 +1,118 @@
+import type {
+  AxisConfig,
+  HandleConfig,
+  ResolvedHandleConfig,
+  ResizeHandlePosition,
+} from './types.js';
+
+/**
+ * Pure position → config lookup. No DOM, no React.
+ *
+ * Edges populate one axis, corners populate both.
+ * The React adapter reads DOM state (getBoundingClientRect, getComputedStyle)
+ * and feeds resolved values into resolveDirection / computeResizeState.
+ */
+
+const configs: Record<ResizeHandlePosition, HandleConfig> = {
+  // Edges — single axis
+  start: {
+    horizontal: { origin: 'start', invert: true, disableDirection: false },
+  },
+  end: {
+    horizontal: { origin: 'end', invert: false, disableDirection: false },
+  },
+  top: {
+    vertical: { origin: 'top', invert: true, disableDirection: true },
+  },
+  bottom: {
+    vertical: { origin: 'bottom', invert: false, disableDirection: true },
+  },
+
+  // Corners — dual axis
+  'top-start': {
+    horizontal: { origin: 'start', invert: true, disableDirection: false },
+    vertical: { origin: 'top', invert: true, disableDirection: true },
+  },
+  'top-end': {
+    horizontal: { origin: 'end', invert: false, disableDirection: false },
+    vertical: { origin: 'top', invert: true, disableDirection: true },
+  },
+  'bottom-start': {
+    horizontal: { origin: 'start', invert: true, disableDirection: false },
+    vertical: { origin: 'bottom', invert: false, disableDirection: true },
+  },
+  'bottom-end': {
+    horizontal: { origin: 'end', invert: false, disableDirection: false },
+    vertical: { origin: 'bottom', invert: false, disableDirection: true },
+  },
+};
+
+export function getHandleConfig(position: ResizeHandlePosition): HandleConfig {
+  return configs[position];
+}
+
+/**
+ * Resolve the direction multiplier for a resize axis.
+ *
+ * @param languageDirection - 'ltr' or 'rtl' from getComputedStyle (passed by React adapter)
+ * @param invert - whether the axis inverts the delta (e.g. dragging left-handle right shrinks)
+ * @param disableDirection - if true, ignore RTL (physical positions like left/right)
+ * @returns +1 or -1
+ */
+export function resolveDirection(
+  languageDirection: string,
+  invert: boolean,
+  disableDirection: boolean
+): number {
+  const finalInvert = languageDirection === 'rtl' && !disableDirection ? !invert : invert;
+  return finalInvert ? -1 : 1;
+}
+
+function resolveAxis(axis: AxisConfig, languageDirection: string) {
+  return {
+    origin: axis.origin,
+    direction: resolveDirection(languageDirection, axis.invert, axis.disableDirection),
+  };
+}
+
+/**
+ * Combines position lookup with direction resolution.
+ * The caller only needs to provide the language direction from the DOM —
+ * all config internals (invert, disableDirection) are resolved here.
+ */
+export function resolveHandleConfig(
+  position: ResizeHandlePosition,
+  languageDirection: string
+): ResolvedHandleConfig {
+  const config = configs[position];
+  return {
+    horizontal: config.horizontal
+      ? resolveAxis(config.horizontal, languageDirection)
+      : undefined,
+    vertical: config.vertical
+      ? resolveAxis(config.vertical, languageDirection)
+      : undefined,
+  };
+}
+
+/**
+ * Pure resize state computation. Called per-axis on each mousemove.
+ *
+ * @param startSize - element width/height at mousedown (from getBoundingClientRect)
+ * @param startCoord - clientX/clientY at mousedown
+ * @param currentCoord - clientX/clientY at this mousemove
+ * @param direction - +1 or -1 from resolveDirection
+ * @param previousSize - the size after the last mousemove (for currentDelta)
+ */
+export function computeResizeState(
+  startSize: number,
+  startCoord: number,
+  currentCoord: number,
+  direction: number,
+  previousSize: number
+): { newSize: number; totalDelta: number; currentDelta: number } {
+  const totalDelta = direction * (currentCoord - startCoord);
+  const newSize = startSize + totalDelta;
+  const currentDelta = newSize - previousSize;
+  return { newSize, totalDelta, currentDelta };
+}

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

@@ -0,0 +1,37 @@
+export { Resizable } from './resizable.js';
+export type { ResizableProps } from './resizable.js';
+
+export { ResizeHandle } from './resize_handle.js';
+export type { ResizeHandleProps } from './resize_handle.js';
+
+export { useResizable } from './context.js';
+
+export {
+  getHandleConfig,
+  resolveDirection,
+  resolveHandleConfig,
+  computeResizeState,
+} from './handle_config.js';
+export { ResizeHandleStrategy } from './resize_strategy.js';
+export type {
+  StartResizeParams,
+  HorizontalResizeResult,
+  VerticalResizeResult,
+  ResizeResult,
+  EndResizeResult,
+} from './resize_strategy.js';
+
+export type {
+  ResizeHandlePosition,
+  HandleConfig,
+  AxisConfig,
+  ResizableContextValue,
+  ResolvedAxisConfig,
+  ResolvedHandleConfig,
+  OnWidthResize,
+  OnWidthResizeEnd,
+  OnHeightResize,
+  OnHeightResizeEnd,
+  WidthResizeOrigin,
+  HeightResizeOrigin,
+} from './types.js';

package/src/utils/decorators/resizable/resizable.module.css

@@ -0,0 +1,5 @@
+@layer tcn-system {
+  :where(.resizable-target) {
+    position: relative;
+  }
+}

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

@@ -0,0 +1,97 @@
+import React, { useMemo, useRef } from 'react';
+import { clsx } from 'clsx';
+import { useForkRef } from '../../hooks/use_fork_ref.js';
+import { ResizableContext } from './context.js';
+import type {
+  OnWidthResize,
+  OnWidthResizeEnd,
+  OnHeightResize,
+  OnHeightResizeEnd,
+  ResizableContextValue,
+} from './types.js';
+import styles from './resizable.module.css';
+
+export interface ResizableProps {
+  children: React.ReactNode;
+  onWidthResize?: OnWidthResize;
+  onWidthResizeEnd?: OnWidthResizeEnd;
+  onHeightResize?: OnHeightResize;
+  onHeightResizeEnd?: OnHeightResizeEnd;
+}
+
+interface ResizableTargetProps {
+  className?: string;
+  children?: React.ReactNode;
+  ref?: React.Ref<HTMLElement>;
+}
+
+type ResizableTarget = React.ReactElement<ResizableTargetProps>;
+
+function isResizableTarget(child: React.ReactNode): child is ResizableTarget {
+  if (!React.isValidElement(child)) return false;
+  const type = child.type;
+  if (typeof type === 'string') return true;
+  if (typeof type === 'function' || typeof type === 'object') {
+    return (type as { displayName?: string }).displayName !== 'ResizeHandle';
+  }
+  return false;
+}
+
+function isResizeHandle(child: React.ReactNode): boolean {
+  return React.isValidElement(child) && !isResizableTarget(child);
+}
+
+export function Resizable({
+  children,
+  onWidthResize,
+  onWidthResizeEnd,
+  onHeightResize,
+  onHeightResizeEnd,
+}: ResizableProps) {
+  const targetRef = useRef<HTMLElement | null>(null);
+
+  const childArray = React.Children.toArray(children);
+  const targetChild = childArray.find(isResizableTarget);
+  const handleChildren = childArray.filter(isResizeHandle);
+
+  const contextValue = useMemo<ResizableContextValue>(
+    () => ({
+      targetRef,
+      onWidthResize,
+      onWidthResizeEnd,
+      onHeightResize,
+      onHeightResizeEnd,
+    }),
+    [onWidthResize, onWidthResizeEnd, onHeightResize, onHeightResizeEnd]
+  );
+
+  const forkedRef = useForkRef(targetRef, targetChild?.props.ref);
+
+  if (!targetChild) {
+    return (
+      <ResizableContext.Provider value={contextValue}>
+        {children}
+      </ResizableContext.Provider>
+    );
+  }
+
+  const clonedTarget = React.cloneElement(
+    targetChild,
+    {
+      ref: forkedRef,
+      className: clsx(
+        targetChild.props.className,
+        styles['resizable-target'],
+        'tcn-resizable-target'
+      ),
+    },
+    targetChild.props.children,
+    ...handleChildren
+  );
+
+  return (
+    <ResizableContext.Provider value={contextValue}>
+      {clonedTarget}
+    </ResizableContext.Provider>
+  );
+}