DA-APPS-SDK

A comprehensive React SDK containing shared components, layouts, contexts, and utilities for building applications at DataActions.

🚀 Features

• Modular Architecture: Well-organized component structure with clear separation of concerns
• TypeScript Support: Full TypeScript coverage with comprehensive type definitions
• Tailwind CSS: Utility-first styling with custom design system
• Multiple Build Formats: CommonJS and ES Modules support
• Development Tools: Hot reloading, linting, testing, and more
• React Icons: Extensive icon library integration
• Real Components: Production-ready components for common UI patterns
• SSR Support: Optimized for Server-Side Rendering environments

📦 Installation

Using npm

npm install da-apps-sdk

Using yarn

yarn add da-apps-sdk

Using yalc (for local development)

# In the SDK directory
yalc publish

# In your project directory
yalc add da-apps-sdk

🎯 Quick Start

import { Button, Input, PanelLayout, Table, ModalContextProvider, useModalContext } from "da-apps-sdk";

// Use components
function App() {
  return (
    <ModalContextProvider>
      <PanelLayout>
        <div className="p-6">
          <h1 className="text-2xl font-bold mb-4">Dashboard</h1>

          <div className="space-y-4">
            <Input name="email" label="Email Address" placeholder="Enter your email" />

            <Button label="Submit" className="bg-blue-600 hover:bg-blue-700 text-white" />

            <Table
              data={[
                { id: 1, name: "John Doe", email: "[email protected]" },
                { id: 2, name: "Jane Smith", email: "[email protected]" },
              ]}
              columns={[
                { key: "name", title: "Name" },
                { key: "email", title: "Email" },
              ]}
            />
          </div>
        </div>
      </PanelLayout>
    </ModalContextProvider>
  );
}

🔧 SSR (Server-Side Rendering) Support

The SDK is optimized for SSR environments like Next.js, Remix, and other frameworks. Here are some important considerations:

Next.js Usage

// In your Next.js app
import { Button, Input, Table } from "da-apps-sdk";

// Components work seamlessly in both client and server components
export default function Page() {
  return (
    <div>
      <Button label="Click me" />
      <Input name="test" label="Test Input" />
    </div>
  );
}

Important SSR Notes

1. React Version: The SDK requires React 18+ and is compatible with React 19
2. Peer Dependencies: React and React-DOM are peer dependencies and must be installed in your project
3. No Side Effects: The SDK is marked as sideEffects: false for optimal tree-shaking
4. External Dependencies: All React-related imports are properly externalized

Troubleshooting SSR Issues

If you encounter SSR-related errors:

1. Ensure React is installed: Make sure react and react-dom are in your project's dependencies
2. Check React version: The SDK requires React 18+ or 19+
3. Import order: Import SDK components after React is available
4. Build configuration: Ensure your bundler is configured to handle external dependencies
5. JSX Runtime: The SDK uses production JSX runtime - ensure your app doesn't override this

// ✅ Correct import order
import React from "react";
import { Button, Input } from "da-apps-sdk";

// ❌ Avoid importing SDK before React
import { Button, Input } from "da-apps-sdk";
import React from "react";

Common Error Solutions

"jsxDevRuntime.jsxDEV is not a function"

• This error occurs when development JSX runtime is used in production
• The SDK is configured to use production JSX runtime
• Ensure your app's build configuration doesn't override the SDK's JSX settings

"React is not defined"

• Ensure React is properly installed as a peer dependency
• Check that React is imported before using SDK components
• Verify your bundler is configured to handle external dependencies

📚 Documentation

Base Components

UI Components

• Button - Versatile button component with customizable styling
• Input - Form input component with validation support
• Label - Label component with icon support
• Loader - Loading spinner component
• Dropdown - Dropdown menu component
• MultiDropdown - Multi-select dropdown component
• Illustration - Illustration placeholder component

Functional Components

Data & Navigation

• Table - Data table component with sorting and actions
• Tabs - Tab navigation component
• Breadcrumbs - Breadcrumb navigation component
• List - List component with navigation support

User Interface

• ModalWrapper - Modal dialog wrapper
• PopupWrapper - Popup wrapper component
• PopUpMenu - Popup menu component
• ConfirmModal - Confirmation modal component
• Wizard - Multi-step wizard component
• Labels - Label management component
• Loading - Loading state component
• Error - Error display component

