@donotdev/cli 0.0.3 → 0.0.5

package/templates/root-consumer/guides/COMPONENTS_ADV.md.example

@@ -0,0 +1,360 @@
+# Advanced Components (@donotdev/adv-comps)
+
+High-level, opinionated, and marketing-focused UI components for DoNotDev framework.
+
+## Setup
+
+**IMPORTANT:** You must import the styles in your `globals.css` file:
+
+```css
+@import '@donotdev/adv-comps/styles';
+```
+
+Without this import, components will not have their required CSS styles.
+
+## Components
+
+### Crawl
+
+Cinematic 3D text crawl component with lazy loading.
+
+```tsx
+import { Crawl } from '@donotdev/adv-comps';
+
+<Crawl
+  intro?: ReactNode | string
+  title?: ReactNode | string
+  content: ReactNode | string | string[]
+  duration?: number // @default 26
+  contentHeight?: string // @default "150vh"
+  tiltAngle?: number
+  className?: string
+  style?: CSSProperties
+  aria-label?: string
+/>
+```
+
+### Marquee
+
+Production-grade marquee with accessibility, reduced motion support, and smart behavior detection.
+
+```tsx
+import { Marquee } from '@donotdev/adv-comps';
+
+<Marquee<T>
+  items: T[]
+  renderItem: (item: T, index: number) => ReactNode
+  className?: string
+  itemClassName?: string
+  gap?: 'none' | 'tight' | 'medium' | 'large' // @default 'medium'
+  speed?: number // px per second
+  direction?: 'left' | 'right' | 'up' | 'down' | 'auto' // @default 'auto'
+  pauseOnHover?: boolean
+  ariaLabel?: string
+  reducedMotion?: 'respect' | 'ignore'
+  behavior?: 'bounce' | 'infinite' | 'auto'
+  pauseOnFocusWithin?: boolean
+  easing?: 'linear' | 'ease-in-out' | 'ease-out'
+/>
+```
+
+### Roadmap
+
+Timeline component with horizontal (desktop) / vertical (mobile) layout. Features animated progress line, glowing nodes, and lift-on-hover cards.
+
+```tsx
+import { Roadmap } from '@donotdev/adv-comps';
+import type { RoadmapStep } from '@donotdev/adv-comps';
+
+<Roadmap
+  steps: RoadmapStep[]
+  className?: string
+  variant?: CardVariant // @default 'default'
+/>
+
+// RoadmapStep interface:
+interface RoadmapStep {
+  phase: string // e.g., "Week 1", "Days 1-2"
+  icon: LucideIcon
+  title: string
+  subtitle: string
+  description?: string
+  content?: CardContent // Optional content shown in popover on click
+}
+```
+
+### StackedCards
+
+Simple scroll-reveal stacked cards. Active card shows full content, stacked cards show only bottom edge with number.
+
+```tsx
+import { StackedCards } from '@donotdev/adv-comps';
+import type { StackedCardData } from '@donotdev/adv-comps';
+
+<StackedCards
+  items: StackedCardData[]
+  variant?: SurfaceVariantProps['variant']
+  ariaLabel?: string
+  threshold?: number // Intersection threshold (0.0 - 1.0) @default 0.3
+  className?: string
+  style?: CSSProperties
+/>
+
+// StackedCardData extends ComponentData with:
+interface StackedCardData extends ComponentData {
+  number?: string | number // Custom number/label (e.g. "01", "Week 1"). Defaults to index.
+}
+```
+
+### Reveal
+
+Reveal component for staggered animations. Features viewport-based visibility detection, directional animations, and customizable stagger delays.
+
+```tsx
+import { Reveal } from '@donotdev/adv-comps';
+
+<Reveal
+  items: string[] | ReactNode[]
+  direction?: 'left' | 'right' | 'top' | 'bottom' | 'fade-in' | 'alternate-h' | 'alternate-v'
+  stagger?: number // milliseconds between items
+  threshold?: number
+  distance?: number // animation distance in pixels
+  duration?: number // animation duration in milliseconds
+  once?: boolean // if true, only animate once
+  viewport?: boolean // if true, only animate items in viewport
+  overrides?: Array<{
+    index: number
+    direction: 'left' | 'right' | 'top' | 'bottom' | 'fade-in'
+  }>
+  className?: string
+  children?: ReactNode
+/>
+```
+
+### InspectorGadget
+
+Floating code inspector component. Displays a floating eye icon button that opens a dialog showing the page's source code.
+
+```tsx
+import { InspectorGadget } from '@donotdev/adv-comps';
+
+<InspectorGadget
+  data?: string // Source code string
+  sourcePath?: string // Path to source file (import with ?raw) - overrides data if provided
+  sourceCode?: string // Source code loaded from file
+  language?: string // Code language for syntax highlighting @default 'tsx'
+  title?: string // Dialog title @default 'Page Source'
+  className?: string
+/>
+```
+
+### Breathing Components
+
+Breathing exercise components for meditation and wellness apps.
+
+```tsx
+import { LungsAnimation, BreathingExerciseLayout } from '@donotdev/adv-comps';
+import type { BreathingExerciseDnDevLayoutProps } from '@donotdev/adv-comps';
+
+<BreathingExerciseLayout
+  status?: ReactNode
+  animation: ReactNode
+  instructions: ReactNode
+  debug?: boolean
+  onSkip?: () => void
+  statusValue?: string
+  onRestart?: () => void
+  isPaused?: boolean
+  isComplete?: boolean
+/>
+
+<LungsAnimation ... />
+```
+
+### Carousel
+
+Premium carousel component with lazy loading built-in. Features true infinite circular loop, hardware-accelerated animations, swipe/touch gestures, and autoplay with pause-on-hover.
+
+```tsx
+import { Carousel } from '@donotdev/adv-comps';
+import type { CarouselProps, CarouselRef } from '@donotdev/adv-comps';
+
+<Carousel<T>
+  items: T[]
+  renderItem: (item: T, index: number, isActive: boolean) => ReactNode
+  className?: string
+  slideClassName?: string
+  showArrows?: boolean
+  showDots?: boolean
+  showProgress?: boolean
+  autoplay?: boolean
+  autoplayInterval?: number // milliseconds
+  transitionDuration?: number // milliseconds
+  loop?: boolean
+  // ... and more props
+/>
+```
+
+### ComparisonGrid
+
+Comparison grid component for displaying feature comparisons. Provides lazy-loaded content with skeleton loading states.
+
+```tsx
+import { ComparisonGrid } from '@donotdev/adv-comps';
+import type { ComparisonItem } from '@donotdev/adv-comps';
+
+<ComparisonGrid
+  title?: string
+  items: ComparisonItem[]
+  gridCols?: 1 | 2 | 3 | 4 // @default 2
+  className?: string
+  ariaLabel?: string
+/>
+
+// ComparisonItem interface:
+interface ComparisonItem {
+  useCase: string
+  bestFit: string
+  dndev: string
+  reason: string
+}
+```
+
+### CongratulationsCard
+
+Card component for displaying congratulatory messages. Features customizable icon and text with centered layout.
+
+```tsx
+import { CongratulationsCard } from '@donotdev/adv-comps';
+
+<CongratulationsCard
+  text: string
+  icon?: ReactNode // @default '🎉'
+  className?: string
+/>
+```
+
+### GuideModal
+
+Modal component for displaying guides and tutorials. Provides step-by-step guide display with navigation, progress tracking, and completion handling.
+
+```tsx
+import { GuideModal } from '@donotdev/adv-comps';
+import type { GuideModalProps, GuideTemplate } from '@donotdev/adv-comps';
+
+<GuideModal
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  guide: GuideTemplate
+  icon?: LucideIcon
+/>
+
+// GuideTemplate interface:
+interface GuideTemplate {
+  title: string
+  subtitle: string
+  quickStart?: {
+    title: string
+    code: string
+    description: string
+  }
+  steps?: GuideStep[]
+  features?: string[]
+  templates?: Array<{
+    name: string
+    description: string
+  }>
+  actions?: Array<{
+    label: string
+    href: string
+    variant?: 'default' | 'outline'
+    icon?: LucideIcon
+  }>
+}
+
+// GuideStep interface:
+interface GuideStep {
+  icon: LucideIcon
+  title: string
+  description: string
+  code?: string
+  details?: string
+}
+```
+
+### SplitReveal
+
+Split reveal component for displaying content in two columns. Features left column content and right column stat cards or custom content with reveal animations.
+
+```tsx
+import { SplitReveal } from '@donotdev/adv-comps';
+import type { StatCardData } from '@donotdev/adv-comps';
+
+<SplitReveal
+  left: ReactNode
+  right: ReactNode | StatCardData[]
+  leftDirection?: 'left' | 'right' | 'top' | 'bottom' | 'fade-in' // @default 'left'
+  rightDirection?: 'left' | 'right' | 'top' | 'bottom' | 'fade-in' // @default 'right'
+  threshold?: number // @default 0.3
+  className?: string
+/>
+
+// StatCardData interface:
+interface StatCardData {
+  title: string
+  description: string
+}
+```
+
+### StartChallengeForm
+
+Generic form layout component for input + CTA button patterns.
+
+```tsx
+import { StartChallengeForm } from '@donotdev/adv-comps';
+
+<StartChallengeForm
+  input={{
+    value: string
+    onChange: (value: string) => void
+    placeholder?: string
+    label?: string
+    maxLength?: number
+    className?: string
+  }}
+  button={{
+    label: string
+    onClick: () => void
+    icon?: ComponentType<{ className?: string }>
+    variant?: ButtonVariant
+    className?: string
+  }}
+  size?: 'sm' | 'md' | 'lg'
+  className?: string
+/>
+```
+
+### Waterfall
+
+Waterfall component with lazy loading built-in. Features clean cascade layout with diagonal staircase effect, perfect for step-by-step processes or feature showcases.
+
+```tsx
+import { Waterfall } from '@donotdev/adv-comps';
+import type { WaterfallProps } from '@donotdev/adv-comps';
+
+<Waterfall
+  items: ComponentData[]
+  className?: string
+  connectorClassName?: string
+  density?: 'compact' | 'comfortable'
+  ariaLabel?: string
+  direction?: 'horizontal' | 'descending'
+/>
+```
+
+## Notes
+
+- All components are lazy-loaded by default for optimal performance
+- Components use framework theme variables for consistent styling
+- Most components support reduced motion preferences
+- All components are SSR-safe and work with both Vite and Next.js

