@possibly6400/ui-kit 1.0.12 → 1.0.14

package/README.md

@@ -9,30 +9,36 @@ A reusable, themeable component library built with React, TypeScript, and Tailwi
 - 🎯 **Accessible**: Built with accessibility best practices
 - 📦 **Packaged**: Ready for npm distribution
 - 🧩 **Composable**: Primitive components with semantic wrappers
-- ⚡ **Lightweight**: No external dependencies except React
+- ⚡ **Lightweight**: Minimal dependencies (only clsx and tailwind-merge)
+- 🎭 **Dynamic Sizing**: Components adapt to content with minimum size constraints
 
 ## Components
 
 ### Primitive Components
 
 - **Button**: Generic visual button with variants, sizes, and states
-- **Input**: Form input field with error states
+- **Input**: Form input field with error states and dynamic sizing
 - **Checkbox**: Animated SVG checkbox with smooth checkmark animation and label support
 - **RadioButton**: Windows-style radio button with RadioGroup support for form selections
-- **Toggle**: Switch/toggle component
+- **Toggle**: Switch/toggle component with celestial sparkle effects
 - **Loader**: Animated loading spinner with rotating faces and glowing effects
 - **ThemeSwitch**: Animated dark/light mode toggle with sun/moon and stars/clouds visual effects
-- **SearchBar**: Gradient search bar input with integrated search icon
+- **SearchBar**: Gradient search bar input with integrated search icon and dynamic placeholder sizing
+- **Card**: Flexible card container with header, content, and footer sections
+- **Tooltip**: Accessible tooltip component with position control and delay support
+- **SocialLinks**: Social media links component with platform icons and tooltips
+- **ContextMenu**: Context menu component with grouped items, icons, and variants
+- **CookieConsent**: Configurable cookie consent card component with localStorage persistence
 
 ### Semantic Wrappers
 
-- **Form**: Animated form container with rotating border effect, backdrop blur, and composable form components
+- **Form**: Form container with backdrop blur and composable form components (dynamically sized)
 - **SubmitButton**: Button wrapper for form submissions with loading/success states
 
 ## Requirements
 
-- React 18.0.0 or higher
-- React DOM 18.0.0 or higher
+- React 19.2.3 or higher
+- React DOM 19.2.3 or higher
 - Node.js 16.0.0 or higher (for development)
 
 **Note:** Tailwind CSS is compiled at build time. Consumers do not need Tailwind installed or configured.
@@ -105,6 +111,12 @@ Start the preview environment to see all components:
 npm run dev
 ```
 
+The preview includes:
+- **Component Showcase**: Full demonstration of all component variants and states
+- **Landing Page**: Beautiful landing page preview showcasing all components in a cohesive design
+
+Toggle between the showcase and landing page using the button in the bottom-right corner.
+
 ### Build
 
 Build the library for distribution:
@@ -145,6 +157,7 @@ npm run lint
 
 ```tsx
 <SubmitButton
+  variant="primary" | "secondary" | "danger"
   size="sm" | "md" | "lg"
   disabled={boolean}
   onSubmit={async () => { /* submit logic */ }}
@@ -173,14 +186,23 @@ npm run lint
 
 ### SearchBar
 
+Search bar component with dynamic sizing based on placeholder text. Automatically adjusts width to fit placeholder content while maintaining minimum size constraints.
+
 ```tsx
 <SearchBar
-  placeholder="Search..."
+  size="sm" | "md" | "lg"
+  placeholder="Search for components..."
   value={string}
   onChange={function}
 />
 ```
 
+**Features:**
+- Dynamic width calculation based on placeholder text
+- Minimum width constraints per size (sm: 200px, md: 260px, lg: 320px)
+- Integrated search icon with hover effects
+- Gradient background with neumorphic design
+
 ### Checkbox
 
 Animated checkbox with smooth SVG checkmark animation. The checkmark animates when checked/unchecked using stroke-dasharray transitions.
@@ -334,9 +356,238 @@ import { Loader, Spinner } from '@possibly6400/ui-kit';
 - Inline and full container display modes
 - Optional loading text label
 