Layouts

• PanelLayout - Panel-based layout component
• ScreenLayout - Full-screen layout component

Contexts

• ModalContext - Modal state management context
• WizardContext - Wizard state management context

Hooks

• useResizeObserver - Resize observer hook for responsive components

Utilities

General Utilities

import { cn, classNames, sleep } from "da-apps-sdk";

// Combine class names with Tailwind merge
const className = cn("bg-blue-500", "bg-red-500"); // Returns 'bg-red-500'

// Simple class name combination
const classes = classNames("bg-blue-500", "text-white", false && "hidden");

// Sleep utility
await sleep(1000); // Wait for 1 second

🛠️ Development

Prerequisites

• Node.js 16+
• npm or yarn

Setup

# Clone the repository
git clone <repository-url>
cd da-apps-sdk

# Install dependencies
npm install

# Start development server
npm run dev

Available Scripts

• npm run build - Build for production
• npm run build:dev - Build for development
• npm run build:watch - Build in watch mode
• npm run dev - Development mode with hot reload
• npm run type-check - TypeScript type checking
• npm run lint - ESLint checking
• npm run lint:fix - ESLint auto-fix
• npm run test - Run tests
• npm run test:watch - Run tests in watch mode
• npm run clean - Clean build directory

Project Structure

src/
├── base/              # Base UI components
│   ├── Button.jsx     # Button component
│   ├── Input.jsx      # Input component
│   ├── Label.jsx      # Label component
│   ├── Loader.jsx     # Loading component
│   ├── Dropdown.jsx   # Dropdown component
│   ├── MultiDropdown.jsx # Multi-select dropdown
│   └── Illustration.jsx # Illustration component
├── functional/        # Functional components
│   ├── Table.jsx      # Data table
│   ├── Tabs.jsx       # Tab navigation
│   ├── Wizard.jsx     # Multi-step wizard
│   ├── ModalWrapper.jsx # Modal wrapper
│   ├── PopupWrapper.jsx # Popup wrapper
│   ├── PopUpMenu.jsx  # Popup menu
│   ├── ConfirmModal.jsx # Confirmation modal
│   ├── Labels.jsx     # Label management
│   ├── List.jsx       # List component
│   ├── Error.jsx      # Error component
│   ├── Loading.jsx    # Loading component
│   └── Breadcrumbs.jsx # Breadcrumb navigation
├── layouts/           # Layout components
│   ├── PanelLayout.jsx # Panel layout
│   └── ScreenLayout.jsx # Screen layout
├── contexts/          # React contexts
│   ├── ModalContext.jsx # Modal context
│   └── WizardContext.jsx # Wizard context
├── hooks/             # Custom React hooks
│   └── useResizeObserver.jsx # Resize observer hook
├── utils/             # Utility functions
│   └── general.util.js # General utilities
└── index.ts           # Main entry point

Building

The SDK builds to multiple formats:

• CommonJS (.cjs.js) - For Node.js and bundlers
• ES Modules (.esm.js) - For modern bundlers
• TypeScript declarations (.d.ts) - For TypeScript support
• CSS (styles.css) - For styling

Testing with yalc

# In the SDK directory
npm run build
yalc publish

# In your project directory
yalc add da-apps-sdk
npm install

🎨 Styling and CSS

The SDK includes a comprehensive CSS file with all Tailwind CSS utilities and custom component styles. To ensure proper styling, you need to import the CSS file in your application.

CSS Import

Option 1: Import in your main application file

// In your main App.jsx, index.jsx, or similar
import "da-apps-sdk/styles.css";

Option 2: Import in your CSS file

/* In your main CSS file */
@import "da-apps-sdk/styles.css";

Option 3: Import in your build configuration

// In your webpack.config.js, vite.config.js, or similar
import "da-apps-sdk/styles.css";

Tailwind CSS Integration

The SDK uses Tailwind CSS with custom design tokens. If your application also uses Tailwind CSS, you may need to configure it to avoid conflicts:

// tailwind.config.js
module.exports = {
  content: ["./src/**/*.{js,ts,jsx,tsx}", "./node_modules/da-apps-sdk/dist/**/*.{js,ts,jsx,tsx}"],
  // ... rest of your config
};

