@donotdev/cli 0.0.3 → 0.0.4

package/templates/app-vite/src/themes.css.example

@@ -2,178 +2,130 @@
 
 /* ===========================
    APP-WIDE SETTINGS
-   These apply to all themes - spacing, radius, shadows, routing animations
+   Spacing, radius, shadows, animations - apply to all themes
    =========================== */
 :root {
-  /* ===========================
-     ROUTING ANIMATIONS
-     Customize page transition animations
-     Pure CSS - zero JS overhead. Respects prefers-reduced-motion.
-     Override in themes.css: --routing-animation: slide; to change animation type
-     =========================== */
-  /* Single animation type (fade, slide, or none to disable) - app-wide */
-  /* --routing-animation: fade; */  /* fade | slide | none */
-  /* --routing-default-duration: var(--dur-normal); */  /* Animation duration */
-
-  /* Breakpoint-specific durations (all inherit from --routing-default-duration) */
-  /* --routing-mobile-duration: var(--routing-default-duration); */
-  /* --routing-tablet-duration: var(--routing-default-duration); */
-  /* --routing-desktop-duration: var(--routing-default-duration); */
-  /* --routing-wide-duration: var(--routing-default-duration); */
-  
-  /* Examples: */
-  /* --routing-animation: slide; */  /* Use slide animation */
-  /* --routing-animation: none; */  /* Disable animations */
-  /* --routing-default-duration: 200ms; */  /* Faster animations */
-
-  /* ===========================
-     SPACING OVERRIDES
-     Customize spacing scale
-     =========================== */
-  /* --gap-sm: 0.5rem; */        /* 8px - tight spacing */
-  /* --gap-md: 1rem; */          /* 16px - medium spacing (default) */
-  /* --gap-lg: 2rem; */          /* 32px - large spacing */
-
-  /* ===========================
-     BORDER RADIUS OVERRIDES
-     Customize component corners
-     =========================== */
-  /* --radius-interactive: var(--radius-none); */ /* Buttons, links (default: square) */
-  /* --radius-surface: var(--radius-md); */ /* Cards, dialogs (default: 8px round) */
-  /* --radius-floating: var(--radius-none); */ /* Dropdowns, popovers (default: square) */
-
-  /* ===========================
-     SHADOW OVERRIDES
-     Customize elevation
-     =========================== */
-  /* --shadow-sm: ...; */        /* Small shadows */
-  /* --shadow-md: ...; */        /* Medium shadows (default) */
-  /* --shadow-xl: ...; */        /* Large shadows */
+  /* Routing animations (fade | slide | none) */
+  /* --routing-animation: fade; */
+  /* --routing-default-duration: var(--dur-normal); */
+
+  /* Spacing scale */
+  /* --gap-sm: 0.5rem; */
+  /* --gap-md: 1rem; */
+  /* --gap-lg: 2rem; */
+
+  /* Border radius */
+  /* --radius-interactive: var(--radius-none); */
+  /* --radius-surface: var(--radius-md); */
+  /* --radius-floating: var(--radius-none); */
 }
 
 /* ===========================
-   LIGHT THEME (High Contrast Light)
-   Background: White
-   Foreground: Black
+   LIGHT THEME
+   Zinc-based neutral palette
    =========================== */
 :root.light {
   --theme-icon: 'Sun';
   --theme-label: 'Light';
   --theme-is-dark: 0;
 
-  /* ===========================
-     1. USER SETS - 5 BRAND COLORS
-     =========================== */
-  --foreground: #000000;
+  /* Core colors */
   --background: #ffffff;
-  --primary: #00bcd4; /* Cyan */
-  --secondary: #047857; /* Emerald-700 - WCAG AA compliant (5.48:1 with white) */
-  --accent: #ff9800; /* Orange */
-
-  /* ===========================
-     2. FRAMEWORK DEFAULTS - STATUS COLORS
-     (Override if needed)
-     =========================== */
-  --success: #047857; /* Emerald-700 - WCAG AA compliant (5.48:1 with white) */
-  --warning: #f59e0b;
-  --destructive: #dc2626;
+  --foreground: #09090b;
+
+  /* Surfaces */
+  --card: #ffffff;
+  --card-foreground: #09090b;
+  --popover: #ffffff;
+  --popover-foreground: #09090b;
 
-  /* ===========================
-     3. AUTO-COMPUTED - SURFACES
-     (Plain sight computation for easy overriding)
-     =========================== */
-  --muted: color-mix(in oklab, var(--foreground) 5%, var(--background));
-  --muted-foreground: color-mix(in oklab, var(--foreground) 75%, transparent);
-  --border: color-mix(in oklab, var(--foreground) 15%, var(--background));
-  --input: var(--muted);
+  /* Muted (zinc-100 / zinc-500) */
+  --muted: #f4f4f5;
+  --muted-foreground: #71717a;
+
+  /* Border & input (zinc-200) */
+  --border: #e4e4e7;
+  --input: #e4e4e7;
   --ring: var(--primary);
 
-      --card: var(--background);
-  --card-foreground: var(--foreground);
-  --popover: var(--card);
-  --popover-foreground: var(--card-foreground);
-  --surface-1: var(--card);
-
-  /* ===========================
-     4. AUTO-COMPUTED - TEXT ON BRAND COLORS
-     (Mapped to foreground/background for consistency)
-     =========================== */
-  --primary-foreground: var(--foreground);
-  --secondary-foreground: var(--background);
-  --accent-foreground: var(--foreground);
-  
-  --success-foreground: var(--background);
-  --warning-foreground: var(--foreground);
-  --destructive-foreground: var(--background);
+  /* Brand colors - customize these */
+  --primary: #0284c7;
+  --primary-foreground: #ffffff;
+
+  --secondary: #f4f4f5;
+  --secondary-foreground: #18181b;
+
+  --accent: #ea580c;
+  --accent-foreground: #ffffff;
+
+  /* Status colors */
+  --destructive: #dc2626;
+  --destructive-foreground: #ffffff;
+  --success: #16a34a;
+  --success-foreground: #ffffff;
+  --warning: #f59e0b;
+  --warning-foreground: #09090b;
 }
 
 /* ===========================
-   DARK THEME (High Contrast Dark)
-   Background: Black
-   Foreground: White
+   DARK THEME
+   Zinc-based dark palette
    =========================== */
 :root.dark {
   --theme-icon: 'Moon';
   --theme-label: 'Dark';
   --theme-is-dark: 1;
 
-  /* ===========================
-     1. USER SETS - 5 BRAND COLORS
-     =========================== */
-  --foreground: #ffffff;
-  --background: #000000;
-  --primary: #00bcd4; /* Cyan */
-  --secondary: #047857; /* Emerald-700 - WCAG AA compliant (5.48:1 with white) */
-  --accent: #ff9800; /* Orange */
-
-  /* ===========================
-     2. FRAMEWORK DEFAULTS - STATUS COLORS
-     =========================== */
-  --success: #047857; /* Emerald-700 - WCAG AA compliant (5.48:1 with white) */
-  --warning: #f59e0b;
-  --destructive: #dc2626; /* Red-600 - WCAG AA compliant (4.83:1 with white) */
-
-  /* ===========================
-     3. AUTO-COMPUTED - SURFACES
-     =========================== */
-  --muted: color-mix(in oklab, var(--foreground) 10%, var(--background));
-  --muted-foreground: color-mix(in oklab, var(--foreground) 75%, transparent);
-  --border: color-mix(in oklab, var(--foreground) 15%, var(--background));
-  --input: var(--muted);
+  /* Core colors */
+  --background: #09090b;
+  --foreground: #fafafa;
+
+  /* Surfaces */
+  --card: #09090b;
+  --card-foreground: #fafafa;
+  --popover: #18181b;
+  --popover-foreground: #fafafa;
+
+  /* Muted (zinc-800 / zinc-400) */
+  --muted: #27272a;
+  --muted-foreground: #a1a1aa;
+
+  /* Border & input (zinc-800) */
+  --border: #27272a;
+  --input: #27272a;
   --ring: var(--primary);
 
-      --card: var(--background);
-  --card-foreground: var(--foreground);
-  --popover: var(--card);
-  --popover-foreground: var(--card-foreground);
-  --surface-1: var(--card);
-
-  /* ===========================
-     4. AUTO-COMPUTED - TEXT ON BRAND COLORS
-     =========================== */
-  --primary-foreground: var(--background);
-  --secondary-foreground: var(--foreground);
-  --accent-foreground: var(--background);
-
-  --success-foreground: var(--foreground);
-  --warning-foreground: var(--background);
-  --destructive-foreground: var(--foreground);
+  /* Brand colors - customize these */
+  --primary: #0ea5e9;
+  --primary-foreground: #ffffff;
+
+  --secondary: #27272a;
+  --secondary-foreground: #fafafa;
+
+  --accent: #f97316;
+  --accent-foreground: #ffffff;
+
+  /* Status colors */
+  --destructive: #dc2626;
+  --destructive-foreground: #ffffff;
+  --success: #16a34a;
+  --success-foreground: #ffffff;
+  --warning: #f59e0b;
+  --warning-foreground: #09090b;
 }
 
 /* ===========================
    CUSTOM THEMES
+   Add your brand themes below
    =========================== */
 
