Rename Arrow sizing properties

- length to size
- spread to base

Author: gilbarbara

CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Development
+- `npm run watch` - Build and watch for changes (uses tsup)
+- `npm run build` - Clean and build the library for production
+
+### Testing
+- `npm test` - Run tests in watch mode (development)
+- `npm run test:coverage` - Run tests with coverage report
+- Run a single test: `vitest run test/index.spec.tsx`
+
+### Quality Checks
+- `npm run lint` - Lint and fix code issues
+- `npm run typecheck` - Run TypeScript type checking
+- `npm run validate` - Run full validation suite (lint, typecheck, test, build, size check)
+- `npm run size` - Check bundle size limits
+
+## Architecture
+
+### Core Component Flow
+The library uses a state machine pattern for managing the floater lifecycle:
+
+1. **Main Entry** (`src/index.tsx`): The `ReactFloater` component manages state using `useReducer` and handles:
+   - Popper.js instance creation/management for positioning
+   - Event handling (click/hover) with mobile detection
+   - Portal rendering for the floating element
+   - Status transitions: IDLE → OPENING → OPEN → CLOSING → IDLE
+
+2. **Component Structure**:
+   - `Portal` (`src/components/Portal.tsx`): Manages DOM portal rendering
+   - `Floater` (`src/components/Floater/index.tsx`): The floating UI container
+   - `Container` (`src/components/Floater/Container.tsx`): Content wrapper with title/footer
+   - `Arrow` (`src/components/Floater/Arrow.tsx`): Customizable arrow element
+   - `Wrapper` (`src/components/Wrapper.tsx`): Target element wrapper for beacon mode
+
+3. **Positioning System**: Uses Popper.js v2 with:
+   - Custom modifiers configuration via `getModifiers()` helper
+   - Fallback placements for auto-positioning
+   - Fixed positioning detection for proper scrolling behavior
+
+### Key Patterns
+
+**State Management**: The component uses `useReducer` with status-based state transitions. Changes are tracked using `tree-changes-hook` for efficient callback triggers.
+
+**Style Merging**: Custom styles are deeply merged with defaults using `deepmerge-ts`. The styles object structure is defined in `src/modules/styles.ts`.
+
+**Event Handling**: Special handling for mobile devices (converts hover to click) and delayed hiding for hover events using timeouts.
+
+**Type Safety**: Uses TypeScript with strict typing. Key type definitions in:
+- `src/types/common.ts`: Component props, states, and common types
+- `src/types/popper.ts`: Popper.js related types
+
+### Testing Approach
+- Uses Vitest with React Testing Library
+- Test files in `test/` directory
+- Coverage requirements: 90% for all metrics
+- Mock components in `test/__fixtures__/`

demo/src/examples/WithCustomStyles.tsx

