@idealyst/components 1.0.82 → 1.0.84

package/src/utils/buildSizeVariants.ts

@@ -0,0 +1,16 @@
+import { AllComponentSizes, Size, Theme, Styles } from '@idealyst/theme';
+
+/**
+ * Builds a generic size variant. Not really useful on its own tbh, just good to show how it can be used.
+ * Context really matters for sizes
+ * @param theme 
+ * @param builder 
+ * @returns 
+ */
+export function buildSizeVariants<T extends keyof AllComponentSizes>(theme: Theme, component: T, builder: (value: AllComponentSizes[T][Size]) => Styles): Record<Size, Styles> {
+    const variants = {} as Record<Size, Styles>;
+    for (const size in theme.sizes[component]) {
+        variants[size as Size] = builder(theme.sizes[component][size as Size]);
+    }
+    return variants;
+}

package/src/utils/deepMerge.ts

@@ -0,0 +1,43 @@
+/**
+ * Check if a value is a plain object (not an array, null, or other special object)
+ */
+function isPlainObject(value: unknown): value is Record<string, any> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.prototype.toString.call(value) === '[object Object]'
+  )
+}
+
+/**
+ * Deep merge two objects together, with the second object taking priority.
+ * Arrays and non-plain objects are replaced rather than merged.
+ *
+ * @param target - The base object
+ * @param source - The object to merge in (takes priority)
+ * @returns A new merged object
+ */
+export function deepMerge<T extends Record<string, any>, S extends Record<string, any>>(
+  target: T,
+  source: S
+): T & S {
+  const result: Record<string, any> = { ...target }
+
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key]
+      const targetValue = result[key]
+
+      // If both values are plain objects, merge them recursively
+      if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+        result[key] = deepMerge(targetValue, sourceValue)
+      } else {
+        // Otherwise, source value takes priority (including arrays, primitives, null, undefined)
+        result[key] = sourceValue
+      }
+    }
+  }
+
+  return result as T & S
+}

package/src/utils/positionUtils.native.ts

