@lax-wp/design-system 0.1.0 → 0.1.2

package/README.md

@@ -1,11 +1,521 @@
-# React + TypeScript + Vite
+# LAX Web Portal Design System
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+A comprehensive React + TypeScript design system built with Vite, providing reusable UI components for the LAX web portal applications. Features a complete set of form components, data display elements, and interactive controls with full TypeScript support, accessibility features, and dark mode compatibility.
 
-Currently, two official plugins are available:
+## 🎨 Features
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+- **📦 Comprehensive Component Library**: Form inputs, toggles, date ranges, currency fields, and more
+- **📚 Storybook Documentation**: Interactive component documentation with live examples
+- **🎯 TypeScript Support**: Full type safety with comprehensive interfaces and JSDoc
+- **⚡ Fast Development**: Vite + HMR for lightning-fast development experience
+- **🌙 Dark Mode**: Complete dark theme support across all components
+- **♿ Accessibility**: ARIA attributes, keyboard navigation, and screen reader support
+- **🎭 Animations**: Smooth transitions using Framer Motion
+- **🔧 ESLint Configuration**: Consistent code quality and formatting
+- **📱 Responsive Design**: Mobile-first responsive components
+- **🎪 Interactive Stories**: Comprehensive Storybook examples with playgrounds
+
+## 📚 Component Library
+
+### Form Components
+
+- **InputField**: Basic text input with validation
+- **TextField**: Enhanced text input with additional features
+- **CurrencyInputField**: Currency input with multi-currency support
+- **PercentageInputField**: Percentage input with constraints and validation
+- **DebounceInputField**: Debounced input for search and real-time scenarios
+- **DateRange**: Date range picker with validation
+- **Checkbox**: Customizable checkbox with multiple variants
+- **Toggle**: Switch component with icons and flexible positioning
+- **ColorPicker**: Color selection with multiple format support
+- **CreatableSelect**: Enhanced select with creation capabilities
+
+### Data Display
+
+- **Typography**: Consistent text styling component
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn package manager
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd lax-wp-design-system
+
+# Install dependencies
+npm install
+```
+
+### Development
+
+Start the development server with hot module replacement:
+
+```bash
+npm run dev
+```
+
+This will start the Vite development server at `http://localhost:5173`
+
+### Storybook
+
+Run Storybook for interactive component documentation:
+
+```bash
+npm run storybook
+```
+
+Storybook will be available at `http://localhost:6006`
+
+### Build
+
+Build the library for production:
+
+```bash
+npm run build
+```
+
+This generates:
+
+- `dist/` - Built library files
+- Type declarations for TypeScript support
+
+## 🔧 Local Development with Yalc
+
+[Yalc](https://github.com/wclr/yalc) is a tool for working with npm packages locally. It's perfect for testing your design system changes in other React applications before publishing.
+
+### Installing Yalc
+
+```bash
+# Install yalc globally
+npm install -g yalc
+```
+
+### Setting Up the Design System for Local Development
+
+1. **Build and publish locally:**
+
+   ```bash
+   # In the design system directory
+   npm run build
+   yalc publish
+   ```
+
+2. **Watch for changes (optional):**
+
+   ```bash
+   # Run this in a separate terminal for auto-rebuild on changes
+   npm run build --watch
+   ```
+
+### Using the Design System in Another React App
+
+1. **Add the local package:**
+
+   ```bash
+   # In your React app directory
+   yalc add @lax-wp/design-system
+   npm install
+   ```
+
+2. **Import and use components:**
+
+   ```tsx
+   // In your React app
+   import {
+     CurrencyInputField,
+     Toggle,
+     DateRange,
+     DebounceInputField,
+     PercentageInputField,
+     ColorPicker,
+     Checkbox,
+     CreatableSelectField,
+   } from "@lax-wp/design-system";
+
+   function App() {
+     const [currency, setCurrency] = useState<number | null>(null);
+     const [isEnabled, setIsEnabled] = useState(false);
+
+     return (
+       <div className="p-6">
+         <CurrencyInputField
+           id="price"
+           label="Product Price"
+           value={currency}
+           onChange={(value, currencyCode) => setCurrency(value)}
+           allowCurrencyChange
+           required
+         />
+
+         <Toggle
+           id="notifications"
+           label="Enable Notifications"
+           checked={isEnabled}
+           onChange={setIsEnabled}
+         />
+       </div>
+     );
+   }
+   ```
+
+3. **Include Tailwind CSS:**
+   The design system uses Tailwind CSS. Make sure your React app has Tailwind configured with the same classes. Add to your `tailwind.config.js`:
+
+   ```js
+   module.exports = {
+     content: [
+       "./src/**/*.{js,jsx,ts,tsx}",
+       "./node_modules/@lax-wp/design-system/dist/**/*.{js,jsx,ts,tsx}",
+     ],
+     theme: {
+       extend: {
+         colors: {
+           primary: {
+             50: "#eff6ff",
+             500: "#3b82f6",
+             600: "#2563eb",
+             // ... add your color palette
+           },
+         },
+       },
+     },
+   };
+   ```
+
+### Updating the Local Package
+
+When you make changes to the design system:
+
+1. **Rebuild and update:**
+
+   ```bash
+   # In the design system directory
+   npm run build
+   yalc push
+   ```
+
+2. **The changes will be automatically updated in your React app!**
+
+### Removing the Local Package
+
+When you're done with local development:
+
+```bash
+# In your React app directory
+yalc remove @lax-wp/design-system
+npm install @lax-wp/design-system  # Install from npm registry
+```
+
+## 📱 Usage Examples
+
+### Basic Form with Validation
+
+```tsx
+import { useState } from "react";
+import {
+  CurrencyInputField,
+  PercentageInputField,
+  DateRange,
+  Toggle,
+  type DateRangeValue,
+} from "@lax-wp/design-system";
+
+function PricingForm() {
+  const [price, setPrice] = useState<number | null>(null);
+  const [discount, setDiscount] = useState<number | null>(null);
+  const [dateRange, setDateRange] = useState<DateRangeValue>({
+    startDate: null,
+    endDate: null,
+  });
+  const [isActive, setIsActive] = useState(false);
+
+  const isValid =
+    price && price > 0 && dateRange.startDate && dateRange.endDate;
+
+  return (
+    <form className="space-y-4 max-w-md">
+      <CurrencyInputField
+        id="price"
+        label="Product Price"
+        value={price}
+        onChange={(value) => setPrice(value)}
+        currencyCode="USD"
+        allowCurrencyChange
+        required
+        message={price === null ? "Price is required" : undefined}
+        messageType={price === null ? "error" : "default"}
+      />
+
+      <PercentageInputField
+        id="discount"
+        label="Discount Rate"
+        value={discount}
+        onChange={setDiscount}
+        min={0}
+        max={50}
+        helpText="Maximum discount allowed is 50%"
+      />
+
+      <DateRange
+        id="validity"
+        label="Validity Period"
+        value={dateRange}
+        onChange={setDateRange}
+        required
+        minDate={new Date()}
+      />
+
+      <Toggle
+        id="active"
+        label="Activate Pricing"
+        checked={isActive}
+        onChange={setIsActive}
+        disabled={!isValid}
+        message={isValid ? "Ready to activate" : "Complete all fields first"}
+        messageType={isValid ? "success" : "info"}
+      />
+
+      <button
+        type="submit"
+        disabled={!isValid || !isActive}
+        className="w-full py-2 px-4 bg-blue-600 text-white rounded disabled:opacity-50"
+      >
+        Save Pricing
+      </button>
+    </form>
+  );
+}
+```
+
+### Search with Debounced Input
+
+```tsx
+import { useState } from "react";
+import { DebounceInputField } from "@lax-wp/design-system";
+
+function SearchExample() {
+  const [searchTerm, setSearchTerm] = useState("");
+  const [results, setResults] = useState<string[]>([]);
+
+  const handleSearch = async (term: string) => {
+    if (!term.trim()) {
+      setResults([]);
+      return;
+    }
+
+    // Simulate API call
+    const mockResults = await fetch(`/api/search?q=${term}`);
+    const data = await mockResults.json();
+    setResults(data);
+  };
+
+  return (
+    <div>
+      <DebounceInputField
+        id="search"
+        label="Search Products"
+        type="search"
+        value={searchTerm}
+        onChange={(value) => {
+          setSearchTerm(value);
+          handleSearch(value);
+        }}
+        debounceTimeout={300}
+        placeholder="Type to search..."
+        helpText="Results appear as you type"
+      />
+
+      <div className="mt-4">
+        {results.map((result, index) => (
+          <div key={index} className="p-2 border-b">
+            {result}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## 🎨 Theming and Customization
+
+### Using with Custom Themes
+
+```tsx
+// Add custom CSS variables for theming
+:root {
+  --primary-50: #eff6ff;
+  --primary-500: #3b82f6;
+  --primary-600: #2563eb;
+  --error-500: #ef4444;
+  --success-500: #10b981;
+}
+
+// Dark mode support
+.dark {
+  --primary-50: #1e40af;
+  --primary-500: #60a5fa;
+  --primary-600: #3b82f6;
+}
+```
+
+### Custom Component Styling
+
+```tsx
+import { CurrencyInputField } from "@lax-wp/design-system";
+
+function CustomStyledComponent() {
+  return (
+    <CurrencyInputField
+      id="custom"
+      label="Custom Styled Price"
+      wrapperClassName="bg-gradient-to-r from-blue-50 to-purple-50 p-4 rounded-lg"
+      inputClassName="border-2 border-purple-300 focus:border-purple-500"
+      labelClassName="text-purple-800 font-bold"
+      onChange={() => {}}
+    />
+  );
+}
+```
+
+## 🔍 TypeScript Support
+
+The design system is built with TypeScript and provides comprehensive type definitions:
+
+```tsx
+import type {
+  CurrencyInputFieldProps,
+  DateRangeValue,
+  ToggleProps,
+  SelectOption,
+} from "@lax-wp/design-system";
+
+// All props are fully typed
+const config: CurrencyInputFieldProps = {
+  id: "price",
+  label: "Price",
+  onChange: (value: number | null, currency: string) => {
+    // TypeScript knows the exact types here
+    console.log(`Price: ${value}, Currency: ${currency}`);
+  },
+};
+
+// Type-safe option handling
+const options: SelectOption[] = [
+  { value: "option1", label: "Option 1" },
+  { value: "option2", label: "Option 2" },
+];
+```
+
+## 🧪 Testing
+
+### Running Tests
+
+```bash
+# Run unit tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Testing with Your Application
+
+When using yalc for local development, you can test your changes immediately:
+
+1. Make changes to a component
+2. Run `npm run build && yalc push`
+3. Test in your React application
+4. Iterate quickly without publishing to npm
+
+## 📦 Publishing
+
+### Preparing for Release
+
+1. **Update version:**
+
+   ```bash
+   npm version patch  # or minor/major
+   ```
+
+2. **Build and test:**
+
+   ```bash
+   npm run build
+   npm run test
+   npm run storybook:build
+   ```
+
+3. **Publish to npm:**
+
+   ```bash
+   npm publish
+   ```
+
+### Semantic Versioning
+
+- **Patch (1.0.1)**: Bug fixes, small improvements
+- **Minor (1.1.0)**: New components, backward-compatible features
+- **Major (2.0.0)**: Breaking changes, API modifications
+
+## 🤝 Contributing
+
+### Development Workflow
+
+1. **Fork and clone** the repository
+2. **Create a feature branch:** `git checkout -b feature/new-component`
+3. **Make your changes** following the established patterns
+4. **Add tests and stories** for new components
+5. **Test locally** using yalc with your application
+6. **Submit a pull request** with clear description
+
+### Component Development Guidelines
+
+- Follow existing patterns for props and structure
+- Add comprehensive TypeScript types and JSDoc
+- Include Storybook stories with multiple examples
+- Ensure accessibility (ARIA attributes, keyboard navigation)
+- Support dark mode with proper contrast
+- Add animation support where appropriate
+- Test with screen readers and keyboard-only navigation
+
+### Code Quality
+
+```bash
+# Lint your code
+npm run lint
+
+# Fix linting issues
+npm run lint:fix
+
+# Check TypeScript
+npm run type-check
+```
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🆘 Support
+
+- **Issues**: Report bugs and request features via GitHub Issues
+- **Documentation**: Check Storybook for component examples
+- **Development**: Use yalc for local testing and development
+
+## 🔗 Related Projects
+
+- **LAX Web Portal**: Main application using this design system
+- **LAX Activity Logger**: Secondary application with shared components
+- **LAX Flow Orchestrator**: Workflow management with design system integration
 
 ## Expanding the ESLint configuration
 
@@ -13,9 +523,9 @@ If you are developing a production application, we recommend updating the config
 
 ```js
 export default tseslint.config([
-  globalIgnores(['dist']),
+  globalIgnores(["dist"]),
   {
-    files: ['**/*.{ts,tsx}'],
+    files: ["**/*.{ts,tsx}"],
     extends: [
       // Other configs...
 
@@ -30,40 +540,40 @@ export default tseslint.config([
     ],
     languageOptions: {
       parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        project: ["./tsconfig.node.json", "./tsconfig.app.json"],
         tsconfigRootDir: import.meta.dirname,
       },
       // other options...
     },
   },
-])
+]);
 ```
 
 You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
 
 ```js
 // eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+import reactX from "eslint-plugin-react-x";
+import reactDom from "eslint-plugin-react-dom";
 
 export default tseslint.config([
-  globalIgnores(['dist']),
+  globalIgnores(["dist"]),
   {
-    files: ['**/*.{ts,tsx}'],
+    files: ["**/*.{ts,tsx}"],
     extends: [
       // Other configs...
       // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
+      reactX.configs["recommended-typescript"],
       // Enable lint rules for React DOM
       reactDom.configs.recommended,
     ],
     languageOptions: {
       parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        project: ["./tsconfig.node.json", "./tsconfig.app.json"],
         tsconfigRootDir: import.meta.dirname,
       },
       // other options...
     },
   },
-])
+]);
 ```

package/dist/components/data-display/badge/Badge.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Available badge status options
+ */
+export type BadgeStatus = "default" | "primary" | "warning" | "error" | "neutral" | "success" | "info";
+/**
+ * Badge appearance variants
+ */
+export type BadgeAppearance = "filled" | "outline";
+/**
+ * Badge size variants
+ */
+export type BadgeSize = "sm" | "md" | "lg";
+/**
+ * Props for the Badge component
+ */
+export interface BadgeProps {
+    /** The badge status/color variant */
+    status?: BadgeStatus;
+    /** The text content to display */
+    children: string;
+    /** Visual appearance style */
+    appearance?: BadgeAppearance;
+    /** Size variant */
+    size?: BadgeSize;
+    /** Additional CSS classes for the wrapper */
+    className?: string;
+    /** Whether to use rounded pill shape */
+    isRounded?: boolean;
+    /** Whether to capitalize the text */
+    capitalize?: boolean;
+    /** Custom aria-label for accessibility */
+    "aria-label"?: string;
+}
+/**
+ * Badge component displays small status indicators or labels
+ *
+ * @example
+ * ```tsx
+ * <Badge status="success">Active</Badge>
+ * <Badge status="error" appearance="filled">Error</Badge>
+ * <Badge status="warning" size="sm" isRounded>Warning</Badge>
+ * ```
+ */
+export declare const Badge: import("react").ForwardRefExoticComponent<BadgeProps & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/components/data-display/banner/Banner.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Available banner status options
+ */
+export type BannerStatus = "success" | "error" | "warning" | "info" | "archived" | "canceled" | "queued" | "paused" | "awaiting_action" | "skipped" | "pending";
+/**
+ * Props for the Banner component
+ */
+export interface BannerProps {
+    /** The banner status/color variant */
+    status: BannerStatus;
+    /** The main content to display */
+    children: React.ReactNode;
+    /** Additional content to display on the right side */
+    additionalChildren?: React.ReactNode;
+    /** Component to render when expanded (for error status) */
+    ExpandedComponent?: React.ComponentType<{
+        children: React.ReactNode;
+    }>;
+    /** Whether the banner is expandable */
+    expandable?: boolean;
+    /** Custom icon to override default status icon */
+    icon?: React.ReactNode;
+    /** Additional CSS classes for the wrapper */
+    className?: string;
+    /** Callback when banner is clicked (if expandable) */
+    onClick?: () => void;
+    /** Custom aria-label for accessibility */
+    "aria-label"?: string;
+}
+/**
+ * Banner component displays important information with status-based styling
+ *
+ * @example
+ * ```tsx
+ * <Banner status="success">Operation completed successfully</Banner>
+ * <Banner status="error" expandable ExpandedComponent={ErrorDetails}>
+ *   Error occurred
+ * </Banner>
+ * ```
+ */
+export declare const Banner: import("react").ForwardRefExoticComponent<BannerProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/data-display/code-editor/CodeEditor.d.ts

@@ -0,0 +1,4 @@
+import { type FC } from 'react';
+import { type CodeEditorProps } from '../../../types';
+export type TTabKey = 'JSON' | 'Grid';
+export declare const CodeEditor: FC<CodeEditorProps>;

package/dist/components/data-display/code-editor/JsonGrid.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+export interface JsonGridProps {
+    isFullScreen: boolean;
+    allExpanded: boolean;
+    toggleAll: () => void;
+    isEditMode: boolean;
+    isDarkMode: boolean;
+    style: React.CSSProperties;
+    value: string;
+    onChange?: (value: string) => void;
+    setIsAddKeyModalOpen: (open: boolean) => void;
+    isAddKeyModalOpen: boolean;
+}
+export declare const JsonGrid: React.FC<JsonGridProps>;

package/dist/components/data-display/code-editor/Tabs.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+export interface TabsProps<T extends string> {
+    variant?: 'default' | 'switch';
+    tabs: T[];
+    activeTab: T;
+    onTabClick: (tab: T) => void;
+    size?: 'sm' | 'md' | 'lg';
+    tabIcons?: Partial<Record<T, React.ReactNode>>;
+    height?: string;
+    className?: string;
+}
+export declare const Tabs: <T extends string>({ variant, tabs, activeTab, onTabClick, size, tabIcons, height, className }: TabsProps<T>) => import("react/jsx-runtime").JSX.Element;