@donotdev/cli 0.0.4 → 0.0.6

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

@@ -0,0 +1,456 @@
+# 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
+
+## FAQSection (from @donotdev/core)
+
+FAQ section component for displaying frequently asked questions using accordion. Reads FAQ items from i18n JSON files.
+
+**Note:** This component is from `@donotdev/core`, not `@donotdev/adv-comps`. It requires i18n setup with translation files.
+
+```tsx
+import { FAQSection, useTranslation } from '@donotdev/core';
+import { Section } from '@donotdev/components';
+
+function FAQPage() {
+  const { t } = useTranslation(['faq']);
+
+  return (
+    <Section>
+      <FAQSection t={t} keyPrefix="faqs.items" maxIndex={50} />
+    </Section>
+  );
+}
+```
+
+**Props:**
+- `t: TFunction` - Translation function from `useTranslation` hook
+- `keyPrefix: string` - Base key prefix for FAQ items (e.g., `'faqs.items'`)
+- `maxIndex?: number` - Maximum number of FAQ items to check (default: 50)
+- `className?: string` - CSS class for container
+- `itemClassName?: string` - CSS class for each accordion item
+- `aria-label?: string` - ARIA label for accessibility (default: 'Frequently Asked Questions')
+
+**JSON Structure:**
+
+FAQ items must be in your i18n JSON files with this structure:
+
+```json
+{
+  "faqs": {
+    "items": [
+      {
+        "q": "Question text",
+        "a": "Answer text"
+      },
+      {
+        "q": "Another question",
+        "a": "Another answer"
+      }
+    ]
+  }
+}
+```
+
+The component uses `translateObjectArray` to automatically load all items from `keyPrefix` (e.g., `faqs.items[0]`, `faqs.items[1]`, etc.) up to `maxIndex`.
+
+**Example:**
+
+```tsx
+// src/pages/FAQPage.tsx
+import { FAQSection, useTranslation } from '@donotdev/core';
+import { HeroSection, Section } from '@donotdev/components';
+import { PageContainer } from '@donotdev/ui';
+
+export const NAMESPACE = 'faq';
+
+function FAQPage() {
+  const { t } = useTranslation([NAMESPACE]);
+
+  return (
+    <PageContainer variant="docs">
+      <HeroSection title={t('title')} subtitle={t('subtitle')} />
+      <Section>
+        <FAQSection t={t} keyPrefix="faqs.items" maxIndex={50} />
+      </Section>
+    </PageContainer>
+  );
+}
+```
+
+```json
+// src/pages/locales/faq_en.json
+{
+  "title": "Frequently Asked Questions",
+  "subtitle": "Everything you need to know.",
+  "faqs": {
+    "items": [
+      {
+        "q": "How long does the free trial last?",
+        "a": "There is no limit. You can use the framework packages indefinitely for development and local testing."
+      },
+      {
+        "q": "What is the watermark?",
+        "a": "The watermark is a floating button that appears when running applications without a valid license."
+      }
+    ]
+  }
+}
+```

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

@@ -22,10 +22,11 @@ These are the only ways one should handle layout to get to quick results functio
 ## Content Components
 
 - **Card** - Premium card component with title, content, footer, and elevation variants.
+  - **Navigation with middle-click support:** Wrap Card in Link component for navigation that supports middle-click (opens in new tab). See navigation section below.
 - **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.
+- **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.
 
@@ -130,5 +131,46 @@ These are the only ways one should handle layout to get to quick results functio
 
 **See also:** [COMPONENTS_UI.md](./COMPONENTS_UI.md) for layout/composition components | [COMPONENTS_CRUD.md](./COMPONENTS_CRUD.md) for CRUD operations and entity forms
 
+---
+
+## Navigation with Card Component
+
+**For clickable cards with navigation support (including middle-click):**
+
+Wrap Card in Link component from `@donotdev/ui`:
+
+```tsx
+import { Card } from '@donotdev/components';
+import { Link } from '@donotdev/ui';
+
+// Card with navigation (supports middle-click)
+<Link
+  path="/about"
+  style={{ display: 'block', textDecoration: 'none', height: '100%' }}
+  aria-label="Learn more about About"
+>
+  <Card
+    title="About"
+    subtitle="Learn more about us"
+    content="Click to navigate"
+  />
+</Link>
+
+// Card with onClick only (no middle-click support)
+<Card
+  title="Action Card"
+  onClick={() => handleAction()}
+/>
+```
+
+**Why wrap in Link?**
+- Card component is standalone and not routing-aware
+- Link wrapper provides framework navigation (SPA routing, keeps outlet context)
+- Native browser middle-click support (opens in new tab)
+- CSR/SSR safe
+
+**Alternative:** Use FeatureCard from `@donotdev/ui` which handles this automatically when `href` prop is provided.
+
+---
 
 **All props documented in JSDoc** - Hover in IDE for complete reference.

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

