docs: add comprehensive UI documentation with website components

docs/ui-documentation.md

@@ -0,0 +1,340 @@
+# Ink UI Documentation
+
+## Table of Contents
+1. [Introduction](#introduction)
+2. [Getting Started](#getting-started)
+3. [Components](#components)
+4. [Layout and Structure](#layout-and-structure)
+5. [Styling Guidelines](#styling-guidelines)
+6. [Interactive Elements](#interactive-elements)
+7. [Accessibility](#accessibility)
+8. [Best Practices](#best-practices)
+9. [Website UI Components](#website-ui-components)
+
+## Introduction
+
+Ink is a powerful library for building command-line interfaces (CLIs) 
+with a focus on creating beautiful and interactive terminal applications. 
+This documentation provides comprehensive guidance on using Ink's UI
+components and features effectively.
+
+## Getting Started
+
+### Installation
+```bash
+npm install ink
+```
+
+### Basic Setup
+```jsx
+import React from 'react';
+import {render, Text} from 'ink';
+
+const App = () => <Text>Hello World</Text>;
+
+render(<App />);
+```
+
+## Components
+
+### Text Component
+The fundamental building block for displaying text in Ink applications.
+
+```jsx
+import {Text} from 'ink';
+
+// Basic usage
+<Text>Regular text</Text>
+
+// Styled text
+<Text color="green">Colored text</Text>
+<Text bold>Bold text</Text>
+```
+
+### Box Component
+Used for layout and positioning of elements.
+
+```jsx
+import {Box} from 'ink';
+
+<Box margin={1} padding={2}>
+  <Text>Content inside a box</Text>
+</Box>
+```
+
+### Input Component
+Handles user input in interactive applications.
+
+```jsx
+import {useInput} from 'ink';
+
+useInput((input, key) => {
+  // Handle input here
+});
+```
+
+## Layout and Structure
+
+### Flexbox Layout
+Ink uses a flexbox-based layout system:
+
+```jsx
+<Box flexDirection="column">
+  <Box>Row 1</Box>
+  <Box>Row 2</Box>
+</Box>
+```
+
+### Spacing and Alignment
+- Margin and padding support
+- Flexible alignment options
+- Responsive layouts
+
+## Styling Guidelines
+
+### Colors
+```jsx
+// Text colors
+<Text color="red">Error message</Text>
+<Text color="green">Success message</Text>
+<Text color="#ff0000">Custom color</Text>
+
+// Background colors
+<Text backgroundColor="blue">Highlighted text</Text>
+```
+
+### Text Formatting
+```jsx
+<Text bold>Bold text</Text>
+<Text italic>Italic text</Text>
+<Text underline>Underlined text</Text>
+<Text inverse>Inverse colors</Text>
+```
+
+## Interactive Elements
+
+### Spinner
+```jsx
+import {Spinner} from 'ink';
+
+<Spinner type="dots" />
+```
+
+### Progress Bar
+```jsx
+import {Progress} from 'ink';
+
+<Progress value={0.5} />
+```
+
+### Select Input
+```jsx
+import {Select} from 'ink-select-input';
+
+const items = [
+  {label: 'Option 1', value: '1'},
+  {label: 'Option 2', value: '2'}
+];
+
+<Select items={items} onSelect={handleSelect} />
+```
+
+## Accessibility
+
+### Best Practices
+1. Use semantic components
+2. Provide clear feedback
+3. Support keyboard navigation
+4. Use appropriate color contrast
+
+### Keyboard Navigation
+```jsx
+useInput((input, key) => {
+  if (key.return) {
+    // Handle Enter key
+  }
+  if (key.escape) {
+    // Handle Escape key
+  }
+});
+```
+
+## Best Practices
+
+### Performance
+- Minimize re-renders
+- Use memoization when appropriate
+- Optimize large lists
+
+### Error Handling
+```jsx
+try {
+  // Your code
+} catch (error) {
+  <Text color="red">{error.message}</Text>
+}
+```
+
+### Testing
+```jsx
+import {render} from 'ink-testing-library';
+
+test('renders correctly', () => {
+  const {lastFrame} = render(<App />);
+  expect(lastFrame()).toContain('Expected output');
+});
+```
+
+## Website UI Components
+
+### Navigation Bar
+```jsx
+import {Box, Text} from 'ink';
+
+const Navbar = () => (
+  <Box borderStyle="single" padding={1}>
+    <Text bold>Home</Text>
+    <Text> | </Text>
+    <Text>Documentation</Text>
+    <Text> | </Text>
+    <Text>Examples</Text>
+  </Box>
+);
+```
+
+### Cards and Containers
+```jsx
+const Card = ({title, content}) => (
+  <Box 
+    flexDirection="column" 
+    borderStyle="round" 
+    padding={1}
+    marginBottom={1}
+  >
+    <Text bold>{title}</Text>
+    <Text>{content}</Text>
+  </Box>
+);
+```
+
+### Responsive Design
+Ink components automatically adjust to terminal width:
+```jsx
+<Box flexDirection="row" flexWrap="wrap">
+  <Box width={process.stdout.columns >= 80 ? '50%' : '100%'}>
+    <Text>Content adjusts based on terminal size</Text>
+  </Box>
+</Box>
+```
+
+### Forms and Input Fields
+```jsx
+import {TextInput} from 'ink-text-input';
+
+const Form = () => {
+  const [value, setValue] = useState('');
+
+  return (
+    <Box flexDirection="column">
+      <TextInput
+        value={value}
+        onChange={setValue}
+        placeholder="Enter your text"
+      />
+    </Box>
+  );
+};
+```
+
+### Modals and Dialogs
+```jsx
+const Modal = ({isVisible, onClose, children}) => {
+  if (!isVisible) return null;
+
+  return (
+    <Box 
+      flexDirection="column"
+      borderStyle="double"
+      padding={1}
+    >
+      {children}
+      <Text>Press ESC to close</Text>
+    </Box>
+  );
+};
+```
+
+### Themes and Customization
+```jsx
+const theme = {
+  primary: 'blue',
+  secondary: 'green',
+  error: 'red',
+  success: 'green',
+  warning: 'yellow'
+};
+
+const StyledButton = ({variant, children}) => (
+  <Text color={theme[variant]}>{children}</Text>
+);
+```
+
+### Loading States
+```jsx
+const LoadingState = () => (
+  <Box>
+    <Spinner />
+    <Text> Loading content...</Text>
+  </Box>
+);
+```
+
+### Error Boundaries
+```jsx
+class ErrorBoundary extends React.Component {
+  state = { hasError: false };
+
+  static getDerivedStateFromError(error) {
+    return { hasError: true };
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <Text color="red">Something went wrong!</Text>;
+    }
+    return this.props.children;
+  }
+}
+```
+
+### Animations and Transitions
+```jsx
+import {useEffect, useState} from 'react';
+import {Text, Box} from 'ink';
+
+const FadeIn = ({children}) => {
+  const [visible, setVisible] = useState(false);
+
+  useEffect(() => {
+    setVisible(true);
+  }, []);
+
+  if (!visible) return null;
+  return children;
+};
+```
+
+### SEO and Metadata
+While traditional SEO isn't applicable to CLI applications, 
+you can implement metadata for your CLI help menus:
+```jsx
+const AppMetadata = {
+  name: 'Your CLI App',
+  version: '1.0.0',
+  description: 'A beautiful CLI application',
+  commands: {
+    help: 'Display help menu',
+    version: 'Display version information'
+  }
+};
+```