@placesapp/appy-ui 0.0.1

package/README.md

@@ -0,0 +1,242 @@
+# appy-ui
+
+A React component library with iOS Liquid Glass and Material 3 design system support. Built with Tailwind CSS 4, supporting automatic platform detection and adaptive styling.
+
+## Installation
+
+```bash
+npm install appy-ui
+```
+
+### Peer Dependencies
+
+Make sure you have these peer dependencies installed:
+
+```bash
+npm install react react-dom tailwindcss
+```
+
+### Optional Peer Dependencies
+
+Some components require additional packages:
+
+```bash
+# For Calendar component
+npm install react-day-picker
+
+# For Carousel component
+npm install embla-carousel-react
+
+# For Chart components
+npm install recharts
+
+# For Form components
+npm install @tanstack/react-form
+```
+
+## Setup
+
+### 1. CSS Configuration
+
+Add the following imports to your project's main CSS file (e.g., `globals.css`):
+
+```css
+@import "tailwindcss";
+@import "appy-ui/styles.css";
+@source "../node_modules/appy-ui/dist/**/*.js";
+```
+
+### 2. Provider Setup
+
+Wrap your app with the `DesignSystemProvider`:
+
+```tsx
+import { DesignSystemProvider } from 'appy-ui';
+
+function App() {
+  return (
+    <DesignSystemProvider>
+      <YourApp />
+    </DesignSystemProvider>
+  );
+}
+```
+
+## Usage
+
+```tsx
+import { Button, Card, CardContent, CardHeader, CardTitle } from 'appy-ui';
+
+function MyComponent() {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Welcome</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button>Click me</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Design System
+
+The library automatically detects the user's platform and applies the appropriate design system:
+
+- **iOS devices**: iOS Liquid Glass styling (`.ios` class)
+- **Android devices**: Material 3 styling (`.material` class)
+- **Desktop**: Default styling
+
+You can also manually set the design system:
+
+```tsx
+import { useDesignSystem } from 'appy-ui';
+
+function Settings() {
+  const { designSystem, setDesignSystem, isAuto } = useDesignSystem();
+
+  return (
+    <div>
+      <p>Current: {designSystem}</p>
+      <button onClick={() => setDesignSystem('auto')}>Auto</button>
+      <button onClick={() => setDesignSystem('ios')}>iOS</button>
+      <button onClick={() => setDesignSystem('material')}>Material</button>
+    </div>
+  );
+}
+```
+
+## Platform-Specific Styling
+
+Use Tailwind CSS custom variants for platform-specific styles:
+
+```tsx
+<div className="bg-white ios:bg-glass-bg material:bg-m3-surface">
+  Content
+</div>
+```
+
+## Layout Components
+
+### TabBar
+
+Adaptive navigation that changes based on platform/form factor:
+
+```tsx
+import { TabBar, type TabItem } from 'appy-ui';
+import { Link, useRouterState } from '@tanstack/react-router';
+
+const items: TabItem[] = [
+  { id: 'home', label: 'Home', path: '/', icon: HomeIcon, activeIcon: HomeFilledIcon },
+  { id: 'profile', label: 'Profile', path: '/profile', icon: UserIcon, activeIcon: UserFilledIcon },
+];
+
+function Navigation() {
+  const { location } = useRouterState();
+
+  return (
+    <TabBar
+      items={items}
+      currentPath={location.pathname}
+      LinkComponent={Link}
+    />
+  );
+}
+```
+
+### Header
+
+Adaptive header with scroll animation support:
+
+```tsx
+import { Header, SecondaryPageHeader, TabPageHeader } from 'appy-ui';
+
+// For secondary pages (with back button)
+<SecondaryPageHeader title="Settings" onBack={() => navigate(-1)} />
+
+// For tab pages (with animated title)
+<TabPageHeader title="Home" />
+
+// Custom composition
+<Header.Root>
+  <Header.BackButton onClick={handleBack} />
+  <Header.AnimatedTitle>My Page</Header.AnimatedTitle>
+  <Header.TrailingAction>
+    <button>Action</button>
+  </Header.TrailingAction>
+</Header.Root>
+```
+
+## Components
+
+### UI Components (55+)
+
+- Accordion
+- Alert, AlertDialog
+- AspectRatio
+- Avatar (with Badge, Group)
+- Badge
+- Breadcrumb
+- Button, ButtonGroup
+- Calendar
+- Card
+- Carousel
+- Chart
+- Checkbox
+- Collapsible
+- Combobox
+- Command
+- ContextMenu
+- Dialog
+- Drawer
+- DropdownMenu
+- Empty
+- Field (form)
+- HoverCard
+- Input, InputGroup, InputOTP
+- Item
+- Kbd
+- Label
+- Menubar
+- NativeSelect
+- NavigationMenu
+- Pagination
+- Popover
+- Progress, ProgressiveBlur
+- RadioGroup
+- Resizable
+- ScrollArea
+- Select
+- Separator
+- Sheet
+- Sidebar
+- Skeleton
+- Slider
+- Sonner (Toast)
+- Spinner
+- Switch
+- Table
+- Tabs
+- Textarea
+- Toggle, ToggleGroup
+- Tooltip
+
+### Layout Components
+
+- TabBar (iOS, Android, Web variants)
+- Header (with animated title)
+- WebNavBar
+- WebFooter
+
+## Hooks
+
+- `useDesignSystem()` - Access design system context
+- `useDeviceContext()` - Platform, form factor, keyboard detection
+- `useScrolled()` - Track scroll position
+- `useIsMobile()` - Mobile breakpoint detection
+
+## License
+
+MIT