corestack-ui 0.1.0 → 0.2.0

package/README.md

@@ -1,18 +1,307 @@
-# Corestack UI
+# corestack-ui
 
-Minimal, production-ready React + TypeScript component library scaffold.
+A minimal, production-ready React + TypeScript component library. Built with **Tailwind CSS**, **tsup**, and modern tooling for seamless integration into your projects.
 
-Build
+## Features
+
+- ✅ **React 17+ Compatible** — Supports React 17, 18, and 19
+- ✅ **TypeScript First** — Fully typed components with JSDoc support
+- ✅ **Tailwind CSS Ready** — All components styled with Tailwind utilities
+- ✅ **Tree-Shakeable** — Optimized for bundle size with ESM and CommonJS exports
+- ✅ **CSS Module Support** — Optional scoped styles for component-specific styling
+- ✅ **Zero Dependencies** — Only peers React and Tailwind CSS
+- ✅ **Headless & Composable** — Flexible component APIs, accept custom classNames
+
+## Installation
+
+### Via npm
+
+```bash
+npm install corestack-ui
+```
+
+### Via yarn
+
+```bash
+yarn add corestack-ui
+```
+
+### Via pnpm
+
+```bash
+pnpm add corestack-ui
+```
+
+### Peer Dependencies
+
+Make sure you have the following installed:
+
+```bash
+npm install react react-dom tailwindcss
+```
+
+## Quick Start
+
+### 1. Configure Tailwind CSS
+
+Ensure your Tailwind config scans the library's built files:
+
+```typescript
+// tailwind.config.ts
+import type { Config } from "tailwindcss";
+
+const config: Config = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./node_modules/corestack-ui/**/*.{js,mjs}",
+  ],
+};
+
+export default config;
+```
+
+### 2. Import Styles (Optional)
+
+If you're using component-specific CSS:
+
+```typescript
+import "corestack-ui/styles.css";
+```
+
+### 3. Use Components
+
+```tsx
+import { Button } from "corestack-ui";
+
+export default function App() {
+  return (
+    <Button 
+      variant="primary" 
+      size="md"
+      onClick={() => alert("Clicked!")}
+    >
+      Click Me
+    </Button>
+  );
+}
+```
+
+## Components
+
+### Button
+
+The `Button` component is a flexible, accessible button with optional ripple effect and loading state.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"primary" \| "secondary" \| "ghost"` | `"primary"` | Button variant style |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Button size |
+| `isLoading` | `boolean` | `false` | Show loading spinner |
+| `disableRipple` | `boolean` | `false` | Disable ripple effect on click |
+| `className` | `string` | `undefined` | Additional Tailwind classes to merge |
+| ...rest | `HTMLButtonElement` props | — | Standard HTML button attributes |
+
+#### Example
+
+```tsx
+import { Button } from "corestack-ui";
+import { useState } from "react";
+
+export default function Demo() {
+  const [loading, setLoading] = useState(false);
+
+  const handleClick = async () => {
+    setLoading(true);
+    // Perform action
+    setLoading(false);
+  };
+
+  return (
+    <div className="space-y-4">
+      <Button variant="primary" size="lg">
+        Primary Large
+      </Button>
+
+      <Button 
+        variant="secondary" 
+        size="md"
+        isLoading={loading}
+        onClick={handleClick}
+      >
+        Submit
+      </Button>
+
+      <Button 
+        variant="ghost" 
+        className="text-blue-600 hover:bg-blue-50"
+      >
+        Custom Styling
+      </Button>
+
+      <Button disabled>
+        Disabled
+      </Button>
+    </div>
+  );
+}
+```
+
+## Build Instructions
+
+### Develop with Watch Mode
+
+```bash
+npm run dev
+```
+
+This will rebuild the library whenever you modify source files.
+
+### Production Build
 
 ```bash
-npm install --save-dev tsup typescript
 npm run build
 ```
 
-Usage
+This command:
+1. Compiles TypeScript to JavaScript
+2. Generates type definitions (`.d.ts`)
+3. Creates both ESM and CommonJS outputs
+4. Copies CSS files to `dist/`
+
+### Clean Build
+
+```bash
+npm run clean && npm run build
+```
+
+## Project Structure
 
-Import from package to enable tree-shaking:
+```
+corestack-ui/
+├── src/
+│   ├── components/
+│   │   ├── Button/
+│   │   │   ├── Button.tsx
+│   │   │   ├── Button.types.ts
+│   │   │   ├── Button.module.css
+│   │   │   └── index.ts
+│   │   └── index.ts
+│   ├── utils/
+│   │   ├── cn.ts              # className merger utility
+│   │   └── index.ts
+│   ├── styles/
+│   │   ├── styles.css         # Global component styles
+│   │   └── index.ts
+│   ├── types/
+│   ├── providers/
+│   └── index.ts               # Main entry point
+├── dist/                       # Built output (ESM + CJS)
+├── tsup.config.ts             # Build configuration
+├── tailwind.config.ts         # Tailwind config (for dev)
+├── tsconfig.json
+└── package.json
+```
+
+## Usage with Custom Tailwind Styling
 
-```js
-import { Button } from 'corestack-ui'
+All components accept a `className` prop to merge custom Tailwind utilities:
+
+```tsx
+import { Button } from "corestack-ui";
+
+export function CustomButton() {
+  return (
+    <Button 
+      className="bg-gradient-to-r from-purple-500 to-pink-500 shadow-lg"
+    >
+      Gradient Button
+    </Button>
+  );
+}
 ```