-/* Add your custom themes here */
 /* Example:
-.brand {
+:root.brand {
   --theme-icon: 'Zap';
   --theme-label: 'Brand';
-  --background: #your-brand-background;
-  --foreground: #your-brand-foreground;
-  --primary: #your-brand-primary;
-  --secondary: #your-brand-secondary;
-  --accent: #your-brand-accent;
-  ... other variables ...
+  --theme-is-dark: 0;
+  --background: #your-color;
+  --foreground: #your-color;
+  ...
 }
 */

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

@@ -1,98 +1,120 @@
 # DoNotDev Framework - Agent Quick Start
 
-**For AI Agents: Read this first.**
+**Persona:** Lead Developer (implementation, code quality) | UX/UI Designer (UX considerations) | Expert Adviser (strategic feedback, trade-offs). **Skills:** TypeScript, React, component composition, convention-over-configuration mindset. **Critical:** ALWAYS follow conventions and trust the framework. Framework handles 90% - discover before building custom.
 
----
+**When Stuck:**
+1. Check JSDoc (hover in IDE)
+2. Read relevant setup guide
+3. Trust framework defaults
+4. Ask user for clarification
 
-## Prime Directive
+**Never guess. Always verify.**
 
-**Framework-first.** 90% of what you need already exists. Discover and use before building custom.
 
