@qwickapps/react-framework 1.3.2 → 1.3.4

package/src/stories/ErrorBoundary.stories.tsx

@@ -0,0 +1,159 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ErrorBoundary, withErrorBoundary } from '../components/ErrorBoundary';
+import React from 'react';
+
+// Test component that throws an error
+const ThrowError = ({ shouldThrow = false }: { shouldThrow?: boolean }) => {
+  if (shouldThrow) {
+    throw new Error('Intentional error for testing ErrorBoundary');
+  }
+  return <div>This component is working fine!</div>;
+};
+
+const meta: Meta<typeof ErrorBoundary> = {
+  title: 'Framework/ErrorBoundary',
+  component: ErrorBoundary,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'A React Error Boundary component that catches JavaScript errors and displays a user-friendly fallback UI with recovery options.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    fallback: {
+      description: 'Custom fallback UI to display when an error occurs',
+    },
+    onError: {
+      description: 'Callback function called when an error is caught',
+      action: 'onError',
+    },
+    showErrorDetails: {
+      description: 'Whether to show error details (overrides development mode detection)',
+      control: 'boolean',
+    },
+    children: {
+      description: 'Child components to wrap with error boundary',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Default story with working component
+export const Default: Story = {
+  args: {
+    children: <div>This is a working component wrapped in ErrorBoundary</div>,
+  },
+};
+
+// Story that demonstrates error handling
+export const WithError: Story = {
+  args: {
+    children: <ThrowError shouldThrow={true} />,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates ErrorBoundary catching an error and displaying the fallback UI.',
+      },
+    },
+  },
+};
+
+// Story with custom fallback UI
+export const CustomFallback: Story = {
+  args: {
+    children: <ThrowError shouldThrow={true} />,
+    fallback: (
+      <div style={{ 
+        padding: '2rem', 
+        textAlign: 'center', 
+        background: '#ffe6e6',
+        border: '2px solid #ff9999',
+        borderRadius: '8px',
+        color: '#cc0000'
+      }}>
+        <h3>🚨 Custom Error UI</h3>
+        <p>Something went wrong, but we have a custom fallback!</p>
+      </div>
+    ),
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Shows how to provide a custom fallback UI instead of the default error message.',
+      },
+    },
+  },
+};
+
+// Story showing error details in development mode
+export const WithErrorDetails: Story = {
+  args: {
+    children: <ThrowError shouldThrow={true} />,
+    showErrorDetails: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Shows error details including stack trace (normally only shown in development mode).',
+      },
+    },
+  },
+};
+
+// Story demonstrating the HOC
+const TestComponent = () => <div>Component enhanced with ErrorBoundary HOC</div>;
+const EnhancedComponent = withErrorBoundary(TestComponent);
+
+export const HigherOrderComponent: Story = {
+  render: () => <EnhancedComponent />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates using the withErrorBoundary Higher-Order Component to wrap any component with error handling.',
+      },
+    },
+  },
+};
+
+// Interactive story for testing retry functionality
+export const Interactive: Story = {
+  render: () => {
+    const [shouldThrow, setShouldThrow] = React.useState(false);
+    
+    return (
+      <div style={{ padding: '2rem' }}>
+        <button 
+          onClick={() => setShouldThrow(!shouldThrow)}
+          style={{ 
+            marginBottom: '1rem', 
+            padding: '0.5rem 1rem',
+            background: shouldThrow ? '#ff4444' : '#44aa44',
+            color: 'white',
+            border: 'none',
+            borderRadius: '4px',
+            cursor: 'pointer'
+          }}
+        >
+          {shouldThrow ? 'Fix Component' : 'Break Component'}
+        </button>
+        
+        <ErrorBoundary>
+          <ThrowError shouldThrow={shouldThrow} />
+        </ErrorBoundary>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive demo where you can break and fix the component to see ErrorBoundary in action.',
+      },
+    },
+  },
+};

package/src/types/CollapsibleLayout.ts