Custom Design System

The SDK includes a custom design system with:

• Primary Colors: Blue-based color palette
• Secondary Colors: Gray-based color palette
• Custom Spacing: Extended spacing scale
• Custom Typography: Extended font sizes
• Custom Shadows: Soft and medium shadow variants
• Custom Animations: Fade and slide animations

Component-Specific Classes

The SDK provides utility classes for common component patterns:

/* Button variants */
.btn-primary
.btn-secondary  
.btn-outline

/* Input styles */
.input-base

/* Card styles */
.card-base

/* Modal styles */
.modal-overlay
.modal-content

/* Dropdown styles */
.dropdown-menu

/* Tooltip styles */
.tooltip-base

/* Loading spinner */
.spinner

/* Alert styles */
.alert-success
.alert-error
.alert-warning
.alert-info;

Troubleshooting Styling Issues

Classes not applying:

1. Ensure you've imported the CSS file
2. Check that the CSS file is being loaded in your browser
3. Verify there are no CSS conflicts with your application styles
4. Check the browser's developer tools for CSS loading errors

Conflicts with existing Tailwind:

1. Configure your Tailwind to include the SDK's content paths
2. Use the cn() utility function to merge classes safely
3. Consider using CSS modules or scoped styles if conflicts persist

Missing styles in production:

1. Ensure your build process includes the CSS file
2. Check that the CSS file is being copied to your build output
3. Verify the CSS file path in your production environment

🔧 Component Examples

Using the Table Component

import { Table } from "da-apps-sdk";

const data = [
  { id: 1, name: "John Doe", email: "[email protected]", status: "Active" },
  { id: 2, name: "Jane Smith", email: "[email protected]", status: "Inactive" },
];

const columns = [
  { key: "name", title: "Name" },
  { key: "email", title: "Email" },
  {
    key: "status",
    title: "Status",
    render: (value) => (
      <span
        className={`px-2 py-1 rounded text-xs ${
          value === "Active" ? "bg-green-100 text-green-800" : "bg-red-100 text-red-800"
        }`}
      >
        {value}
      </span>
    ),
  },
];

const actions = [
  { name: "Add User", onClick: () => console.log("Add user") },
  { name: "Export", onClick: () => console.log("Export") },
];

<Table data={data} columns={columns} actions={actions} onRowClick={(row) => console.log("Row clicked:", row)} />;

Using the Modal Context

import { ModalContextProvider, useModalContext } from "da-apps-sdk";

function MyComponent() {
  const { openModal, closeModal } = useModalContext();

  const handleOpenModal = () => {
    openModal({
      title: "Confirmation",
      content: "Are you sure you want to proceed?",
      onConfirm: () => {
        console.log("Confirmed!");
        closeModal();
      },
    });
  };

  return <button onClick={handleOpenModal}>Open Modal</button>;
}

// Wrap your app with the provider
<ModalContextProvider>
  <MyComponent />
</ModalContextProvider>;

Using the Panel Layout

import { PanelLayout } from "da-apps-sdk";

function App() {
  return (
    <PanelLayout>
      <div className="p-6">
        <h1>Dashboard Content</h1>
        {/* Your app content */}
      </div>
    </PanelLayout>
  );
}

Using the Tabs Component

import { Tabs } from "da-apps-sdk";

const tabs = [
  {
    id: 1,
    label: "Users",
    value: "users",
    component: <div>Users content</div>,
  },
  {
    id: 2,
    label: "Settings",
    value: "settings",
    component: <div>Settings content</div>,
  },
];

<Tabs tabs={tabs} onTabChange={(value) => console.log("Tab changed:", value)} />;

Using the Wizard Component

import { Wizard, WizardContext } from "da-apps-sdk";

const steps = [
  {
    id: 1,
    title: "Step 1",
    component: <div>Step 1 content</div>,
  },
  {
    id: 2,
    title: "Step 2",
    component: <div>Step 2 content</div>,
  },
];

<Wizard steps={steps} />;

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Write comprehensive tests
• Use semantic commit messages
• Follow the existing code style
• Add proper documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the documentation

🔄 Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

📝 Changelog

See CHANGELOG.md for a list of changes and version history.