-**Trust conventions.** File-based routing, auto-discovery, defaults work.
+** dndev ** is our custom CLI, dndev --help for info.
 
-**Zero CSS.** Component props only. No inline styles, no custom CSS (unless explicitly needed).
 
-**Strict typing.** TypeScript mandatory. `any` forbidden. `import type` for types.
+**🧠 PHILOSOPHY & MINDSET (READ THIS):**
+*   **Speed > Polish:** Your goal is to reach UAT (User Acceptance Testing) fast. The app should look "good enough" (80%) using standard components.
+*   **Composition > Customization:** Do not waste time writing CSS to make it "perfect" pixel-wise. Drop components, use props, move on.
+*   **Standardize:** If it looks like a standard DoNotDev app, you succeeded. If you are writing custom CSS to fight the framework, you failed.
+*   **Polishing:** Deep styling is for *after* the core functionality is approved and the User asks you to polish, with their preferred method.
 
 ---
 
-## Setup Guides (Read These)
-
-**Core setup:**
-- [PAGES_SETUP.md](./PAGES_SETUP.md) - Drop `*Page.tsx`, get routes
-- [CONFIG_SETUP.md](./CONFIG_SETUP.md) - `app.ts` + `vite.config.ts`
-- [EMULATOR_SETUP.md](./EMULATOR_SETUP.md) - Local secrets (.env.local)
-- [I18N_SETUP.md](./I18N_SETUP.md) - Drop `*_en.json`, get languages
-- [THEMING_SETUP.md](./THEMING_SETUP.md) - Override `themes.css`
-
-**Features:**
-- [AUTH_SETUP.md](./AUTH_SETUP.md) - Authentication
-- [BILLING_SETUP.md](./BILLING_SETUP.md) - Stripe subscriptions
+**✅ STYLING STANDARDS (ALWAYS FOLLOW):**
 
-**Reference:**
-- [HOW_TO_USE.md](./HOW_TO_USE.md) - Component composition philosophy
-- [COMPONENTS.md](./COMPONENTS.md) - Component catalog
-- [LAYOUTS.md](./LAYOUTS.md) - Layout presets
-- [INDEX.md](./INDEX.md) - Full guide navigation
+1.  **Layout Strategy:** Use `<Stack>`, `<Grid>`, and `<Section>` components to organize content. These handle spacing and alignment automatically.
+2.  **Component Props:** Leverage component-specific props and trust their defaults, only add what you really need.
+3.  **Interactions:** Prefer native component interactions. E.g., Use `<Card onClick={...}>` instead of nesting a Button inside if the whole item is actionable.
 
 ---
 
 ## Import Rules
 