@@ -0,0 +1,231 @@
+/**
+ * TypeScript type definitions for CollapsibleLayout component
+ * 
+ * Provides TypeScript interfaces that extend the schema model with React-specific types
+ * and component-level functionality for the CollapsibleLayout component.
+ * 
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+
+import React, { ReactNode } from 'react';
+import type { WithDataBinding, ModelProps } from '@qwickapps/schema';
+import type { WithBaseProps } from '../hooks/useBaseProps';
+import CollapsibleLayoutModel from '../schemas/CollapsibleLayoutSchema';
+
+/**
+ * Core CollapsibleLayout properties extending the schema model
+ * 
+ * This interface combines the schema-defined properties with React-specific types
+ * and additional component functionality not captured in the schema.
+ */
+export type CollapsibleLayoutViewProps = ModelProps<CollapsibleLayoutModel> & 
+  WithBaseProps & {
+    // ========================================
+    // React Event Handlers
+    // ========================================
+    
+    /** 
+     * Callback fired when the collapsed state changes
+     * @param collapsed - The new collapsed state
+     */
+    onToggle?: (collapsed: boolean) => void;
+    
+    // ========================================
+    // React Node Overrides
+    // ========================================
+    
+    /** Lead icon as React node (overrides string-based leadIcon from schema) */
+    leadIcon?: ReactNode;
+    
+    /** Header actions as React node (overrides string-based headerActions from schema) */
+    headerActions?: ReactNode;
+    
+    /** Collapsed view content as React node (overrides string-based collapsedView from schema) */
+    collapsedView?: ReactNode;
+    
+    /** Main content as React node (overrides string-based children from schema) */
+    children?: ReactNode;
+    
+    /** Footer content as React node (overrides string-based footerView from schema) */
+    footerView?: ReactNode;
+    
+    /** Collapsed state icon as React node (overrides string-based collapsedIcon from schema) */
+    collapsedIcon?: ReactNode;
+    
+    /** Expanded state icon as React node (overrides string-based expandedIcon from schema) */
+    expandedIcon?: ReactNode;
+    
+    // ========================================
+    // Additional Component Props
+    // ========================================
+    
+    /** 
+     * Unique key for local storage persistence (when persistState is true)
+     * Defaults to component id or generates one automatically
+     */
+    storageKey?: string;
+    
+    /** 
+     * Animation duration in milliseconds 
+     * @default 300
+     */
+    animationDuration?: number;
+    
+    /**
+     * Disable all animations (useful for testing or accessibility)
+     * @default false
+     */
+    disableAnimations?: boolean;
+    
+    /**
+     * Custom CSS class for the container
+     */
+    containerClassName?: string;
+    
+    /**
+     * Custom CSS class for the header
+     */
+    headerClassName?: string;
+    
+    /**
+     * Custom CSS class for the content area
+     */
+    contentClassName?: string;
+    
+    /**
+     * Custom CSS class for the footer
+     */
+    footerClassName?: string;
+    
+    // ========================================
+    // Accessibility Props
+    // ========================================
+    
+    /** 
+     * ARIA label for the toggle button
+     * @default "Toggle content visibility"
+     */
+    toggleAriaLabel?: string;
+    
+    /**
+     * ID of element that describes the collapsible content
+     */
+    'aria-describedby'?: string;
+    
+    /**
+     * Additional ARIA attributes for the content region
+     */
+    contentAriaProps?: {
+      'aria-label'?: string;
+      'aria-labelledby'?: string;
+      role?: string;
+    };
+  };
+
+/**
+ * Complete CollapsibleLayout component props interface
+ * 
+ * This is the interface that should be used by the CollapsibleLayout component.
+ * It combines the view props with data binding capabilities.
+ */
+export interface CollapsibleLayoutProps extends CollapsibleLayoutViewProps, WithDataBinding {}
+
+/**
+ * Type guard to check if a component has CollapsibleLayout props
+ */
+export function isCollapsibleLayoutProps(props: any): props is CollapsibleLayoutProps {
+  return props && typeof props === 'object' && ('collapsed' in props || 'defaultCollapsed' in props);
+}
+
+/**
+ * Default props for CollapsibleLayout component
+ */
+export const defaultCollapsibleLayoutProps: Partial<CollapsibleLayoutProps> = {
+  // Note: collapsed is intentionally omitted so components can be uncontrolled
+  defaultCollapsed: false,
+  triggerArea: 'both',
+  animationStyle: 'slide',
+  persistState: false,
+  showDivider: true,
+  variant: 'default',
+  headerSpacing: 'comfortable',
+  contentSpacing: 'comfortable',
+  animationDuration: 300,
+  disableAnimations: false,
+  toggleAriaLabel: 'Toggle content visibility',
+};
+
+/**
+ * Animation style configurations
+ */
+export interface AnimationConfig {
+  duration: number;
+  easing: string;
+  transform?: string;
+  opacity?: [number, number];
+}
+
+export const animationConfigs: Record<NonNullable<CollapsibleLayoutProps['animationStyle']>, AnimationConfig> = {
+  fade: {
+    duration: 300,
+    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+    opacity: [0, 1],
+  },
+  slide: {
+    duration: 300,
+    easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+    transform: 'translateY(-10px)',
+  },
+  scale: {
+    duration: 200,
+    easing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+    transform: 'scale(0.95)',
+    opacity: [0, 1],
+  },
+};
+
+/**
+ * Spacing configurations
+ */
+export interface SpacingConfig {
+  padding: string;
+  gap?: string;
+}
+
+export const spacingConfigs: Record<NonNullable<CollapsibleLayoutProps['headerSpacing'] | CollapsibleLayoutProps['contentSpacing']>, SpacingConfig> = {
+  compact: {
+    padding: '8px 12px',
+    gap: '4px',
+  },
+  comfortable: {
+    padding: '16px 20px',
+    gap: '8px',
+  },
+  spacious: {
+    padding: '24px 32px', 
+    gap: '16px',
+  },
+};
+
+/**
+ * Utility type for extracting controlled vs uncontrolled props
+ */
+export type ControlledCollapsibleLayoutProps = CollapsibleLayoutProps & {
+  collapsed: boolean;
+  onToggle: (collapsed: boolean) => void;
+};
+
+export type UncontrolledCollapsibleLayoutProps = CollapsibleLayoutProps & {
+  defaultCollapsed?: boolean;
+  onToggle?: (collapsed: boolean) => void;
+};
+
+/**
+ * Hook return type for managing collapsed state
+ */
+export interface UseCollapsibleLayoutState {
+  collapsed: boolean;
+  toggle: () => void;
+  setCollapsed: (collapsed: boolean) => void;
+  isControlled: boolean;
+}

