npm package: @placesapp/appy-ui
Description: 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.
Latest version: 0.0.339

# 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
```

## 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