+### Card
+
+Flexible card component for displaying content with header, content, and footer sections.
+
+```tsx
+import { Card, CardHeader, CardContent, CardFooter } from '@possibly6400/ui-kit';
+
+<Card>
+  <CardHeader>
+    <h3>Card Title</h3>
+  </CardHeader>
+  <CardContent>
+    <p>Card content goes here</p>
+  </CardContent>
+  <CardFooter>
+    <Button variant="ghost" size="sm">Action</Button>
+  </CardFooter>
+</Card>
+```
+
+**Components:**
+- **Card**: Main card container
+- **CardHeader**: Header section with bottom border
+- **CardContent**: Main content area
+- **CardFooter**: Footer section with top border
+
+**Features:**
+- Theme-aware styling with CSS variables
+- Flexible layout with composable sections
+- Border separators between sections
+- Full TypeScript support
+
+### Tooltip
+
+Accessible tooltip component that displays contextual information on hover or focus.
+
+```tsx
+import { Tooltip } from '@possibly6400/ui-kit';
+
+const [tooltipOpen, setTooltipOpen] = useState(false);
+
+<Tooltip
+  open={tooltipOpen}
+  onOpenChange={setTooltipOpen}
+  content="This is a tooltip"
+  position="top" | "bottom" | "left" | "right"
+  delay={number}
+  disabled={boolean}
+>
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+**Props:**
+- `open: boolean` - Controlled open state
+- `onOpenChange?: (open: boolean) => void` - Callback when open state changes
+- `content: React.ReactNode` - Tooltip content
+- `position?: "top" | "bottom" | "left" | "right"` - Tooltip position (default: `"top"`)
+- `delay?: number` - Delay before showing tooltip in milliseconds (default: `0`)
+- `disabled?: boolean` - Disable tooltip functionality
+- `children: React.ReactElement` - Child element to attach tooltip to
+
+**Features:**
+- Accessible with ARIA attributes
+- Keyboard support (focus/blur events)
+- Position control (top, bottom, left, right)
+- Configurable delay
+- Arrow indicator pointing to trigger element
+- Theme-aware styling
+
+### SocialLinks
+
+Social media links component with platform-specific icons and tooltips.
+
+```tsx
+import { SocialLinks } from '@possibly6400/ui-kit';
+
+const links = [
+  { platform: 'github', url: 'https://github.com', label: 'GitHub' },
+  { platform: 'linkedin', url: 'https://linkedin.com' },
+  { platform: 'x', url: 'https://x.com' },
+];
+
+<SocialLinks
+  links={links}
+  orientation="vertical" | "horizontal"
+/>
+```
+
+**Props:**
+- `links: SocialLink[]` - Array of social link objects
+- `orientation?: "vertical" | "horizontal"` - Layout orientation (default: `"vertical"`)
+- `className?: string` - Additional CSS classes
+
+**Supported Platforms:**
+- LinkedIn, GitHub, Instagram, YouTube, Facebook, Spotify, Telegram, Pinterest, X (Twitter)
+
+**Features:**
+- Platform-specific SVG icons
+- Hover tooltips with platform names
+- Vertical and horizontal layouts
+- Smooth animations and transitions
+- Accessible with proper ARIA labels
+
+### ContextMenu
+
+Context menu component with grouped items, icons, and variant support.
+
+```tsx
+import { ContextMenu } from '@possibly6400/ui-kit';
+
+<ContextMenu
+  groups={[
+    {
+      id: 'actions',
+      items: [
+        {
+          id: 'edit',
+          label: 'Edit',
+          icon: <EditIcon />,
+          onClick: () => console.log('Edit'),
+        },
+        {
+          id: 'copy',
+          label: 'Copy',
+          icon: <CopyIcon />,
+          onClick: () => console.log('Copy'),
+        },
+      ],
+    },
+    {
+      id: 'danger',
+      items: [
+        {
+          id: 'delete',
+          label: 'Delete',
+          variant: 'danger',
+          icon: <DeleteIcon />,
+          onClick: () => console.log('Delete'),
+        },
+      ],
+    },
+  ]}
+  showSeparators={true}
+/>
+```
+
+**Props:**
+- `groups: ContextMenuGroupData[]` - Array of menu groups
+- `showSeparators?: boolean` - Show separators between groups (default: `true`)
+- `className?: string` - Additional CSS classes
+
+**Item Variants:**
+- `default` - Standard menu item
+- `danger` - Destructive action (red styling)
+- `accent` - Accented item (highlighted)
+
+**Features:**
+- Grouped menu items with separators
+- Icon support for each item
+- Variant styling (default, danger, accent)
+- Disabled state support
+- Theme-aware styling
+
+### CookieConsent
+
+Configurable cookie consent card component with localStorage persistence. A pure UI component that can be used inline or within a modal wrapper.
+
+```tsx
+import { CookieConsent } from '@possibly6400/ui-kit';
+
+<CookieConsent
+  title="Your privacy is important to us"
+  description="We process your personal information to measure and improve our sites and services, to assist our campaigns and to provide personalised content."
+  privacyLink="/privacy"
+  privacyLinkText="Privacy Policy"
+  acceptLabel="Accept"
+  optionsLabel="More Options"
+  onAccept={() => console.log('Accepted')}
+  onOptions={() => console.log('More options')}
+  storageKey="cookie-consent"
+  storageValue="accepted"
+  icon={cookieIcon}
+  privacyLinkTarget="_blank"
+  privacyLinkRel="noopener noreferrer"
+  className="transition-transform duration-300"
+  iconClassName=""
+  contentClassName=""
+  acceptButtonClassName=""
+  optionsButtonClassName=""
+/>
+```
+
+**Props:**
+- `title: string` - Consent card title
+- `description: string` - Consent description text
+- `privacyLink: string` - Privacy policy URL
+- `privacyLinkText: string` - Privacy policy link text
+- `acceptLabel: string` - Accept button label
+- `optionsLabel: string` - More options button label
+- `onAccept: () => void` - Callback when accept is clicked
+- `onOptions: () => void` - Callback when more options is clicked
+- `storageKey: string` - localStorage key for persisting consent
+- `storageValue: string` - Value to store when consent is accepted
+- `icon?: React.ReactNode` - Optional icon/illustration (typically a cookie icon)
+- `privacyLinkTarget?: string` - Link target attribute (e.g., "_blank")
+- `privacyLinkRel?: string` - Link rel attribute (e.g., "noopener noreferrer")
+- `className?: string` - Additional CSS classes for the card container
+- `iconClassName?: string` - Additional CSS classes for the icon wrapper
+- `contentClassName?: string` - Additional CSS classes for the content wrapper
+- `acceptButtonClassName?: string` - Additional CSS classes for the accept button
+- `optionsButtonClassName?: string` - Additional CSS classes for the options button
+
+**Features:**
+- Pure UI component - no modal/backdrop assumptions
+- localStorage persistence - automatically checks and stores consent state
+- Fully props-driven - all text, links, and behavior controlled via props
+- Optional icon support - layout adapts when icon is omitted
+- Customizable styling - all elements can be styled via className props
+- Dark mode support - theme-aware colors and styling
+- Accessible - proper semantic HTML and keyboard navigation
+- Inline or modal usage - can be embedded anywhere or wrapped in a modal
+
+**Usage Notes:**
+- Component automatically hides once consent is stored in localStorage
+- Reset consent by removing the storageKey from localStorage
+- For modal usage, wrap the component in a backdrop/overlay div
+- All styling is customizable via className props while maintaining sensible defaults
+
 ### Form
 
-Animated form container component with beautiful rotating border effect, backdrop blur, and composable form elements. Perfect for creating elegant login, signup, contact, and survey forms.
+Form container component with backdrop blur and composable form elements. Dynamically sizes based on content.
 
 ```tsx
 import { Form, FormField, FormButton, FormFooter, FormFooterLink } from '@possibly6400/ui-kit';