package/templates/root-consumer/guides/COMPONENTS_ATOMIC.md.example

@@ -0,0 +1,134 @@
+# Component Reference
+
+**Check JSDoc in your IDE** - Hover over any component import to see props, types, and examples.
+
+**Import from:** `@donotdev/components` (atomic UI)
+
+**This is your GOTO  Semantic React package**
+
+---
+
+## Layout Components
+
+These are the only ways one should handle layout to get to quick results functionality wide.
+- **Section** - Layout section with title, grid, and tone system for organizing content.
+- **Grid** - CSS Grid layout primitive with responsive column control.
+- **Stack** - Flexbox layout for arranging items in rows or columns.
+- **HeroSection** - Hero banner section with title, subtitle, and gradient backgrounds.
+- **CallToAction** - Conversion-focused section with primary and secondary actions.
+
+---
+
+## Content Components
+
+- **Card** - Premium card component with title, content, footer, and elevation variants.
+- **DualCard** - Side-by-side card layout for comparison or feature showcases.
+- **Text** - Typography component with semantic text variants.
+- **Blockquote** - Styled blockquote for citations and testimonials.
+- **List** - Bullet points, numbered lists, and feature lists with zero CSS. Use `icon` prop for custom icons, `icon={null}` for plain bullets.
+- **DescriptionList** - Key-value pairs and metadata using semantic HTML (dl, dt, dd).
+- **Separator** - Visual separator with semantic styling variants.
+
+---
+
+## Action Components
+
+- **Button** - Accessible button with variants, icons, tooltips, and render prop composition.
+- **ActionButton** - Button with async action handling and loading states.
+- **FileButton** - Button that triggers file input selection.
+- **PortalButton** - Button that opens content in a portal overlay.
+
+---
+
+## Form Components
+
+- **Input** - Accessible input with mobile-friendly touch targets and key state styling.
+- **PasswordInput** - Password field with show/hide toggle functionality.
+- **Textarea** - Multi-line text input component.
+- **Label** - Accessible label with icon support and various positions.
+- **Checkbox** - Accessible checkbox with custom styling.
+- **RadioGroup** - Accessible radio group with multiple visual variants.
+- **Select** - Accessible select dropdown with search and multi-select support.
+- **Combobox** - Searchable combobox with autocomplete functionality.
+- **Switch** - Toggle switch component.
+- **Slider** - Range slider for numeric input.
+
+---
+
+## Feedback Components
+
+- **Alert** - Attention-grabbing alert with semantic variants and icons.
+- **AlertDialog** - Modal dialog that interrupts with important content expecting a response.
+- **Dialog** - Accessible modal dialog with custom content sizes and actions.
+- **Toast** - Toast notifications via Toaster component with ToastProvider.
+- **Skeleton** - Loading state skeleton with multiple animation variants.
+- **Spinner** - Loading spinner with multiple sizes and theme-aware colors.
+- **Progress** - Progress bar component for task completion.
+
+---
+
+## Navigation Components
+
+- **Tabs** - Tabbed interface with props-based API and full keyboard navigation.
+- **Accordion** - Vertically stacked headings that reveal content sections.
+- **NavigationMenu** - Props-based navigation menu with nested menus and rich content.
+- **Pagination** - Accessible pagination with page number generation and ellipsis.
+- **Command** - Command palette component for keyboard navigation and search.
+- **CommandDialog** - Command palette dialog optimized for Cmd+K navigation.
+
+---
+
+## Overlay Components
+
+- **Popover** - Accessible popover displaying rich content in a portal.
+- **Tooltip** - Tooltip component with positioning and delay controls.
+- **HoverCard** - Card that appears on hover with rich content.
+- **Sheet** - Slide-out panel for sidebars, mobile navigation, or editing panels.
+- **ContextMenu** - Right-click context menu with nested submenus.
+- **DropdownMenu** - Professional dropdown menu with props-based API.
+
+---
+
+## Data Display Components
+
+- **Table** - Accessible table component with sorting and selection.
+- **DataTable** - High-level table with built-in sorting, filtering, search, and pagination.
+- **Avatar** - Accessible avatar with image and fallback support.
+- **Badge** - Status indicator with semantic variants (polymorphic: div, span, mark).
+- **Tag** - Tag component for labels and categories.
+- **Calendar** - Accessible date picker built on react-day-picker.
+
+---
+
+## Utility Components
+
+- **Collapsible** - Collapsible content component.
+- **Toggle** - Toggle button component.
+- **ToggleGroup** - Group of toggle buttons.
+- **ScrollArea** - Scrollable area with custom scrollbars.
+- **Portal** - Portal component for rendering outside DOM hierarchy.
+- **VisuallyHidden** - Screen reader-only content component.
+- **Slot** - Slot component for composition patterns.
+
+---
+
+## Advanced Components
+
+- **InfiniteScroll** - Infinite scroll component with load more functionality.
+- **Stepper** - Step-by-step workflow component with navigation controls.
+- **CopyToClipboard** - Copy to clipboard with visual feedback.
+- **VideoPlayer** - Video player component with controls.
+- **FeatureFallback** - Fallback UI when features are unavailable.
+
+---
+
+## Icons
+
+- **Icons** - Icon components from lucide-react and custom partner icons.
+
+---
+
+**See also:** [COMPONENTS_UI.md](./COMPONENTS_UI.md) for layout/composition components | [COMPONENTS_CRUD.md](./COMPONENTS_CRUD.md) for CRUD operations and entity forms
+
+
+**All props documented in JSDoc** - Hover in IDE for complete reference.