+
+The `cn()` utility merges classes intelligently, preventing conflicts and allowing overrides.
+
+## Exports
+
+### Named Exports
+
+```tsx
+// Components
+import { Button, Autocomplete } from "corestack-ui";
+
+// Utilities
+import { cn } from "corestack-ui";
+
+// Types
+import type { ButtonProps } from "corestack-ui";
+
+// Styles
+import "corestack-ui/styles.css";
+```
+
+## TypeScript Support
+
+All components ship with full TypeScript support. Type definitions are included in the package:
+
+```tsx
+import type { ButtonProps } from "corestack-ui";
+
+const buttonProps: ButtonProps = {
+  variant: "primary",
+  size: "lg",
+  isLoading: false,
+};
+```
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Performance
+
+- **Tree-shakeable**: Only import what you use
+- **No runtime CSS-in-JS**: Styles are static Tailwind classes
+- **Minimal bundle size**: ~10 KB gzipped (excluding React)
+- **Zero dependencies**: Only React and Tailwind as peer dependencies
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-component`)
+3. Commit your changes (`git commit -m "Add amazing component"`)
+4. Push to the branch (`git push origin feature/amazing-component`)
+5. Open a Pull Request
+
+## License
+
+MIT © 2024 — [ProNabowy](https://github.com/ProNabowy)
+
+## Author
+
+**ProNabowy**
+
+- GitHub: [@ProNabowy](https://github.com/ProNabowy)
+- NPM: [corestack-ui](https://www.npmjs.com/package/corestack-ui)
+
+## Repository
+
+[github.com/ProNabowy/corestack-ui](https://github.com/ProNabowy/corestack-ui)
+
+## Changelog
+
+### v0.2.0 (Initial Release)
+
+- Initial release with Button component
+- Tailwind CSS integration
+- TypeScript support
+- ESM + CommonJS builds
+- CSS Module support

package/dist/index.css

@@ -0,0 +1,20 @@
+button:has(span.ripple) {
+	overflow: hidden;
+	position: relative;
+}
+
+span.ripple {
+	position: absolute !important;
+	border-radius: 50%;
+	transform: scale(0);
+	animation: ripple 600ms linear;
+	background-color: rgba(255, 255, 255, 0.199);
+	z-index: 100;
+}
+
+@keyframes ripple {
+	to {
+		transform: scale(4);
+		opacity: 0;
+	}
+}

package/dist/index.d.mts

@@ -1,40 +1,225 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
+import React__default from 'react';
 
-type ButtonVariant = 'primary' | 'secondary' | 'ghost';
-type ButtonSize = 'sm' | 'md' | 'lg';
+type AutocompleteChangeReason = "selectOption" | "removeOption" | "clear" | "blur";
+interface AutocompleteRenderOptionState {
+    selected: boolean;
+    index: number;
+}
+interface RenderInputParams {
+    ref: React.Ref<HTMLInputElement>;
+    value: string;
+    placeholder?: string;
+    disabled?: boolean;
+    onChange: React.ChangeEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onKeyDown: React.KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onFocus: React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onBlur: React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    role: string;
+    "aria-autocomplete": "list";
+    "aria-controls"?: string;
+    "aria-expanded": boolean;
+    "aria-activedescendant"?: string;
+    autoComplete?: string;
+    InputProps: {
+        startAdornment?: React.ReactNode;
+        endAdornment?: React.ReactNode;
+        className?: string;
+    };
+}
+interface BaseAutocompleteProps<T> {
+    options: T[];
+    getOptionLabel: (option: T) => string;
+    isOptionEqualToValue?: (option: T, value: T) => boolean;
+    renderInput: (params: RenderInputParams) => React.ReactNode;
+    renderOption?: (props: React.HTMLAttributes<HTMLLIElement>, option: T, state: AutocompleteRenderOptionState) => React.ReactNode;
+    loading?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    className?: string;
+    /** Text to show when there are no options and not loading */
+    emptyText?: string;
+}
+type NativeInputProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange" | "value" | "defaultValue">;
+interface SingleAutocompleteProps<T> extends BaseAutocompleteProps<T>, NativeInputProps {
+    multiple?: false;
+    value?: T | null;
+    defaultValue?: T | null;
+    disableCloseOnSelect?: boolean;
+    onChange?: (event: React.SyntheticEvent, value: T | null, reason: AutocompleteChangeReason) => void;
+}
+interface MultipleAutocompleteProps<T> extends BaseAutocompleteProps<T>, NativeInputProps {
+    multiple: true;
+    value?: T[];
+    defaultValue?: T[];
+    disableCloseOnSelect?: boolean;
+    onChange?: (event: React.SyntheticEvent, value: T[], reason: AutocompleteChangeReason) => void;
+}
+type AutocompleteProps<T> = SingleAutocompleteProps<T> | MultipleAutocompleteProps<T>;
+
+declare function Autocomplete<T>(props: AutocompleteProps<T>): react_jsx_runtime.JSX.Element;
+
+type ButtonVariant = "primary" | "secondary" | "ghost";
+type ButtonSize = "sm" | "md" | "lg";
 interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: ButtonVariant;
     size?: ButtonSize;
+    disableRipple?: boolean;
+    isLoading?: boolean;
 }
 
-declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+declare function Button({ children, disableRipple, isLoading, className, onClick, ...props }: ButtonProps): react_jsx_runtime.JSX.Element;
 
-interface AutocompleteOption {
-    label: string;
-    value: string;
-}
-interface AutocompleteProps {
-    options: AutocompleteOption[];
-    value?: string;
-    onChange?: (value?: string) => void;
+declare const TextField: React__default.ForwardRefExoticComponent<{
+    value?: string | number | readonly string[];
+    defaultValue?: string | number | readonly string[];
+    onChange?: React__default.ChangeEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onBlur?: React__default.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+    onFocus?: React__default.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
     placeholder?: string;
-    renderItem?: (option: AutocompleteOption) => React.ReactNode;
-}
-
-declare const Autocomplete: React.FC<AutocompleteProps>;
+    label?: string;
+    helperText?: string | false | undefined;
+    error?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    multiline?: boolean;
+    rows?: number;
+    type?: string;
+    name?: string;
+    id?: string;
+    fullWidth?: boolean;
+    size?: "small" | "medium";
+    variant?: "outlined" | "filled" | "standard";
+    InputProps?: {
+        startAdornment?: React__default.ReactNode;
+        endAdornment?: React__default.ReactNode;
+        inputComponent?: React__default.ElementType;
+        className?: string;
+    };
+    className?: string;
+} & Omit<React__default.InputHTMLAttributes<HTMLInputElement> & React__default.TextareaHTMLAttributes<HTMLTextAreaElement>, "size" | "disabled" | "name" | "type" | "value" | "defaultValue" | "id" | "onFocus" | "onBlur" | "onChange" | "placeholder" | "required"> & React__default.RefAttributes<HTMLInputElement | HTMLTextAreaElement>>;
 
-declare function useAutocomplete(options: AutocompleteOption[]): {
-    readonly input: string;
-    readonly setInput: React.Dispatch<React.SetStateAction<string>>;
-    readonly filtered: AutocompleteOption[];
+declare const defaultTheme: {
+    colors: {
+        primary: string;
+        secondary: string;
+        success: string;
+        danger: string;
+        warning: string;
+        background: string;
+        surface: string;
+        border: string;
+        textPrimary: string;
+        textSecondary: string;
+    };
+    fonts: {
+        body: string;
+        heading: string;
+        monospace: string;
+        size: {
+            sm: string;
+            md: string;
+            lg: string;
+            xl: string;
+        };
+        weight: {
+            regular: number;
+            medium: number;
+            bold: number;
+        };
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
+};
+declare const ThemeProvider: ({ theme, children, }: {
+    theme?: Partial<typeof defaultTheme>;
+    children: React__default.ReactNode;
+}) => react_jsx_runtime.JSX.Element;
+declare const useTheme: () => {
+    colors: {
+        primary: string;
+        secondary: string;
+        success: string;
+        danger: string;
+        warning: string;
+        background: string;
+        surface: string;
+        border: string;
+        textPrimary: string;
+        textSecondary: string;
+    };
+    fonts: {
+        body: string;
+        heading: string;
+        monospace: string;
+        size: {
+            sm: string;
+            md: string;
+            lg: string;
+            xl: string;
+        };
+        weight: {
+            regular: number;
+            medium: number;
+            bold: number;
+        };
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
 };
-
-declare const cn: (...parts: Array<string | false | null | undefined>) => string;
 
 declare const tokens: {
     colors: {
         primary: string;
+        secondary: string;
+        success: string;
+        danger: string;
+        warning: string;
+        background: string;
+        surface: string;
+        border: string;
+        textPrimary: string;
+        textSecondary: string;
+    };
+    fonts: {
+        body: string;
+        heading: string;
+        monospace: string;
+        size: {
+            sm: string;
+            md: string;
+            lg: string;
+            xl: string;
+        };
+        weight: {
+            regular: number;
+            medium: number;
+            bold: number;
+        };
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
     };
 };
 
-export { Autocomplete, type AutocompleteOption, type AutocompleteProps, Button, type ButtonProps, cn, tokens, useAutocomplete };
+type ClassValue = string | false | null | undefined;
+declare const cn: (...parts: ClassValue[]) => string;
+
+declare const cssFile = "./styles.css";
+
+export { Autocomplete, Button, type ButtonProps, type ClassValue, TextField, ThemeProvider, cn, cssFile, tokens, useTheme };