@b3-crow/ui-kit 0.0.23 → 0.0.25

package/docs/development.md

@@ -0,0 +1,291 @@
+# Development Guide
+
+## Getting Started
+
+### Prerequisites
+
+- [Bun](https://bun.sh) v1.3.3 or higher
+- Node.js v18 or higher (for compatibility)
+- Git
+
+### Installation
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/CROW-B3/ui-kit.git
+cd ui-kit
+bun install
+```
+
+## Project Structure
+
+```
+ui-kit/
+├── src/
+│   ├── components/          # All UI components
+│   ├── lib/                 # Utility functions
+│   ├── index.ts             # Main exports
+│   └── styles.css           # Global styles
+├── dist/                    # Compiled output
+├── docs/                    # Documentation
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Development Workflow
+
+### Building
+
+Build the library for production:
+
+```bash
+bun run build
+```
+
+Watch mode for development:
+
+```bash
+bun run build:watch
+```
+
+### Linting
+
+Run ESLint to check for code issues:
+
+```bash
+bun run lint
+```
+
+Auto-fix linting issues:
+
+```bash
+bun run lint:fix
+```
+
+### Formatting
+
+Format code with Prettier:
+
+```bash
+bun run format
+```
+
+### Pre-commit Hooks
+
+The project uses Husky for Git hooks:
+
+- **Pre-commit**: Runs lint-staged to lint and format changed files
+- **Commit-msg**: Validates commit messages using conventional commits
+
+Hooks are automatically installed after running `bun install`.
+
+## Code Standards
+
+### TypeScript
+
+- All components must be fully typed
+- Export component prop types
+- Use strict TypeScript configuration
+- No `any` types unless absolutely necessary
+
+### Styling
+
+- Use Tailwind CSS utility classes
+- Follow dark theme design system
+- Use consistent spacing and sizing
+- Prefer composition over configuration
+
+### Component Structure
+
+```tsx
+import type { ComponentProps } from 'react';
+
+export interface YourComponentProps {
+  // Props interface
+  required: string;
+  optional?: number;
+}
+
+export function YourComponent({ required, optional }: YourComponentProps) {
+  // Component implementation
+  return <div>{required}</div>;
+}
+```
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new component
+fix: resolve animation bug
+docs: update README
+chore: bump dependencies
+```
+
+Types:
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting)
+- `refactor`: Code refactoring
+- `test`: Adding/updating tests
+- `chore`: Maintenance tasks
+
+## Testing
+
+### Manual Testing
+
+Link the package locally in a test project:
+
+```json
+{
+  "dependencies": {
+    "@b3-crow/ui-kit": "file:../ui-kit"
+  }
+}
+```
+
+For Next.js projects, add to `next.config.ts`:
+
+```ts
+const nextConfig = {
+  transpilePackages: ['@b3-crow/ui-kit'],
+};
+```
+
+### Visual Testing
+
+Test components in different scenarios:
+
+- Dark backgrounds
+- Light backgrounds
+- Different viewport sizes
+- Animation triggers
+- Scroll behavior
+
+## Publishing
+
+### Version Bump
+
+Update version in `package.json`:
+
+```json
+{
+  "version": "0.0.25"
+}
+```
+
+### Build and Publish
+
+```bash
+# Build the library
+bun run build
+
+# Publish to npm
+npm publish
+```
+
+### Automated Publishing
+
+The project uses GitHub Actions for automated publishing:
+
+- Pushes to `main` trigger automatic version bumps
+- Releases are created automatically
+- Package is published to npm registry
+
+## Contributing
+
+### Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes
+4. Commit using conventional commits
+5. Push to your fork
+6. Open a pull request
+
+### Code Review
+
+- All PRs require review before merging
+- Ensure CI passes (linting, building)
+- Update documentation if needed
+- Add examples for new components
+
+## File Checklist
+
+When adding a new component:
+
+- [ ] Create component in `src/components/`
+- [ ] Export from `src/index.ts`
+- [ ] Add TypeScript types
+- [ ] Document in `docs/components.md`
+- [ ] Add examples in `docs/examples.md`
+- [ ] Test locally with a consumer project
+- [ ] Update version in `package.json`
+
+## Troubleshooting
+
+### Build Errors
+
+**TypeScript errors:**
+
+```bash
+# Check TypeScript configuration
+cat tsconfig.json
+
+# Clean and rebuild
+rm -rf dist
+bun run build
+```
+
+**Missing dependencies:**
+
+```bash
+# Clean install
+rm -rf node_modules bun.lock
+bun install
+```
+
+### Import Errors
+
+**Cannot resolve module:**
+
+- Ensure component is exported in `src/index.ts`
+- Check `package.json` exports field
+- Verify build output in `dist/`
+
+**Type errors in consumer:**
+
+- Ensure `.d.ts` files are generated
+- Check `types` field in `package.json`
+- Rebuild the library
+
+### Next.js Integration
+
+**Module not found:**
+
+- Add package to `transpilePackages` in `next.config.ts`
+- Clear Next.js cache: `rm -rf .next`
+- Reinstall dependencies
+
+**Tailwind classes not working:**
+
+- Ensure consumer project has Tailwind configured
+- Check PostCSS configuration
+- Verify Tailwind v4 is installed
+
+## Resources
+
+- [Bun Documentation](https://bun.sh/docs)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+- [Tailwind CSS v4](https://tailwindcss.com/docs)
+- [Framer Motion](https://www.framer.com/motion/)
+- [Conventional Commits](https://www.conventionalcommits.org/)
+
+## License
+
+MIT License - see [LICENSE](../LICENSE) file for details.

package/docs/examples.md

@@ -0,0 +1,333 @@
+# Usage Examples
+
+## Complete Coming Soon Page
+
+Here's a complete example of a Coming Soon page using all hero components:
+
+```tsx
+import {
+  AnimatedBackground,
+  HeroText,
+  Logo,
+  TypewriterText,
+  Subtitle,
+} from '@b3-crow/ui-kit';
+
+function App() {
+  return (
+    <>
+      {/* Hero Section - must have position: relative and min-height */}
+      <section
+        style={{
+          position: 'relative',
+          minHeight: '100vh',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'center',
+          alignItems: 'center',
+        }}
+      >
+        <AnimatedBackground />
+        <Logo src="/your-logo.png" alt="Your Logo" />
+        <HeroText text="Your Brand" />
+        <TypewriterText text="COMING SOON" />
+        <Subtitle>
+          Your subtitle text here
+          <br />
+          Can be multi-line with custom formatting
+        </Subtitle>
+      </section>
+
+      {/* Other sections - add your own background */}
+      <section
+        style={{ background: 'white', padding: '4rem 2rem', minHeight: '50vh' }}
+      >
+        <h2>Your Content Here</h2>
+        <p>Additional sections will scroll normally</p>
+      </section>
+    </>
+  );
+}
+```
+
+**Important:** The parent container of `AnimatedBackground` must have `position: relative` to properly contain the absolutely positioned background. Use `minHeight: '100vh'` for full-screen hero sections.
+
+---
+
+## Button Examples
+
+```tsx
+import { Button } from '@b3-crow/ui-kit'
+
+// Outline button (default)
+<Button variant="outline">Try Now</Button>
+
+// Solid button
+<Button variant="solid">Get Started</Button>
+
+// Button as link
+<Button href="/docs">View Docs</Button>
+
+// Button with click handler
+<Button onClick={() => console.log('clicked')}>Click Me</Button>
+
+// Button without arrow
+<Button showArrow={false}>No Arrow</Button>
+```
+
+---
+
+## Card Examples
+
+```tsx
+import { Card, Button } from '@b3-crow/ui-kit'
+import { FiCode, FiBook } from 'react-icons/fi'
+
+// Feature card
+<Card
+  title="Feature Title"
+  description="Feature description text goes here"
+  icon={<FiCode />}
+  index={0}
+  layout="feature"
+  button={<Button variant="outline">Try Now</Button>}
+/>
+
+// Documentation card with center alignment
+<Card
+  title="Documentation"
+  description="Read our comprehensive guides"
+  icon={<FiBook />}
+  index={1}
+  layout="documentation"
+  contentAlign="center"
+  button={<Button href="/docs">View Docs</Button>}
+/>
+
+// Simple card without button
+<Card
+  title="Simple Card"
+  description="Just text, no button needed"
+  icon={<FiCode />}
+/>
+```
+
+---
+
+## Globe Examples
+
+```tsx
+import { Globe } from '@b3-crow/ui-kit'
+import { BsGlobe2, BsDatabase } from 'react-icons/bs'
+
+// Default globe with preset points
+<Globe size={500} />
+
+// Custom globe with custom data points
+<Globe
+  size={600}
+  points={[
+    {
+      label: 'Data Source',
+      icon: <BsGlobe2 />,
+      position: { x: 50, y: 30 }
+    },
+    {
+      label: 'Database',
+      icon: <BsDatabase />,
+      position: { x: -30, y: -20 }
+    }
+  ]}
+/>
+```
+
+---
+
+## GradientBackground Examples
+
+```tsx
+import { GradientBackground } from '@b3-crow/ui-kit'
+
+// Top gradient (default)
+<section style={{ position: 'relative' }}>
+  <GradientBackground position="top" />
+  <div>Your content here</div>
+</section>
+
+// Bottom gradient with custom height
+<section style={{ position: 'relative' }}>
+  <GradientBackground position="bottom" height="50vh" />
+  <div>Your content here</div>
+</section>
+
+// Custom colors
+<GradientBackground
+  position="top"
+  colors={{
+    start: 'rgba(100, 50, 150, 0.9)',
+    middle1: 'rgba(80, 40, 120, 0.7)',
+    middle2: 'rgba(60, 30, 100, 0.6)',
+    middle3: 'rgba(40, 20, 80, 0.4)',
+  }}
+  blur="200px"
+/>
+```
+
+---
+
+## InputField Examples
+
+```tsx
+import { InputField } from '@b3-crow/ui-kit'
+import { useState } from 'react'
+
+// Default input with submit button
+<InputField
+  placeholder="Ask CROW Anything..."
+  onSubmit={(value) => console.log('Submitted:', value)}
+/>
+
+// Controlled input
+function ControlledExample() {
+  const [inputValue, setInputValue] = useState('')
+
+  return (
+    <InputField
+      value={inputValue}
+      onChange={(value) => setInputValue(value)}
+      onSubmit={(value) => {
+        console.log('Submitted:', value)
+        setInputValue('')
+      }}
+    />
+  )
+}
+
+// Different sizes and variants
+<InputField size="sm" variant="transparent" placeholder="Small input" />
+<InputField size="md" variant="filled" placeholder="Medium filled" />
+<InputField size="lg" variant="transparent" placeholder="Large input" />
+
+// Without button
+<InputField showButton={false} placeholder="No submit button" />
+
+// Button on left
+<InputField buttonPosition="left" placeholder="Button on left" />
+```
+
+---
+
+## SectionLabel Examples
+
+```tsx
+import { SectionLabel } from '@b3-crow/ui-kit'
+
+// Animated label
+<SectionLabel label="FEATURES" className="mb-16" />
+
+// Static label (no animation)
+<SectionLabel label="ABOUT" animate={false} />
+
+// With custom styling
+<SectionLabel label="TEAM" className="mb-8 opacity-80" />
+```
+
+---
+
+## Full Page Example
+
+Here's a complete landing page example using multiple components:
+
+```tsx
+import {
+  AnimatedBackground,
+  HeroText,
+  Logo,
+  TypewriterText,
+  Subtitle,
+  SectionLabel,
+  Card,
+  Button,
+  Globe,
+  InputField,
+} from '@b3-crow/ui-kit';
+import { FiCode, FiBook, FiZap } from 'react-icons/fi';
+
+export default function LandingPage() {
+  return (
+    <div className="min-h-screen bg-black text-white">
+      {/* Hero Section */}
+      <section className="relative flex min-h-screen flex-col items-center justify-center">
+        <AnimatedBackground />
+        <Logo src="/logo.png" alt="CROW Logo" />
+        <HeroText text="CROW-B3" />
+        <TypewriterText text="COMING SOON" />
+        <Subtitle>
+          The future of development is here
+          <br />
+          Built for modern web applications
+        </Subtitle>
+      </section>
+
+      {/* Features Section */}
+      <section className="relative px-8 py-24">
+        <SectionLabel label="FEATURES" className="mb-16" />
+        <div className="mx-auto grid max-w-6xl gap-8 md:grid-cols-3">
+          <Card
+            title="Fast Development"
+            description="Build faster with pre-built components"
+            icon={<FiZap />}
+            layout="feature"
+            button={<Button variant="outline">Learn More</Button>}
+          />
+          <Card
+            title="Documentation"
+            description="Comprehensive guides and examples"
+            icon={<FiBook />}
+            layout="feature"
+            button={<Button href="/docs">View Docs</Button>}
+          />
+          <Card
+            title="Open Source"
+            description="Free and open source forever"
+            icon={<FiCode />}
+            layout="feature"
+            button={<Button href="/github">GitHub</Button>}
+          />
+        </div>
+      </section>
+
+      {/* Globe Section */}
+      <section className="relative flex items-center justify-center py-24">
+        <Globe size={600} />
+      </section>
+
+      {/* CTA Section */}
+      <section className="relative px-8 py-24 text-center">
+        <h2 className="mb-8 text-4xl font-bold">Get Early Access</h2>
+        <div className="mx-auto max-w-md">
+          <InputField
+            placeholder="Enter your email..."
+            size="lg"
+            onSubmit={email => console.log('Email:', email)}
+          />
+        </div>
+      </section>
+    </div>
+  );
+}
+```
+
+---
+
+## Important Notes
+
+1. **Scrolling Requirements**: The parent container of `AnimatedBackground` MUST have `position: relative` and a defined height (e.g., `minHeight: '100vh'`) to enable proper scrolling
+
+2. **Tailwind CSS**: Most components use Tailwind CSS classes, ensure Tailwind is configured in your project
+
+3. **Dark Theme**: Components are designed for dark backgrounds, using white text with opacity variants
+
+4. **Animations**: All animated components use Framer Motion with scroll-triggered animations
+
+5. **TypeScript**: All components are fully typed with exported TypeScript interfaces

package/docs/setup.md

@@ -0,0 +1,73 @@
+# Setup Guide
+
+## Installation
+
+Install the UI kit using your preferred package manager:
+
+```bash
+bun add @b3-crow/ui-kit
+```
+
+## Local Development
+
+For local development, you can link the package directly:
+
+```json
+{
+  "dependencies": {
+    "@b3-crow/ui-kit": "file:../ui-kit"
+  }
+}
+```
+
+## Peer Dependencies
+
+Install the required peer dependencies:
+
+```bash
+bun add react react-dom framer-motion react-icons cobe
+```
+
+### Required Versions
+
+- `react`: ^19.2.0
+- `react-dom`: ^19.2.0
+- `framer-motion`: Latest
+- `react-icons`: Latest
+- `cobe`: Latest
+
+## Tailwind CSS Configuration
+
+Most components use Tailwind CSS classes. Ensure Tailwind v4 is configured in your project:
+
+```bash
+bun add -D tailwindcss @tailwindcss/postcss
+```
+
+### PostCSS Configuration
+
+Create or update `postcss.config.mjs`:
+
+```js
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+### Next.js Configuration
+
+If using with Next.js and local packages, add to `next.config.ts`:
+
+```ts
+const nextConfig = {
+  transpilePackages: ['@b3-crow/ui-kit'],
+};
+
+export default nextConfig;
+```
+
+## Dark Theme
+
+All components are designed for dark backgrounds with white text and opacity variants. Ensure your app has a dark theme configured.