package/templates/root-consumer/guides/COMPONENTS_CRUD.md.example

@@ -0,0 +1,70 @@
+# CRUD Package Reference
+
+**Check JSDoc in your IDE** - Hover over any component import to see props, types, and examples.
+
+**Import from:** `@donotdev/crud` (CRUD operations and forms)
+
+---
+
+## Core Hook
+
+- **useCrud** - React hook for CRUD operations (create, read, update, delete, query) with automatic validation and backend abstraction.
+
+---
+
+## Service
+
+- **getCrudService** - Get CrudService singleton instance for direct service access.
+
+---
+
+## Form Components
+
+- **EntityFormRenderer** - Renders complete entity forms with automatic field mapping.
+- **FormFieldRenderer** - Renders individual form fields based on schema.
+- **FormLayout** - Form layout component with spacing and structure.
+- **CrudButton** - Button component integrated with CRUD operations.
+
+---
+
+## Form Field Components
+
+- **TextFieldComponent** - Text input field component.
+- **NumberFieldComponent** - Number input field component.
+- **TextAreaComponent** - Textarea input field component.
+- **PasswordFieldComponent** - Password input field component.
+- **DateFieldComponent** - Date picker field component.
+- **CheckboxFieldComponent** - Checkbox field component.
+- **RadioFieldComponent** - Radio button field component.
+- **DropdownComponent** - Single-select dropdown field component.
+- **MultiDropdownComponent** - Multi-select dropdown field component.
+- **FileFieldComponent** - File upload field component.
+- **ImageFieldComponent** - Image upload field component.
+- **AvatarFieldComponent** - Avatar upload field component.
+- **BadgeFieldComponent** - Badge display/input field component.
+- **PhoneNumberComponent** - Phone number input field component.
+- **GeoPointFieldComponent** - Geographic point input field component.
+- **MapFieldComponent** - Map picker field component.
+- **TimestampFieldComponent** - Timestamp input field component.
+- **ReferenceFieldComponent** - Reference/link field component.
+- **MultiInputTextFieldComponent** - Multiple text inputs field component.
+- **ButtonFieldComponent** - Button field component.
+- **HiddenFieldComponent** - Hidden field component.
+
+---
+
+## Controlled Fields
+
+- **ControlledFields** - Controlled form field components with validation.
+
+---
+
+## Utilities
+
+- **loadDeterministicRange** - Load deterministic range from collections.
+- **upsertDeterministic** - Upsert with deterministic ID.
+- **appendToCollection** - Append item to collection.
+
+---
+
+**All props documented in JSDoc** - Hover in IDE for complete reference.