package/src/types/index.ts

@@ -93,6 +93,7 @@ export type LoadingState = 'idle' | 'loading' | 'success' | 'error';
 
 // Export all content-related types
 export * from './CacheProvider';
+export * from './CollapsibleLayout';
 export * from './ContentProxy';
 export * from './DataTypes';
 export * from './TemplateProvider';

package/dist/schemas/Builders.d.ts

@@ -1,7 +0,0 @@
-/**
- * Schema builders - Re-exported from @qwickapps/schema
- *
- * @deprecated Import directly from '@qwickapps/schema' instead
- */
-export { FieldBuilder, SchemaBuilder, ModelBuilder, createSchema, field, model, Fields } from '@qwickapps/schema';
-//# sourceMappingURL=Builders.d.ts.map

package/dist/schemas/Builders.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Builders.d.ts","sourceRoot":"","sources":["../../src/schemas/Builders.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,KAAK,EACL,KAAK,EACL,MAAM,EACP,MAAM,mBAAmB,CAAC"}

package/dist/schemas/types.d.ts

@@ -1,7 +0,0 @@
-/**
- * Schema types - Re-exported from @qwickapps/schema
- *
- * @deprecated Import directly from '@qwickapps/schema' instead
- */
-export { Schema, Model, FieldDefinition, DataType, FieldType, ValidationRules, EditorConfig } from '@qwickapps/schema';
-//# sourceMappingURL=types.d.ts.map

package/dist/schemas/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/schemas/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,MAAM,EACN,KAAK,EACL,eAAe,EACf,QAAQ,EACR,SAAS,EACT,eAAe,EACf,YAAY,EACb,MAAM,mBAAmB,CAAC"}

package/dist/types/DataBinding.d.ts

@@ -1,7 +0,0 @@
-/**
- * Data binding types - Re-exported from @qwickapps/schema
- *
- * @deprecated Import directly from '@qwickapps/schema' instead
- */
-export { DataBindingProps, DataBindingMeta, DataBindingOptions, WithDataBinding, DataBindingResult } from '@qwickapps/schema';
-//# sourceMappingURL=DataBinding.d.ts.map

package/dist/types/DataBinding.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DataBinding.d.ts","sourceRoot":"","sources":["../../src/types/DataBinding.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EAClB,MAAM,mBAAmB,CAAC"}

package/dist/types/DataProvider.d.ts

@@ -1,7 +0,0 @@
-/**
- * Data provider interface - Re-exported from @qwickapps/schema
- *
- * @deprecated Import directly from '@qwickapps/schema' instead
- */
-export { IDataProvider, DataResponse, ModelInstance, SelectOptions } from '@qwickapps/schema';
-//# sourceMappingURL=DataProvider.d.ts.map

package/dist/types/DataProvider.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DataProvider.d.ts","sourceRoot":"","sources":["../../src/types/DataProvider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}