@@ -372,7 +623,7 @@ import { Form, FormField, FormButton, FormFooter, FormFooterLink } from '@possib
 ```
 
 **Components:**
-- **Form**: Main form container with animated border and backdrop blur
+- **Form**: Main form container with backdrop blur
 - **FormField**: Input field wrapper with optional label and error state
 - **FormButton**: Button component with primary and Google sign-in variants
 - **FormFooter**: Footer container for form links and text
@@ -386,13 +637,13 @@ import { Form, FormField, FormButton, FormFooter, FormFooterLink } from '@possib
 - `FormFooterLink`: Standard anchor HTML attributes
 
 **Features:**
-- Beautiful animated rotating border effect using conic gradient
 - Backdrop blur effect for modern glassmorphism look
 - Optional user/logo icon with animated design
 - Theme-aware colors using CSS variables
 - Composable structure - works with Checkbox, RadioButton, and other components
 - Animated footer links with hover effects
 - Customizable width and aspect ratio
+- Dynamic sizing based on content
 - Full TypeScript support
 
 ## Architecture Principles
@@ -402,20 +653,7 @@ import { Form, FormField, FormButton, FormFooter, FormFooterLink } from '@possib
 3. **No hardcoded colors**: All colors derive from CSS variables
 4. **Theme agnostic**: No OS theme detection, explicit theme control
 5. **Composable**: Components can be combined and extended
-
-## Quality Assurance
-
-A comprehensive professional audit has been conducted on all components. See [`AUDIT_REPORT.md`](./AUDIT_REPORT.md) for detailed findings, including:
-
-- Architecture and design system integrity analysis
-- Component API quality assessment
-- Accessibility (A11y) compliance review
-- Performance and maintainability evaluation
-- Visual consistency and UX rules validation
-- Styling strategy assessment
-- Improvement recommendations prioritized by severity
-
-The audit identifies critical issues, medium-priority improvements, and long-term scalability considerations to help harden the UI Kit into a production-ready design system.
+6. **Dynamic sizing**: Components adapt to content while maintaining minimum constraints
 
 ## License