@@ -0,0 +1,280 @@
+import { Dimensions } from 'react-native';
+
+/**
+ * Calculate the maximum available height for content at a given position
+ * This matches the logic in BoundedModalContent to ensure positioning is accurate
+ */
+export const calculateAvailableHeight = (
+  top: number,
+  safeAreaInsets?: SafeAreaInsets
+): number => {
+  const { height: windowHeight } = Dimensions.get('window');
+  const padding = 12;
+  const bottomSafeEdge = windowHeight - (safeAreaInsets?.bottom || 0);
+  const bottomBound = bottomSafeEdge - padding;
+  return Math.max(100, bottomBound - top);
+};
+
+export type Placement =
+  | 'top' | 'top-start' | 'top-end'
+  | 'bottom' | 'bottom-start' | 'bottom-end'
+  | 'left' | 'left-start' | 'left-end'
+  | 'right' | 'right-start' | 'right-end';
+
+export interface Position {
+  top: number;
+  left: number;
+  width?: number;
+}
+
+export interface AnchorMeasurements {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface ContentSize {
+  width: number;
+  height: number;
+}
+
+export interface SafeAreaInsets {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/**
+ * Get the opposite placement (for flipping)
+ */
+const getOppositePlacement = (placement: Placement): Placement => {
+  const opposites: Record<Placement, Placement> = {
+    'top': 'bottom',
+    'top-start': 'bottom-start',
+    'top-end': 'bottom-end',
+    'bottom': 'top',
+    'bottom-start': 'top-start',
+    'bottom-end': 'top-end',
+    'left': 'right',
+    'left-start': 'right-start',
+    'left-end': 'right-end',
+    'right': 'left',
+    'right-start': 'left-start',
+    'right-end': 'left-end',
+  };
+  return opposites[placement];
+};
+
+/**
+ * Calculate position for a given placement without boundary checks
+ */
+const calculatePositionForPlacement = (
+  anchor: AnchorMeasurements,
+  contentSize: ContentSize,
+  placement: Placement,
+  offset: number
+): Position => {
+  let top = 0;
+  let left = 0;
+
+  switch (placement) {
+    case 'top':
+      top = anchor.y - contentSize.height - offset;
+      left = anchor.x + anchor.width / 2 - contentSize.width / 2;
+      break;
+    case 'top-start':
+      top = anchor.y - contentSize.height - offset;
+      left = anchor.x;
+      break;
+    case 'top-end':
+      top = anchor.y - contentSize.height - offset;
+      left = anchor.x + anchor.width - contentSize.width;
+      break;
+    case 'bottom':
+      top = anchor.y + anchor.height + offset;
+      left = anchor.x + anchor.width / 2 - contentSize.width / 2;
+      break;
+    case 'bottom-start':
+      top = anchor.y + anchor.height + offset;
+      left = anchor.x;
+      break;
+    case 'bottom-end':
+      top = anchor.y + anchor.height + offset;
+      left = anchor.x + anchor.width - contentSize.width;
+      break;
+    case 'left':
+      top = anchor.y + anchor.height / 2 - contentSize.height / 2;
+      left = anchor.x - contentSize.width - offset;
+      break;
+    case 'left-start':
+      top = anchor.y;
+      left = anchor.x - contentSize.width - offset;
+      break;
+    case 'left-end':
+      top = anchor.y + anchor.height - contentSize.height;
+      left = anchor.x - contentSize.width - offset;
+      break;
+    case 'right':
+      top = anchor.y + anchor.height / 2 - contentSize.height / 2;
+      left = anchor.x + anchor.width + offset;
+      break;
+    case 'right-start':
+      top = anchor.y;
+      left = anchor.x + anchor.width + offset;
+      break;
+    case 'right-end':
+      top = anchor.y + anchor.height - contentSize.height;
+      left = anchor.x + anchor.width + offset;
+      break;
+  }
+
+  return { top, left };
+};
+
+/**
+ * Check if position fits within window bounds accounting for safe areas
+ * Position is in window coordinates (from measureInWindow)
+ */
+const fitsInViewport = (
+  position: Position,
+  contentSize: ContentSize,
+  windowSize: { width: number; height: number },
+  padding: number = 12,
+  safeAreaInsets?: SafeAreaInsets
+): boolean => {
+  const right = position.left + contentSize.width;
+  const bottom = position.top + contentSize.height;
+
+  // Calculate bounds in window coordinates
+  // Respect safe areas to avoid overlapping with system UI
+  const topBound = padding + (safeAreaInsets?.top || 0);
+  const leftBound = padding + (safeAreaInsets?.left || 0);
+  const rightBound = windowSize.width - padding - (safeAreaInsets?.right || 0);
+  const bottomBound = windowSize.height - topBound - (safeAreaInsets?.bottom || 0) - padding;
+
+  // Add a buffer to account for floating point precision and give some breathing room
+  const buffer = 2;
+
+  const fits = (
+    position.left >= leftBound &&
+    position.top >= topBound &&
+    right <= rightBound - buffer &&
+    bottom <= bottomBound - buffer
+  );
+
+  console.log(bottom, bottomBound);
+
+  if (__DEV__) {
+    console.log('[fitsInViewport]', {
+      position,
+      contentSize,
+      windowSize,
+      safeAreaInsets,
+      bounds: { topBound, leftBound, rightBound, bottomBound },
+      edges: { right, bottom },
+      fits,
+      bottomOverflow: bottom > bottomBound ? bottom - bottomBound : 0
+    });
+  }
+
+  return fits;
+};
+
+/**
+ * Calculate the best position with smart boundary detection and flipping
+ */
+export const calculateSmartPosition = (
+  anchor: AnchorMeasurements,
+  contentSize: ContentSize,
+  placement: Placement,
+  offset: number = 8,
+  matchWidth: boolean = false,
+  safeAreaInsets?: SafeAreaInsets
+): Position => {
+  // Use window dimensions - this is the actual visible content area
+  const { width: windowWidth, height: windowHeight } = Dimensions.get('window');
+  const padding = 12;
+
+  // Calculate actual usable space accounting for safe areas
+  const topBound = padding;
+  const rightBound = windowWidth - padding - (safeAreaInsets?.right || 0);
+  const bottomBound = windowHeight - padding - (safeAreaInsets?.bottom || 0);
+  const leftBound = padding + (safeAreaInsets?.left || 0);
+
+  // Try original placement
+  let position = calculatePositionForPlacement(anchor, contentSize, placement, offset);
+
+  // Check if it fits using window dimensions
+  const windowSize = { width: windowWidth, height: windowHeight };
+  const originalFits = fitsInViewport(position, contentSize, windowSize, padding, safeAreaInsets);
+
+  if (__DEV__) {
+    console.log('[calculateSmartPosition] Original placement:', placement, 'fits:', originalFits, 'position:', position);
+  }
+
+  if (originalFits) {
+    if (matchWidth) {
+      position.width = anchor.width;
+    }
+    return position;
+  }
+
+  // Try flipping to opposite side
+  const oppositePlacement = getOppositePlacement(placement);
+  let flippedPosition = calculatePositionForPlacement(anchor, contentSize, oppositePlacement, offset);
+  const flippedFits = fitsInViewport(flippedPosition, contentSize, windowSize, padding, safeAreaInsets);
+
+  if (__DEV__) {
+    console.log('[calculateSmartPosition] Flipped placement:', oppositePlacement, 'fits:', flippedFits, 'position:', flippedPosition);
+  }
+
+  if (flippedFits) {
+    if (matchWidth) {
+      flippedPosition.width = anchor.width;
+    }
+    return flippedPosition;
+  }
+
+  // Try alternative alignments for the original side
+  const alternativePlacements: Placement[] = [];
+  const basePlacement = placement.split('-')[0] as 'top' | 'bottom' | 'left' | 'right';
+
+  if (placement.includes('-')) {
+    // If we have an alignment, try other alignments on the same side
+    alternativePlacements.push(`${basePlacement}` as Placement);
+    if (!placement.endsWith('-start')) alternativePlacements.push(`${basePlacement}-start` as Placement);
+    if (!placement.endsWith('-end')) alternativePlacements.push(`${basePlacement}-end` as Placement);
+  }
+
+  // Try alternative alignments
+  for (const altPlacement of alternativePlacements) {
+    const altPosition = calculatePositionForPlacement(anchor, contentSize, altPlacement, offset);
+    if (fitsInViewport(altPosition, contentSize, windowSize, padding, safeAreaInsets)) {
+      if (matchWidth) {
+        altPosition.width = anchor.width;
+      }
+      return altPosition;
+    }
+  }
+
+  // If nothing fits perfectly, constrain to viewport bounds as fallback
+  // This handles when content is too large to fit anywhere
+  if (__DEV__) {
+    console.log('[calculateSmartPosition] Nothing fits, constraining to bounds. Original position:', position, 'bounds:', { topBound, bottomBound, leftBound, rightBound });
+  }
+
+  position.left = Math.max(leftBound, Math.min(position.left, rightBound - contentSize.width));
+  position.top = Math.max(topBound, Math.min(position.top, bottomBound - contentSize.height));
+
+  if (__DEV__) {
+    console.log('[calculateSmartPosition] Constrained position:', position);
+  }
+
+  if (matchWidth) {
+    position.width = anchor.width;
+  }
+
+  return position;
+};

package/src/utils/styleHelpers.ts

@@ -0,0 +1,48 @@
+import { Theme } from '@idealyst/theme';
+
+// Type definitions
+export type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+// Helper functions
+export function isPlainObject(value: unknown): value is Record<string, any> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.prototype.toString.call(value) === '[object Object]'
+  )
+}
+
+export function deepMerge<T extends Record<string, any>, S extends Record<string, any>>(
+  target: T,
+  source: S
+): T & S {
+  const result: Record<string, any> = { ...target }
+
+  for (const key in source) {
+    if (Object.prototype.hasOwnProperty.call(source, key)) {
+      const sourceValue = source[key]
+      const targetValue = result[key]
+
+      if (isPlainObject(targetValue) && isPlainObject(sourceValue)) {
+        result[key] = deepMerge(targetValue, sourceValue)
+      } else {
+        result[key] = sourceValue
+      }
+    }
+  }
+
+  return result as T & S
+}
+
+export function buildSizeVariants<T>(
+  theme: Theme,
+  component: string,
+  builder: (value: any) => any
+): Record<Size, any> {
+  const variants = {} as Record<Size, any>;
+  for (const size in (theme.sizes as any)[component]) {
+    variants[size as Size] = builder((theme.sizes as any)[component][size as Size]);
+  }
+  return variants;
+}