+**Root imports only:**
 ```tsx
-// ✅ Correct
 import { Button } from '@donotdev/components';
+import { PageContainer } from '@donotdev/ui';
 import { useAuth } from '@donotdev/auth';
-import type { PageMeta } from '@donotdev/core';
-
-// ❌ Wrong
-import { Button } from '@donotdev/components/src/atomic/Button';
-import { PageMeta } from '@donotdev/core';  // Missing 'type'
 ```
 
-See [IMPORT_PATTERNS.md](./IMPORT_PATTERNS.md)
+**Type imports (strict TypeScript):**
+```tsx
+import type { ButtonProps } from '@donotdev/components';
+import type { PageMeta } from '@donotdev/core';
+```
 
 ---
 
-## Component Philosophy
+## New App Setup
 
-**Props, not CSS:**
 
-```tsx
-// ✅ Correct
-<Card title="Feature" subtitle="Description" icon={Rocket} elevated />
+**If not scaffolded:** `dndev create-app`
 
-// ❌ Wrong
-<Card style={{ padding: '2rem' }}>
-  <CardTitle>Feature</CardTitle>
-</Card>
-```
+**Configure:**
+1. `config/app.ts` - Choose layout preset + footer links + auth behavior (if needed)
+2. `config/legal.ts` - Set legal pages data
+3. `public/logo.svg` - Drop logo (framework generates rest - optional)
 
-**Composition, not nesting:**
+---
 
-```tsx
-// ✅ Correct
-<Section gridCols={3} tone="muted">
-  <Card title="One" />
-  <Card title="Two" />
-  <Card title="Three" />
-</Section>
-
-// ❌ Wrong - writing custom CSS
-<div className="my-custom-grid">...</div>
-```
+## Generic Conventions
 
----
+**Routing:** Drop `*Page.tsx` files in `pages/**` → auto-discovered. Use `PageMeta` for routes, auth, icons.
 
-## When Stuck
+**i18n:** Drop `<namespace>_<lng>.json` in `/locales` (eager) or `/pages/locales` (lazy). Framework auto-discovers languages.
 
-1. Check JSDoc (hover in IDE)
-2. Read relevant setup guide
-3. Trust framework defaults
-4. Ask user for clarification
+**Themes:** Override CSS variables in `src/themes.css`. Framework auto-computes surfaces, borders, text colors.
 
-**Never guess. Always verify.**
+---
+
+## Landing Page Example
+
+```tsx
+import { PageContainer } from '@donotdev/ui';
+import { HeroSection, Section, Card, CallToAction, Button, Grid, Stack } from '@donotdev/components';
+
+export default function HomePage() {
+  return (
+    <PageContainer>
+      <HeroSection 
+        title="Welcome" 
+        subtitle="Build fast with DoNotDev" 
+        variant="primary"
+      />
+      
+      <Section title="Features" gridCols={3}>
+        <Card title="Fast" content="Lightning fast development" />
+        <Card title="Simple" content="Zero configuration needed" />
+        <Card title="Powerful" content="Enterprise-grade features" />
+      </Section>
+      
+      <Section title="Layout Examples">
+        <Grid cols={2} gap="medium">
+          <Card title="Left Column" />
+          <Card title="Right Column" />
+        </Grid>
+        
+        <Stack direction="row" gap="medium">
+          <Button variant="primary">Primary</Button>
+          <Button variant="outline">Secondary</Button>
+        </Stack>
+      </Section>
+      
+      <CallToAction 
+        title="Get Started" 
+        subtitle="Ready to build?"
+        primaryAction={<Button variant="primary">Sign Up</Button>}
+        secondaryAction={<Button variant="outline">Learn More</Button>}
+      />
+    </PageContainer>
+  );
+}
+```
 
 ---
 
-**Start building. Framework handles the rest.**
+**Component references:** [COMPONENTS_ATOMIC.md](./COMPONENTS_ATOMIC.md) | [COMPONENTS_UI.md](./COMPONENTS_UI.md) | [COMPONENTS_CRUD.md](./COMPONENTS_CRUD.md)
+
+**Full guides:** [INDEX.md](./INDEX.md) - 50-100 LOC per topic (SETUP_*.md, advanced/*.md)

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.
+- **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.