@@ -39,6 +39,12 @@
 
 ---
 
+## 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.

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

@@ -7,6 +7,7 @@
 ## Core Setup
 
 - [SETUP_PAGES.md](./SETUP_PAGES.md) - Pages & routing (pre-configured)
+- [USE_ROUTING.md](./USE_ROUTING.md) - **Routing components & hooks (CRITICAL)**
 - [SETUP_APP_CONFIG.md](./SETUP_APP_CONFIG.md) - App + Vite configuration
 - [SETUP_I18N.md](./SETUP_I18N.md) - Translations (pre-configured)
 - [SETUP_THEMES.md](./SETUP_THEMES.md) - Themes & CSS variables (pre-configured)
@@ -16,9 +17,11 @@
 
 ## Feature Setup
 
+- [SETUP_CRUD.md](./SETUP_CRUD.md) - CRUD operations & data access (critical)
 - [SETUP_AUTH.md](./SETUP_AUTH.md) - Authentication (pre-configured)
 - [SETUP_OAUTH.md](./SETUP_OAUTH.md) - OAuth connections (pre-configured)
 - [SETUP_BILLING.md](./SETUP_BILLING.md) - Stripe subscriptions (pre-configured)
+- [SETUP_PWA.md](./SETUP_PWA.md) - Progressive Web App setup
 - [SETUP_FUNCTIONS.md](./SETUP_FUNCTIONS.md) - Firebase Functions (pre-configured)
 
 ---

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

@@ -13,6 +13,8 @@ import type { AppConfig } from '@donotdev/core';
 export const appConfig: AppConfig = {
   app: {
     name: 'My App',
+    shortName: 'App',              // Required for PWA
+    description: 'My app description', // Required for PWA
     url: 'https://myapp.com',
   },
 
@@ -93,9 +95,10 @@ export default defineViteConfig({
     generateSitemap: true,
   },
 
-  // PWA
+  // PWA (see SETUP_PWA.md for full guide)
   pwa: {
-    enabled: false,
+    enabled: false,      // Enable PWA in production
+    devEnabled: false,  // Enable PWA in development (optional)
   },
 });
 ```

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

@@ -1,6 +1,6 @@
 # Setup: Billing
 
-**Most is pre-configured.** Create Stripe config files. Framework handles checkout, webhooks, subscriptions.
+**Most is pre-configured.** Create Stripe config files. Framework handles checkout, webhooks, subscriptions, and loading UX.
 
 ---
 
@@ -24,6 +24,36 @@ STRIPE_WEBHOOK_SECRET=whsec_xxx
 
 ---
 
+## Automatic UX (Zero Config)
+
+**The hook handles loading overlays automatically for redirect operations:**
+
+```tsx
+// Just call the method - framework handles the rest
+const checkout = useStripeBilling('checkout', authState);
+const openCustomerPortal = useStripeBilling('openCustomerPortal', authState);
+
+// Checkout → Shows "Redirecting to Stripe" / "Initializing secure payment..."
+await checkout({ priceId: 'price_123', mode: 'payment' });
+
+// Portal → Shows "Redirecting to Stripe" / "Opening billing portal..."
+await openCustomerPortal();
+```
+
+**What happens automatically:**
+- Blocking fullscreen overlay during Firebase Functions cold start
+- Operation-specific messaging (checkout vs portal)
+- Translated in all 8 supported languages
+- Clean removal on redirect or error
+
+**Optional:** Use `loading` state if you want to disable your own buttons:
+```tsx
+const loading = useStripeBilling('loading', authState);
+<Button disabled={loading}>Purchase</Button>
+```
+
+---
+
 ## Advanced: Frontend Config
 
 ```typescript
@@ -69,10 +99,20 @@ import { useStripeBilling } from '@donotdev/billing';
 import { SubscriptionTemplate, PaymentTemplate } from '@donotdev/templates';
 import { ProductCard, SubscriptionManager } from '@donotdev/billing';
 
-const checkout = useStripeBilling('checkout');
-await checkout({ priceId: 'price_123', mode: 'subscription' });
+// Auth state required
+const user = useAuth('user');
+const status = useAuth('status');
+const authState = { user, status };
+
+// Methods - framework handles overlay automatically
+const checkout = useStripeBilling('checkout', authState);
+const openCustomerPortal = useStripeBilling('openCustomerPortal', authState);
+
+// Optional state access
+const loading = useStripeBilling('loading', authState);
+const error = useStripeBilling('error', authState);
 ```
 
 ---
 
-**Create config files, get billing. Framework handles the rest.**
+**Create config files, get billing with best-in-class UX. Framework handles the rest.**