package/LLM-ACCESS-GUIDE.md

@@ -1,143 +0,0 @@
-# LLM Documentation Access Guide
-
-This guide explains exactly how LLMs can access @idealyst/components documentation in real-world scenarios.
-
-## Scenario 1: Working in a Project with the Package Installed
-
-When helping a developer who has `@idealyst/components` installed in their project:
-
-### Quick Overview
-```bash
-# Read the main documentation file
-cat node_modules/@idealyst/components/CLAUDE.md
-```
-This gives you everything in one file - all components, patterns, and usage examples.
-
-### Specific Component Details
-```bash
-# For detailed Button documentation
-cat node_modules/@idealyst/components/src/Button/README.md
-
-# For detailed Card documentation  
-cat node_modules/@idealyst/components/src/Card/README.md
-
-# And so on for each component...
-```
-
-### Component Discovery
-```bash
-# See all available components
-ls node_modules/@idealyst/components/src/*/README.md
-
-# Will show:
-# node_modules/@idealyst/components/src/Avatar/README.md
-# node_modules/@idealyst/components/src/Badge/README.md
-# node_modules/@idealyst/components/src/Button/README.md
-# ... etc
-```
-
-## Scenario 2: Repository/GitHub Access
-
-When working with the source repository or GitHub:
-
-### Main Documentation
-- `packages/components/README.md` - Complete overview with component table
-- `packages/components/CLAUDE.md` - LLM-optimized quick reference
-
-### Individual Component Docs
-- `packages/components/src/Avatar/README.md`
-- `packages/components/src/Button/README.md`
-- `packages/components/src/Card/README.md`
-- ... etc for all 11 components
-
-## Scenario 3: Package Manager Info
-
-```bash
-# View package information
-npm info @idealyst/components
-
-# View package README
-npm docs @idealyst/components
-
-# Download and examine (if needed)
-npm pack @idealyst/components
-tar -tf idealyst-components-*.tgz | grep README
-```
-
-## Scenario 4: Examples and Live Code
-
-For working examples and demonstrations:
-
-```bash
-# Import component examples
-import { ButtonExamples, CardExamples } from '@idealyst/components/examples';
-
-# Or read example source code
-cat node_modules/@idealyst/components/src/examples/ButtonExamples.tsx
-cat node_modules/@idealyst/components/src/examples/CardExamples.tsx
-```
-
-## Recommended LLM Workflow
-
-### Step 1: Quick Reference
-Start with `CLAUDE.md` for:
-- All component names and categories
-- Common usage patterns
-- Intent system explanation
-- Quick examples
-
-### Step 2: Specific Component Help
-When user asks about a specific component:
-1. Read `src/ComponentName/README.md` for complete details
-2. Use the detailed props table, examples, and best practices
-
-### Step 3: Component Discovery
-When user asks "what components are available for X":
-1. Check the component table in main README.md
-2. Use component categories (layout, form, display, etc.)
-3. Read individual component descriptions
-
-## File Locations Summary
-
-```
-@idealyst/components/
-├── README.md                    # Complete overview + component table
-├── CLAUDE.md                    # LLM quick reference (START HERE)
-├── src/
-│   ├── Avatar/README.md         # Detailed Avatar docs
-│   ├── Badge/README.md          # Detailed Badge docs  
-│   ├── Button/README.md         # Detailed Button docs
-│   ├── Card/README.md           # Detailed Card docs
-│   ├── Checkbox/README.md       # Detailed Checkbox docs
-│   ├── Divider/README.md        # Detailed Divider docs
-│   ├── Icon/README.md           # Detailed Icon docs
-│   ├── Input/README.md          # Detailed Input docs
-│   ├── Screen/README.md         # Detailed Screen docs
-│   ├── Text/README.md           # Detailed Text docs
-│   └── View/README.md           # Detailed View docs
-```
-
-## Pro Tips for LLMs
-
-1. **Always start with `CLAUDE.md`** - it has everything you need for 90% of questions
-2. **Component table in main README** - perfect for "what components are available" questions  
-3. **Individual README files** - use when user needs specific component details
-4. **Check the examples/** folder - contains working code examples for all components
-5. **Intent system is key** - primary, neutral, success, error, warning are used across all components
-
-## Quick Command Reference
-
-```bash
-# Essential reads for any LLM session
-cat CLAUDE.md                           # Complete LLM reference
-cat README.md                           # Overview + component table
-
-# Specific component help
-cat src/Button/README.md                # Button documentation
-cat src/Card/README.md                  # Card documentation
-
-# Discovery
-ls src/*/README.md                      # List all component docs
-```
-
-This approach ensures LLMs have clear, practical access to all documentation without cluttering the main component API.

package/src/ActivityIndicator/README.md

@@ -1,132 +0,0 @@
-# ActivityIndicator
-
-A cross-platform loading indicator component that displays a spinning animation to indicate loading or processing state.
-
-## Features
-
-- **Cross-platform**: Works seamlessly on both React and React Native
-- **Intent-based colors**: Uses semantic color system (primary, neutral, success, error, warning)
-- **Multiple sizes**: Supports small, medium, large, or custom numeric sizes
-- **Customizable**: Override colors and styles as needed
-- **Animation control**: Start/stop animation with `animating` prop
-- **Auto-hide**: Optionally hide when not animating
-
-## Usage
-
-```tsx
-import { ActivityIndicator } from '@idealyst/components';
-
-// Basic usage
-<ActivityIndicator />
-
-// With different sizes
-<ActivityIndicator size="small" />
-<ActivityIndicator size="medium" />
-<ActivityIndicator size="large" />
-<ActivityIndicator size={64} /> // Custom size in pixels
-
-// With different intents
-<ActivityIndicator intent="primary" />
-<ActivityIndicator intent="success" />
-<ActivityIndicator intent="error" />
-<ActivityIndicator intent="warning" />
-<ActivityIndicator intent="neutral" />
-
-// Custom color
-<ActivityIndicator color="#FF5733" />
-
-// Control animation
-<ActivityIndicator animating={isLoading} />
-
-// Don't hide when stopped
-<ActivityIndicator animating={false} hidesWhenStopped={false} />
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `animating` | `boolean` | `true` | Whether the indicator is animating (visible) |
-| `size` | `'small' \| 'medium' \| 'large' \| number` | `'medium'` | The size of the indicator |
-| `intent` | `'primary' \| 'neutral' \| 'success' \| 'error' \| 'warning'` | `'primary'` | The color intent of the indicator |
-| `color` | `string` | - | Custom color to override intent |
-| `style` | `ViewStyle` | - | Additional styles to apply to the container |
-| `testID` | `string` | - | Test identifier for testing |
-| `hidesWhenStopped` | `boolean` | `true` | Whether to hide the indicator when not animating |
-
-## Examples
-
-### Loading State
-```tsx
-const LoadingScreen = () => {
-  const [isLoading, setIsLoading] = useState(true);
-  
-  return (
-    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
-      <ActivityIndicator 
-        animating={isLoading}
-        size="large"
-        intent="primary"
-      />
-      {isLoading && <Text>Loading data...</Text>}
-    </View>
-  );
-};
-```
-
-### Button with Loading
-```tsx
-const SubmitButton = ({ onSubmit }) => {
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  
-  const handleSubmit = async () => {
-    setIsSubmitting(true);
-    await onSubmit();
-    setIsSubmitting(false);
-  };
-  
-  return (
-    <Button onPress={handleSubmit} disabled={isSubmitting}>
-      {isSubmitting ? (
-        <ActivityIndicator size="small" color="white" />
-      ) : (
-        'Submit'
-      )}
-    </Button>
-  );
-};
-```
-
-### Custom Styled Indicator
-```tsx
-<ActivityIndicator
-  size={50}
-  color="#8B5CF6"
-  style={{
-    backgroundColor: 'rgba(139, 92, 246, 0.1)',
-    padding: 20,
-    borderRadius: 10,
-  }}
-/>
-```
-
-## Platform Differences
-
-- **Web**: Uses CSS animations with a custom spinner implementation
-- **Native**: Uses React Native's built-in `ActivityIndicator` component
-- Both platforms support all the same props for consistency
-
-## Accessibility
-
-The ActivityIndicator component includes:
-- Proper ARIA roles for screen readers on web
-- Visual indication of loading state
-- Support for test IDs for testing
-
-## Best Practices
-
-1. **Always provide context**: Pair with text to explain what's loading
-2. **Use appropriate sizes**: Small for inline, large for full-screen loading
-3. **Match intent to context**: Use error intent for retry states, success for completion
-4. **Consider animation performance**: Avoid too many simultaneous indicators
-5. **Provide alternative content**: Show skeleton screens or placeholders when appropriate