@@ -28,9 +28,9 @@ export default function WithCustomStyles({ cb }: any) {
           textAlign: 'right',
         },
         arrow: {
+          base: 10,
           color: '#000',
-          length: 8,
-          spread: 10,
+          size: 8,
         },
       }}
       title={

demo/src/examples/WithStyledComponents.tsx

@@ -1,4 +1,4 @@
-  import Floater, { CustomComponentProps } from 'react-floater';
+import Floater, { CustomComponentProps } from 'react-floater';
 import styled from '@emotion/styled';
 import { Button } from '@gilbarbara/components';
 
@@ -39,11 +39,11 @@ export default function WithStyledComponents({ cb }: any) {
         arrow={
           <svg
             height="100px"
+            transform="rotate(180)"
             version="1.1"
             viewBox="0 0 10 100"
             width="10px"
             xmlns="http://www.w3.org/2000/svg"
-            transform="rotate(180)"
           >
             <g>
               <path
@@ -60,9 +60,9 @@ export default function WithStyledComponents({ cb }: any) {
         portalElement="#portalElement"
         styles={{
           arrow: {
-            length: 80,
-            spread: 10,
+            base: 10,
             color: '#6ba2ff',
+            size: 80,
           },
         }}
       >

demo/src/examples/WithTitleAndFooter.tsx

@@ -17,8 +17,8 @@ export default function WithTitleAndFooter({ cb }: any) {
       placement="left"
       styles={{
         arrow: {
-          length: 64,
-          spread: 12,
+          base: 12,
+          size: 64,
         },
       }}
       title="Oi, I have a title!"

src/components/Floater/Arrow.tsx

@@ -12,31 +12,38 @@ interface Props {
 export default function FloaterArrow(props: Props) {
   const { arrow, arrowRef, placement, styles } = props;
   const {
-    arrow: { color, display, length, position, spread },
+    arrow: { base, color, display, position, size },
   } = styles;
   const arrowStyles: CSSProperties = { display, position };
 
   let points;
-  let x = spread;
-  let y = length;
+  let x = base;
+  let y = size;
 
   if (placement.startsWith('top')) {
     points = `0,0 ${x / 2},${y} ${x},0`;
   } else if (placement.startsWith('bottom')) {
     points = `${x},${y} ${x / 2},0 0,${y}`;
   } else if (placement.startsWith('left')) {
-    y = spread;
-    x = length;
+    y = base;
+    x = size;
     points = `0,0 ${x},${y / 2} 0,${y}`;
   } else if (placement.startsWith('right')) {
-    y = spread;
-    x = length;
+    y = base;
+    x = size;
     points = `${x},${y} ${x},0 0,${y / 2}`;
   }
 
   if (arrow) {
     return (
-      <span ref={arrowRef} style={{ color, height: length, width: spread }}>
+      <span
+        ref={arrowRef}
+        style={{
+          color,
+          height: placement.startsWith('left') || placement.startsWith('right') ? base : size,
+          width: placement.startsWith('left') || placement.startsWith('right') ? size : base,
+        }}
+      >
         {arrow}
       </span>
     );

src/components/Floater/index.tsx

@@ -40,7 +40,7 @@ function Floater(props: Props) {
 
   const style = useMemo(() => {
     const {
-      arrow: { length },
+      arrow: { size },
       floater,
       floaterCentered,
       floaterClosing,
@@ -51,13 +51,13 @@ function Floater(props: Props) {
 
     if (!hideArrow) {
       if (placement.startsWith('top')) {
-        element.padding = `0 0 ${length}px`;
+        element.padding = `0 0 ${size}px`;
       } else if (placement.startsWith('bottom')) {
-        element.padding = `${length}px 0 0`;
+        element.padding = `${size}px 0 0`;
       } else if (placement.startsWith('left')) {
-        element.padding = `0 ${length}px 0 0`;
+        element.padding = `0 ${size}px 0 0`;
       } else if (placement.startsWith('right')) {
-        element.padding = `0 0 0 ${length}px`;
+        element.padding = `0 0 0 ${size}px`;
       }
     }
 

src/modules/styles.ts

@@ -13,11 +13,11 @@ export default function getStyles(styles?: PartialDeep<Styles>): Styles {
   return deepmerge(
     {
       arrow: {
+        base: 32,
         color: '#fff',
         display: 'inline-flex',
-        length: 16,
         position: 'absolute',
-        spread: 32,
+        size: 16,
       },
       close: {
         backgroundColor: 'transparent',

src/types/common.ts

@@ -136,8 +136,14 @@ export interface State {
 
 export interface Styles {
   arrow: CSSProperties & {
-    length: number;
-    spread: number;
+    /**
+     * The distance from the tip of the arrow to the edge of the Floater.
+     */
+    base: number;
+    /**
+     * The width of the base of the arrow.
+     */
+    size: number;
   };
   close: CSSProperties;
   container: CSSProperties;

test/index.spec.tsx

@@ -699,8 +699,8 @@ describe('ReactFloater', () => {
         styles: {
           arrow: {
             color: '#6ba2ff',
-            length: 80,
-            spread: 10,
+            size: 80,
+            base: 10,
           },
         },
       });