package/templates/root-consumer/guides/COMPONENTS_UI.md.example

@@ -0,0 +1,141 @@
+# UI Package Reference
+
+**Check JSDoc in your IDE** - Hover over any component import to see props, types, and examples.
+
+**Import from:** `@donotdev/ui` (layout/composition components)
+
+---
+
+## Layout Components
+
+- **PageContainer** - Page wrapper with width constraints, spacing, and density system.
+- **GameContainer** - Game preset container with fixed header/footer layout.
+- **GameFlow** - Game flow component for step-by-step game interfaces.
+
+---
+
+## Layout Sub-Components
+
+- **AppBranding** - App branding display with logo and name.
+- **AppIcon** - App icon component.
+- **AppTitle** - App title display component.
+- **GameTitle** - Game title component for game preset.
+- **Breadcrumbs** - Breadcrumb navigation component.
+- **HeaderNavigation** - Header navigation menu component.
+- **DropdownNavigation** - Dropdown navigation menu.
+- **HeaderMenu** - Header menu component.
+- **SettingsMenu** - Settings menu component.
+- **ThemeToggle** - Theme toggle button component.
+- **CacheSettings** - Cache settings component.
+- **Notifications** - Notifications component.
+- **FloatingLanguageSwitcher** - Floating language selector component.
+
+---
+
+## Auth Components
+
+- **AuthHeader** - Header component with authentication UI (sign in/out, user menu).
+- **AuthMenu** - Authentication menu component.
+
+---
+
+## Helpers
+
+- **tList(t, key, count, icon?, size?)** - Translated array as List. Default: CheckCircle icon. Pass `null` for no icon (use with emoji labels).
+
+---
+
+## Common Components
+
+- **AppLoading** - App-level loading component.
+- **FeatureDisabled** - Component shown when features are disabled.
+- **Icon** - Icon component wrapper.
+- **Loader** - Loading spinner component.
+- **LoadingMessage** - Loading message with variants (processing, saving, uploading, etc.).
+- **LoadingOverlay** - Overlay component for loading states.
+- **LoadingScreen** - Full-screen loading component.
+- **ProgressBar** - Progress bar component.
+- **Skeleton** - Skeleton loading component.
+- **FeatureCard** - Feature showcase card component.
+- **TechBento** - Tech stack showcase component.
+
+---
+
+## Routing Components
+
+- **Link** - Platform-agnostic link component (works in Vite + Next.js).
+- **AuthGuard** - Route guard component for protected routes.
+- **AuthGuardFallback** - Fallback component for auth-guarded routes.
+- **GoTo** - Programmatic navigation component.
+- **GoToWrapper** - Wrapper for GoTo navigation.
+- **GoToInput** - Input component for GoTo navigation.
+- **GoToDialog** - Dialog for GoTo navigation.
+- **DnDevNavigationMenu** - Framework navigation menu component.
+- **NotFoundPage** - 404 page component.
+
+---
+
+## Routing Hooks
+
+- **useNavigate** - Navigate to routes programmatically.
+- **useBack** - Navigate back in history.
+- **useRefresh** - Refresh current route.
+- **usePrefetch** - Prefetch route data.
+- **useLocation** - Get current location.
+- **useParams** - Get route parameters.
+- **useSearchParams** - Get URL search parameters.
+- **useMatch** - Match current route pattern.
+- **useQueryParams** - Get and set query parameters.
+- **useRedirectGuard** - Guard against redirects.
+- **useNavigation** - Navigation state and methods.
+- **useGoTo** - GoTo navigation hook.
+- **useRouteDiscovery** - Route discovery hook.
+
+---
+
+## Cookie Consent
+
+- **CookieConsent** - Cookie consent management component.
+- **ConsentBanner** - Cookie consent banner component.
+
+---
+
+## Platform-Specific Providers
+
+- **ViteAppProviders** - App providers for Vite (import from `@donotdev/ui/vite`).
+- **NextJsAppProviders** - App providers for Next.js (import from `@donotdev/ui/next`).
+
+---
+
+## CRUD Display Components (from @donotdev/ui)
+
+- **DisplayFieldRenderer** - Renders read-only field displays.
+- **EntityDisplayRenderer** - Renders complete entity displays.
+- **TextFieldDisplay** - Text field display component.
+- **BadgeFieldDisplay** - Badge field display component.
+- **AvatarFieldDisplay** - Avatar field display component.
+- **LinkFieldDisplay** - Link field display component.
+- **DateFieldDisplay** - Date field display component.
+- **NumberFieldDisplay** - Number field display component.
+- **PhoneNumberDisplay** - Phone number display component.
+- **TextAreaDisplay** - Textarea display component.
+- **CheckboxFieldDisplay** - Checkbox display component.
+- **DropdownDisplay** - Dropdown display component.
+- **MultiDropdownDisplay** - Multi-select dropdown display component.
+- **MultiInputTextFieldDisplay** - Multi-input text field display component.
+- **RadioFieldDisplay** - Radio field display component.
+- **RangeFieldDisplay** - Range field display component.
+- **FileFieldDisplay** - File field display component.
+- **ImageFieldDisplay** - Image field display component.
+- **GeoPointFieldDisplay** - GeoPoint field display component.
+- **MapFieldDisplay** - Map field display component.
+- **ReferenceFieldDisplay** - Reference field display component.
+- **TimestampFieldDisplay** - Timestamp field display component.
+- **HiddenFieldDisplay** - Hidden field display component.
+- **ButtonFieldDisplay** - Button field display component.
+
+---
+
+**For MVP:** Only `PageContainer` is needed. All other components are optional.
+
+**All props documented in JSDoc** - Hover in IDE for complete reference.