atlasui-lib 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,157 @@
+# Changelog
+
+All notable changes to AtlasUI are documented here.  
+Project by [JohnDev19](https://github.com/JohnDev19) · [GitHub](https://github.com/JohnDev19/AtlasUI) · [atlasui.vercel.app](https://atlasui.vercel.app/)
+
+This project follows [Semantic Versioning](https://semver.org).
+
+---
+
+## [0.1.0] — 2025-06-28
+## [0.1.0] — 2025-03-13 (UPDATED)
+
+### 🎉 Initial Release
+
+First public release of AtlasUI. 90 components, a full CLI, 10 hooks, a Tailwind
+plugin, and a complete CSS token system with light + dark mode.
+
+---
+
+#### atlasui-lib
+
+**Basic (10)**
+- `Button` — solid, outline, ghost, soft, link, danger variants · sizes xs–xl · loading state · left/right icon slots
+- `IconButton` — square or circular icon-only button with all button variants
+- `Link` — anchor with external link indicator and underline control
+- `Badge` — compact label with 5 color variants and optional dot
+- `Avatar` — image with fallback initials, online/offline status ring, 6 sizes
+- `AvatarGroup` — stacked avatar row with overflow count
+- `Divider` — horizontal/vertical with optional center label
+- `Tag` — closable colored tag with icon slot
+- `Chip` — toggleable with avatar/icon support and remove button
+- `Tooltip` — Radix-powered, all four sides, configurable delay
+
+**Layout (10)**
+- `Container` — responsive max-width wrapper with padding control
+- `Stack` — flex column/row with gap, align, justify, and divider support
+- `Grid` — CSS Grid with column/row/gap config
+- `Flex` — inline flex with full directional control
+- `Section` — semantic `<section>` with vertical padding presets
+- `Spacer` — invisible spacer
+- `AspectRatio` — Radix aspect-ratio wrapper
+- `Center` — flex centering helper
+- `ScrollArea` — custom scrollbar via Radix ScrollArea
+- `Masonry` — CSS multi-column masonry grid
+
+**Navigation (10)**
+- `Navbar` — sticky + glass-blur top bar
+- `Sidebar` — collapsible with width transition
+- `Menu` / `MenuItem` — vertical nav with active/disabled states
+- `DropdownMenu` — full Radix Dropdown with all sub-primitives
+- `Breadcrumb` — accessible trail with custom separator
+- `Pagination` — page numbers, ellipsis, prev/next
+- `Tabs` — line, pills, enclosed variants · Radix powered
+- `Stepper` — horizontal/vertical multi-step progress indicator
+- `CommandDialog` — ⌘K command palette via cmdk
+
+**Forms (10)**
+- `Input` — left/right icon slots, sizes, error state
+- `TextArea` — resize control, error state
+- `Select` — full Radix Select with all sub-primitives
+- `Checkbox` — with label, description, error state
+- `RadioGroup` — per-option labels and descriptions
+- `Switch` — three sizes, label, description
+- `Slider` — range slider
+- `RangeSlider` — dual-thumb slider
+- `DatePicker` — native date input wrapper
+- `TimePicker` — native time input wrapper
+
+**Advanced Forms (10)**
+- `FileUpload` — drag-and-drop zone with click-to-upload fallback
+- `OTPInput` — PIN/OTP with auto-advance and paste support
+- `ColorPicker` — swatches + hex input
+- `SearchInput` — search with loading state and clear button
+- `PasswordInput` — toggle show/hide
+- `Combobox` — searchable single-value select
+- `MultiSelect` — multi-value select with chips
+- `FormField` / `FormLabel` / `FormError` — composable form primitives
+
+**Data Display (10)**
+- `Card` — surface with header/content/footer slots · 5 variants
+- `Table` + sub-primitives — full HTML table system
+- `DataTable` — sortable data table with loading and empty states
+- `List` / `ListItem` — simple, bordered, and divided lists
+- `Statistic` — key metric with trend indicator
+- `Timeline` — vertical events with color-coded icons
+- `Calendar` — month picker with highlighted dates
+- `CodeBlock` — code display with copy button and line numbers
+- `Chart` — chart wrapper (bring your own chart library)
+
+**Feedback (10)**
+- `Alert` — info/success/warning/danger with optional dismiss
+- `Toast` — Radix Toast with all sub-primitives
+- `Snackbar` — positioned message with action
+- `Progress` — linear bar with color variants
+- `CircularProgress` — SVG ring with indeterminate mode
+- `Skeleton` — pulse placeholder for text, rect, circle
+- `LoadingSpinner` — accessible SVG spinner
+- `EmptyState` — icon + title + description + action slot
+- `StatusIndicator` — online/offline/busy/away dot with pulse
+- `Notification` — notification item with avatar, timestamp, unread dot
+
+**Overlay (10)**
+- `Modal` — preset dialog with size variants (sm → full)
+- `Dialog` — full Radix Dialog primitive suite
+- `Drawer` — slide-in from any edge (left/right/top/bottom)
+- `Sheet` — Drawer alias
+- `Popover` — floating panel
+- `HoverCard` — rich hover preview
+- `ContextMenu` — right-click menu
+- `CommandDialog` — ⌘K palette
+- `Lightbox` / `ImageViewer` — full-screen image overlay
+
+**Media (5)**
+- `Image` — fallback, aspect ratio, object-fit, rounded, caption
+- `VideoPlayer` — HTML5 video with captions/subtitles track support
+- `AudioPlayer` — custom UI with seek bar, cover art
+- `Carousel` — autoplay, dots, arrows, loop, slidesPerView
+- `Gallery` — responsive image grid with click handler
+
+**Utility (5)**
+- `ThemeSwitcher` — icon / toggle / select variants
+- `CopyButton` — icon or labelled button with success feedback
+- `KeyboardShortcut` — styled `<kbd>` shortcut display
+- `ResizablePanel` — drag-to-resize with min/max constraints
+- `DragDropArea` — accessible file drop zone
+
+#### Hooks
+- `useDisclosure` — open/close state management
+- `useMediaQuery` — window media query subscription
+- `useBreakpoint` — Tailwind breakpoint helper
+- `useClipboard` — clipboard copy with timeout feedback
+- `useLocalStorage` — persistent state
+- `useTheme` — theme switching (persists to localStorage)
+- `useDebounce` — debounced value
+- `useOnClickOutside` — outside click detection
+- `useKeydown` — keyboard shortcut listener with modifier support
+- `useMounted` — SSR-safe mount check
+- `useToast` — programmatic toast notifications
+
+#### Infrastructure
+- Tailwind CSS plugin + preset (`atlasPlugin`, `atlasPreset`)
+- Full CSS design token system — light and dark themes
+- `AtlasProvider` for Next.js App Router
+- TypeScript strict throughout — full named type exports
+- Tree-shakeable ESM + CJS dual build via tsup
+- Turbo monorepo setup
+
+#### atlasui-lib CLI
+- `init` — project setup wizard (detects Next.js, writes atlas.config.json)
+- `add` — copies components + installs npm deps, resolves AtlasUI peer deps
+- `list` — browse all 90 components filtered by category
+- `diff` — compare local copy to latest (registry fetch, coming soon)
+- Auto-detects npm / pnpm / yarn / bun
+
+---
+
+[0.1.0]: https://github.com/JohnDev19/AtlasUI/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JohnDev19
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+<div align="center">
+
+<br/>
+
+```
+╔═╗╔╦╗╦  ╔═╗╔═╗╦ ╦╦
+╠═╣ ║ ║  ╠═╣╚═╗║ ║║
+╩ ╩ ╩ ╩═╝╩ ╩╚═╝╚═╝╩
+```
+
+### **Build anything. Ship faster.**
+
+90+ production-ready React components — accessible, composable, dark-mode ready.
+Works with Tailwind CSS and Next.js out of the box.
+
+[![npm](https://img.shields.io/npm/v/atlasui-lib?color=0ea5e9&label=atlasui-lib)](https://www.npmjs.com/package/atlasui-lib)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6)](https://www.typescriptlang.org)
+[![GitHub](https://img.shields.io/github/stars/JohnDev19/AtlasUI?style=social)](https://github.com/JohnDev19/AtlasUI)
+
+**[Docs](https://atlasui.vercel.app/)** · **[Components](https://atlasui.vercel.app/components)** · **[Issues](https://github.com/JohnDev19/AtlasUI/issues)** · **[Changelog](CHANGELOG.md)**
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install atlasui-lib
+# pnpm add atlasui-lib
+# bun add atlasui-lib
+```
+
+---
+
+## Setup
+
+### 1. Import the stylesheet
+
+```tsx
+// app/layout.tsx
+import "atlasui-lib/styles";
+```
+
+### 2. Add the Tailwind plugin
+
+```ts
+// tailwind.config.ts
+import { atlasPlugin } from "atlasui-lib/tailwind";
+
+export default {
+  darkMode: ["class"],
+  content: ["./app/**/*.{ts,tsx}", "./components/**/*.{ts,tsx}"],
+  plugins: [atlasPlugin],
+};
+```
+
+### 3. Wrap your app
+
+```tsx
+// app/layout.tsx
+import { AtlasProvider } from "atlasui-lib/provider";
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en">
+      <body>
+        <AtlasProvider>{children}</AtlasProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### 4. Start building
+
+```tsx
+import { Button, Card, CardContent, Input, Badge } from "atlasui-lib";
+
+export default function Page() {
+  return (
+    <Card>
+      <CardContent className="flex flex-col gap-4 p-6">
+        <Badge variant="soft" color="success">New</Badge>
+        <Input placeholder="Email address" type="email" />
+        <Button variant="solid" size="lg">Get started</Button>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+---
+
+## CLI
+
+atlasui-lib ships with a CLI that copies components straight into your project — shadcn-style. You own the code.
+
+```bash
+# Set up atlasui-lib in your project (writes atlas.config.json)
+npx atlasui-lib init
+
+# Add components
+npx atlasui-lib add button
+npx atlasui-lib add card modal drawer toast
+
+# Browse all 90 components
+npx atlasui-lib list
+npx atlasui-lib list --category forms
+
+# Compare your local copy to the latest version
+npx atlasui-lib diff button
+```
+
+After running `add`, a file like `components/ui/button/index.tsx` appears in your project. It re-exports from `atlasui-lib` by default, or you can paste the full source in and go wild.
+
+---
+
+## Components (90)
+
+### Basic (10)
+`Button` `IconButton` `Link` `Badge` `Avatar` `AvatarGroup` `Divider` `Tag` `Chip` `Tooltip`
+
+### Layout (10)
+`Container` `Stack` `Grid` `Flex` `Section` `Spacer` `AspectRatio` `Center` `ScrollArea` `Masonry`
+
+### Navigation (10)
+`Navbar` `Sidebar` `Menu` `DropdownMenu` `Breadcrumb` `Pagination` `Tabs` `CommandPalette` `NavigationMenu` `Stepper`
+
+### Forms (10)
+`Input` `TextArea` `Select` `Checkbox` `RadioGroup` `Switch` `Slider` `RangeSlider` `DatePicker` `TimePicker`
+
+### Advanced Forms (10)
+`FileUpload` `OTPInput` `ColorPicker` `SearchInput` `PasswordInput` `Combobox` `MultiSelect` `FormField` `FormLabel` `FormError`
+
+### Data Display (10)
+`Card` `Table` `DataTable` `List` `ListItem` `Statistic` `Timeline` `Calendar` `Chart` `CodeBlock`
+
+### Feedback (10)
+`Alert` `Toast` `Snackbar` `Progress` `CircularProgress` `Skeleton` `LoadingSpinner` `EmptyState` `StatusIndicator` `Notification`
+
+### Overlay (10)
+`Modal` `Dialog` `Drawer` `Popover` `HoverCard` `ContextMenu` `CommandDialog` `Sheet` `Lightbox` `ImageViewer`
+
+### Media (5)
+`Image` `VideoPlayer` `AudioPlayer` `Carousel` `Gallery`
+
+### Utility (5)
+`ThemeSwitcher` `CopyButton` `KeyboardShortcut` `ResizablePanel` `DragDropArea`
+
+---
+
+## Hooks
+
+```tsx
+import {
+  useDisclosure,     // open/close state for modals, drawers, anything toggle
+  useMediaQuery,     // subscribe to any CSS media query
+  useBreakpoint,     // Tailwind breakpoint detection (sm, md, lg, xl, 2xl)
+  useClipboard,      // clipboard copy with "copied!" feedback
+  useLocalStorage,   // useState that persists to localStorage
+  useTheme,          // read/set light · dark · system theme
+  useDebounce,       // debounce any value — perfect for search inputs
+  useOnClickOutside, // detect clicks outside a ref'd element
+  useKeydown,        // keyboard shortcut listener with modifier support
+  useMounted,        // SSR-safe mount check
+  useToast,          // fire toasts programmatically
+} from "atlasui-lib";
+```
+
+---
+
+## Theming
+
+All colors are CSS custom properties. Override them in your global CSS:
+
+```css
+:root {
+  /* swap in your brand color */
+  --primary: 262 83% 58%;
+  --primary-foreground: 0 0% 100%;
+
+  /* rounder corners */
+  --radius: 0.75rem;
+}
+```
+
+Full token list: `--background` `--foreground` `--primary` `--secondary` `--muted` `--accent` `--destructive` `--success` `--warning` `--info` `--border` `--input` `--ring` `--radius`.
+
+---
+
+## Dark Mode
+
+Uses the `class` strategy — add `dark` to `<html>` and everything flips automatically.
+
+```tsx
+import { useTheme, ThemeSwitcher } from "atlasui-lib";
+
+function Header() {
+  const { theme, setTheme } = useTheme();
+  return <ThemeSwitcher value={theme} onChange={setTheme} variant="toggle" />;
+}
+```
+
+---
+
+## Package Structure
+
+```
+atlasui-lib/
+├── src/
+│   ├── components/
+│   │   ├── basic/           Button, IconButton, Badge, Avatar, Tooltip…
+│   │   ├── layout/          Container, Stack, Grid, ScrollArea, Masonry…
+│   │   ├── navigation/      Navbar, Tabs, DropdownMenu, Stepper…
+│   │   ├── forms/           Input, Select, Checkbox, Slider, Switch…
+│   │   ├── advanced-forms/  OTPInput, ColorPicker, Combobox, MultiSelect…
+│   │   ├── data-display/    Card, DataTable, Timeline, Calendar, CodeBlock…
+│   │   ├── feedback/        Alert, Toast, Skeleton, EmptyState, Progress…
+│   │   ├── overlay/         Modal, Drawer, CommandDialog, Lightbox…
+│   │   ├── media/           VideoPlayer, AudioPlayer, Carousel, Gallery…
+│   │   └── utility/         ThemeSwitcher, CopyButton, ResizablePanel…
+│   ├── hooks/               10 utility hooks
+│   ├── styles/              atlas.css — full design token system
+│   ├── types/               shared TypeScript types
+│   ├── utils/               cn() and helpers
+│   ├── cli/                 atlasui-lib CLI (add, init, list, diff)
+│   ├── provider.tsx         AtlasProvider for Next.js
+│   └── tailwind.ts          atlasPlugin + atlasPreset
+├── package.json
+├── tsup.config.ts
+└── tsconfig.json
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome.
+→ [github.com/JohnDev19/AtlasUI/issues](https://github.com/JohnDev19/AtlasUI/issues)
+
+---
+
+## License
+
+MIT © [JohnDev19](https://github.com/JohnDev19)
+
+---
+
+<div align="center">
+  <sub>Built by JohnDev19.</sub>
+</div>