nextworks 0.1.0-alpha.2 → 0.1.0-alpha.4

package/dist/kits/blocks/.nextworks/docs/THEME_GUIDE.md

@@ -0,0 +1,223 @@
+# Theme System Guide
+
+This file is shipped with the Nextworks Blocks kit and lives under `.nextworks/docs/THEME_GUIDE.md` in your project.
+
+The content below is the canonical theme guide for projects using Nextworks Blocks.
+
+---
+
+## Overview
+
+This project now includes a comprehensive theming system that allows you to easily switch between different color schemes and have all components automatically adapt.
+
+## How to Use
+
+### 1. Basic Setup
+
+Your app is already configured with the enhanced theme provider in `app/layout.tsx`. The default theme is set to "monochrome".
+
+### 2. Available Themes
+
+- **Monochrome** - Clean black and white theme
+- **Blue** - Professional blue color scheme
+- **Green** - Fresh green color scheme
+- **Purple** - Modern purple color scheme
+- **Orange** - Vibrant orange color scheme
+- **Default** - Standard shadCN theme
+
+### 3. Using Theme-Aware Components
+
+#### Navbar2 Component
+
+```tsx
+import { Navbar2 } from "@/components/sections/Navbar2";
+
+<Navbar2
+  brand="My App"
+  brandNode={<YourLogoComponent />}
+  menuItems={[
+    { label: "Home", href: "/" },
+    { label: "About", href: "/about" },
+  ]}
+  ctaButton={{ label: "Get Started", href: "/signup" }}
+  showThemeSelector={true}
+/>;
+```
+
+#### Theme Selector
+
+The `ThemeSelector` component is automatically included in Navbar2 and allows users to:
+
+- Switch between theme variants (monochrome, blue, green, etc.)
+- Toggle between light/dark modes
+- Use system preference
+
+### 4. Converting Existing Components
+
+To make your existing components theme-aware, replace hardcoded colors with semantic classes:
+
+#### Before (Hardcoded Colors):
+
+```tsx
+className = "bg-gray-50 dark:bg-gray-800 text-gray-800 dark:text-white";
+```
+
+#### After (Theme-Aware):
+
+```tsx
+className = "bg-background text-foreground";
+```
+
+#### Common Replacements:
+
+- `text-gray-800 dark:text-white` → `text-foreground`
+- `bg-gray-50 dark:bg-gray-800` → `bg-background`
+- `border-gray-200 dark:border-gray-700` → `border-border`
+- `hover:bg-gray-100 dark:hover:bg-gray-700` → `hover:bg-accent`
+- `text-blue-600 dark:text-blue-500` → `text-primary`
+
+### 5. Semantic Color Classes
+
+Use these semantic classes for consistent theming:
+
+- `text-primary` - Primary brand color
+- `text-secondary` - Secondary text color
+- `text-muted-foreground` - Muted text color
+- `bg-background` - Main background color
+- `bg-card` - Card background color
+- `bg-accent` - Accent background color
+- `border-border` - Border color
+- `ring-ring` - Focus ring color
+
+### 6. Creating Custom Themes
+
+To create a custom theme, modify `lib/themes.ts`:
+
+```ts
+export const themes: Record<ThemeVariant, ThemeConfig> = {
+  // ... existing themes
+  myCustomTheme: {
+    name: "My Custom Theme",
+    colors: {
+      primary: "oklch(0.5 0.2 120)", // Custom green
+      primaryForeground: "oklch(0.98 0 0)",
+      // ... other colors
+    },
+  },
+};
+```
+
+### 7. Example Usage
+
+See the templates under `app/templates/*` and `lib/themes.ts` for concrete examples of how themes are wired up.
+
+## Benefits
+
+1. **Consistent Design**: All components automatically use the same color scheme
+2. **Easy Customization**: Change the entire app's look by switching themes
+3. **Accessibility**: Proper contrast ratios maintained across all themes
+4. **Developer Experience**: No need to manually style each component
+5. **User Choice**: Users can choose their preferred theme and light/dark mode
+
+---
+
+## Mixing tokens and local overrides
+
+Sometimes you want the speed and consistency of the Color Theme (tokens), but still make template-specific tweaks. This project supports three patterns:
+
+- Token-first: use semantic classes/variants everywhere (default behavior)
+- Hybrid: keep tokens for most things and override specific slots/elements
+- Full control: bypass tokens with unstyled primitives and fully custom classes
+
+### 1) Prefer additive overrides first
+
+- Keep variant/size from tokens and add className for small tweaks.
+- Use component slot props for targeted overrides rather than global changes.
+
+Example: override only mobile link hover background in the shared Navbar from a preset, leaving everything else token-based.
+
+```tsx
+// app/templates/productlaunch/components/Navbar.tsx
+mobileLinks: {
+  className: "hover:bg-purple-50 dark:hover:bg-purple-900/20",
+},
+```
+
+### 2) Override focus ring colors locally
+
+Links in Navbar apply a token focus ring (`focus:ring-ring`). You can override it per preset by placing your ring utilities in `links.className` (these are merged last):
+
+```tsx
+// app/templates/productlaunch/components/Navbar.tsx
+links: {
+  className:
+    "text-sm font-medium font-inter text-gray-800 dark:text-white hover:text-purple-700 dark:hover:text-purple-500 " +
+    "focus:ring-purple-500 dark:focus:ring-purple-400",
+},
+```
+
+### 3) ThemeToggle with local styling
+
+`ThemeToggle` accepts `buttonProps` that forward to the internal `Button`. For small tweaks, keep token variants and just add classes. For full control, use `unstyled: true` to bypass tokens:
+
+```tsx
+// app/templates/productlaunch/components/Navbar.tsx
+themeToggle: {
+  buttonProps: {
+    unstyled: true,
+    className:
+      "size-9 p-0 flex items-center justify-center rounded-md border border-gray-200 " +
+      "bg-white text-gray-700 hover:bg-purple-50 hover:text-purple-700 " +
+      "dark:border-gray-800 dark:bg-gray-900 dark:text-gray-100 dark:hover:bg-purple-900/20 " +
+      "transition-colors focus:outline-none focus:ring-2 focus:ring-purple-500 dark:focus:ring-purple-400",
+  },
+  moonClassName: "text-gray-700 dark:text-gray-100",
+  sunClassName: "text-gray-700 dark:text-gray-100",
+},
+```
+
+### 4) Unstyled escape hatch for primitives
+
+Shared primitives like `Button` support an `unstyled` prop to bypass tokenized CVA classes and allow complete consumer control:
+
+```tsx
+// components/ui/button.tsx
+<Button unstyled className="rounded-md bg-purple-600 px-3 py-2 text-white ...">
+  Click me
+</Button>
+```
+
+Use this when a section must not be influenced by the global Color Theme.
+
+### 5) Navbar accent via CSS variables (recommended for presets)
+
+Set a small set of CSS variables on the Navbar root in your preset, and internal elements (ThemeToggle, mobile links, focus rings) will read them automatically with fallbacks to tokens.
+
+Suggested variables:
+
+- `--navbar-accent`: icon/text accent color
+- `--navbar-hover-bg`: hover background color for toggle and mobile links
+- `--navbar-toggle-bg`: default background for the theme toggle button
+- `--navbar-ring`: focus ring color
+- `--navbar-border`: border color for theme toggle and similar controls
+
+Example in a preset:
+
+```tsx
+// app/templates/productlaunch/components/Navbar.tsx
+nav: {
+  className:
+    "bg-white dark:bg-gray-900 text-gray-800 dark:text-white border-b border-gray-200 dark:border-gray-800 " +
+    "[--navbar-accent:theme(colors.purple.600)] dark:[--navbar-accent:theme(colors.purple.400)] " +
+    "[--navbar-hover-bg:theme(colors.purple.50)] dark:[--navbar-hover-bg:color-mix(in oklab,oklch(0.17 0.05 324) 20%, transparent)] " +
+    "[--navbar-ring:theme(colors.purple.500)] dark:[--navbar-ring:theme(colors.purple.400)]",
+},
+```
+
+After setting these, you generally don’t need to pass `themeToggle` overrides; the toggle and links will align to your preset accent automatically.
+
+Notes:
+
+- Consumer `className` is merged last, so your overrides win when conflicts exist.
+- Always include `dark:` variants when you override hover/focus to maintain dark mode parity.
+- Scope overrides narrowly (slots/elements) to avoid surprising global changes.

package/dist/kits/data/.nextworks/docs/DATA_QUICKSTART.md

@@ -0,0 +1,112 @@
+# nextworks — Data kit quickstart
+
+This document explains how to use the Data (crud) kit in the nextworks starter project.
+
+Prerequisites
+
+- A running PostgreSQL database and `DATABASE_URL` set in `.env`.
+- Auth kit installed and configured (NextAuth + Prisma). The Data kit relies on NextAuth session for access control.
+  - In the monorepo, this is already wired up.
+  - In your own app via the CLI, the recommended alpha setup is to install Blocks (with sections + templates) + Auth Core + Forms first, then Data:
+
+    ```bash
+    npx nextworks add blocks --sections --templates
+    npx nextworks add auth-core
+    npx nextworks add forms
+    npx nextworks add data
+    ```
+
+    then follow the Prisma and `.env` steps below.
+
+- Forms kit (optional but recommended) for form primitives.
+
+Setup
+
+1. Install dependencies and generate Prisma client:
+
+   npm install
+   npx prisma generate
+
+2. Run migrations (creates User/Post tables):
+
+   Make sure you have merged the Auth + Data models into your `prisma/schema.prisma` before running migrations.
+
+   npx prisma migrate dev
+
+3. Seed a demo admin user and posts locally (optional):
+
+   # Set env vars or use defaults
+
+   SEED_ADMIN_EMAIL=admin@example.com SEED_ADMIN_PASSWORD=password123 node ./scripts/seed-demo.mjs
+
+4. Run the dev server:
+
+   npm run dev
+
+Usage & testing
+
+- Sign in at /auth/login using the seeded admin credentials (admin@example.com / password123).
+- Visit /admin/posts to create/edit/delete posts. The UI supports pagination, search (title contains), and sort by createdAt.
+- Visit /admin/users to view users (admin-only).
+
+Notes
+
+- Server-side RBAC: all modifying APIs (POST/PUT/DELETE) require a valid session, and user-level checks ensure only authors or admins can modify posts. The users list API requires admin access.
+- Published flag: posts have a `published` boolean in Prisma. The admin UI exposes the published checkbox when creating or editing posts.
+
+Troubleshooting
+
+- If users list returns 403, ensure your signed-in user has role = 'admin'. You can promote a user with Prisma Studio or by running:
+
+  npx prisma db executeRaw "UPDATE \"User\" SET role = 'admin' WHERE email = 'admin@example.com';"
+
+- If migrations fail, try:
+
+  npx prisma migrate reset
+
+Files & kit manifest
+
+If you plan to package a Data kit, here are the primary files, API routes and components used by the Data example flows. This manifest is intended to help packaging and documentation — adjust paths if you extract the kit into another project.
+
+Files
+
+- app/api/posts/route.ts
+- app/api/posts/[id]/route.ts
+- app/api/users/route.ts
+- app/api/users/[id]/route.ts
+- app/api/users/check-unique/route.ts
+- app/api/users/check-email/route.ts
+- app/api/seed-demo/route.ts
+- app/api/signup/route.ts
+- components/admin/admin-header.tsx
+- components/admin/posts-manager.tsx
+- components/admin/users-manager.tsx
+- app/(protected)/admin/users/page.tsx
+- app/(protected)/admin/posts/page.tsx
+- app/examples/demo/create-post-form.tsx
+- app/examples/demo/page.tsx
+- lib/prisma.ts
+- lib/server/result.ts
+- lib/utils.ts
+- lib/validation/forms.ts
+- scripts/seed-demo.mjs
+
+API routes (list)
+
+- /api/posts (GET/POST) -> app/api/posts/route.ts
+- /api/posts/:id (GET/PUT/DELETE) -> app/api/posts/[id]/route.ts
+- /api/users (GET/POST) -> app/api/users/route.ts
+- /api/users/:id (GET/PUT/DELETE) -> app/api/users/[id]/route.ts
+- /api/users/check-unique -> app/api/users/check-unique/route.ts
+- /api/users/check-email -> app/api/users/check-email/route.ts
+- /api/seed-demo -> app/api/seed-demo/route.ts
+- /api/signup -> app/api/signup/route.ts
+
+Notes
+
+- The Data kit relies on NextAuth sessions for access control — see lib/auth-helpers.ts and lib/auth.ts for server-side helpers and RBAC checks.
+- The API routes return ApiResult envelope objects (see lib/server/result.ts) and the client uses lib/forms/map-errors.ts to map server validation errors into react-hook-form where appropriate.
+
+Feedback
+
+- File issues in the repo; note that CLI packaging for the Data kit is not yet implemented — this quickstart is for the repository as-is.

package/dist/kits/data/.nextworks/docs/DATA_README.md

@@ -0,0 +1,117 @@
+Data kit (cli/kits/data)
+
+This kit provides a standalone example Data layer with Posts + Users CRUD: API routes, admin UI, Prisma helpers and a seed script. The kit is designed to be installed via the `nextworks` CLI:
+
+```bash
+npx nextworks add data
+```
+
+and is packaged with its own kit dependencies metadata.
+
+> **Alpha note**
+>
+> In this early alpha, the Data kit is tested and supported on top of **Blocks** (with sections + templates), **Auth Core**, and **Forms**. For the smoothest experience, run:
+>
+> ```bash
+> npx nextworks add blocks --sections --templates
+> npx nextworks add auth-core
+> npx nextworks add forms
+> npx nextworks add data
+> ```
+>
+> Using Data without Blocks/Auth/Forms may work but is not yet a supported path and can require manual Prisma/schema and UI tweaks.
+
+What the kit includes
+
+- API routes:
+  - app/api/posts/route.ts
+  - app/api/posts/[id]/route.ts
+  - app/api/users/route.ts
+  - app/api/users/[id]/route.ts
+  - app/api/users/check-unique/route.ts
+  - app/api/users/check-email/route.ts
+  - app/api/seed-demo/route.ts
+- Admin UI components (now standalone in the kit):
+  - components/admin/posts-manager.tsx
+  - components/admin/users-manager.tsx
+- Protected admin pages:
+  - app/(protected)/admin/posts/page.tsx
+  - app/(protected)/admin/users/page.tsx
+- Example/demo pages and helpers:
+  - app/examples/demo/create-post-form.tsx
+  - app/examples/demo/page.tsx
+  - app/examples/demo/README.md
+- Prisma helpers and utilities:
+  - lib/prisma.ts
+  - lib/server/result.ts (ApiResult helpers)
+  - lib/utils.ts
+- Seed script: scripts/seed-demo.mjs
+- Kit metadata: package-deps.json (declares @prisma/client and zod; prisma is a devDependency)
+
+Database requirements
+
+- The data kit is designed and tested with **PostgreSQL**, using a Postgres database hosted on [Neon](https://neon.tech/) during development.
+- Any Prisma‑supported provider _may_ work, but **Postgres is the recommended and currently tested path**.
+
+Quick start with Postgres (recommended):
+
+1. Create a Postgres database (for example on Neon).
+2. Copy the connection string into your `.env` as:
+
+   ```bash
+   DATABASE_URL="postgres://..."
+   ```
+
+3. Merge the Data/Auth Prisma models into your project's `prisma/schema.prisma` (see `prisma/auth-models.prisma` referenced by the manifest).
+4. Run:
+
+   ```bash
+   npx prisma generate
+   npx prisma migrate dev -n init_data
+   ```
+
+If you choose a different database provider, update the `provider` field in your Prisma schema and carefully review indexes/constraints before running migrations.
+
+Notes and important behavior
+
+- Kit dependencies:
+  - Data depends on Auth (for RBAC/session) and Forms (for form primitives/validation). The CLI currently auto-installs `auth-core` and `forms` when you run `nextworks add data` to ensure the required pieces are present. If you prefer an interactive prompt instead of auto-install, the CLI can be adjusted to prompt (ask the maintainers).
+  - The kit's package-deps.json lists runtime and dev dependencies that the CLI will merge into the project's package.json; after installation you must run npm install in the project.
+
+- Standalone admin components:
+  - The admin UI components have been copied into the kit so the Data kit is self-contained. They may still import shared UI primitives (for example from a Blocks or shared ui package) — ensure the consumer project has those UI packages or the CLI installs the required kits.
+
+- Auth overlap:
+  - The Data kit references the signup API route (app/api/signup/route.ts) in its manifest but does not duplicate the signup implementation — signup is provided by the Auth kit.
+
+- Prisma schema & migrations:
+  - The kit manifest references prisma/schema.prisma, prisma/migrations/\* and prisma/auth-models.prisma snippets, but the kit does not ship a full migrations directory. You must merge the provided model snippets into your project's prisma/schema.prisma, then run:
+    1. npx prisma generate
+    2. npx prisma migrate dev
+
+Post-install checklist
+
+1. Run `npm install` in your project to install dependencies merged by the kit.
+2. Merge the Data/Auth Prisma models into your project's `prisma/schema.prisma` (see `prisma/auth-models.prisma` referenced by the manifest) and run:
+   - `npx prisma generate`
+   - `npx prisma migrate dev`
+3. Populate demo data if desired:
+   - Either run the kit seed script locally: `node scripts/seed-demo.mjs`
+   - Or call the included API seed endpoint (POST to `/api/seed-demo`) if you prefer an HTTP-driven seed.
+
+CLI behavior and packaging (for maintainers)
+
+- Command: the CLI exposes the command `nextworks add data` which copies the files listed in `cli/cli_manifests/data_manifest.json` into your project and merges `package-deps.json` entries.
+- Auto-install: when running the command the CLI ensures Forms and Auth are installed first (auto-installs them if missing).
+- Manifest: keep cli_manifests/data_manifest.json and the files in this kit folder in sync — the CLI uses the manifest to know which files to copy.
+- Packaging: the kit includes package-deps.json and is included in the CLI distribution tarball (dist/kits/data). When the CLI package is built/packed it will include the standalone Data kit files.
+
+Caveats & tips
+
+- The kit is intended as example/demo code — consumers should review and adapt for production use (security, RBAC rules, validation, etc.).
+- If you want the CLI to prompt before installing Auth/Forms instead of auto-installing, open an issue or request the interactive behavior; it can be added.
+- If you want a timestamped or additional tarball build, the CLI packing step can be re-run to produce another artifact.
+
+CLI manifest
+
+- In the Nextworks repo, the CLI copies files listed in `cli/cli_manifests/data_manifest.json`. Keep that manifest and this kit folder in sync when editing the repo.

package/dist/kits/forms/.nextworks/docs/FORMS_QUICKSTART.md

@@ -0,0 +1,84 @@
+# Forms Quickstart — Example page
+
+This short doc points to the minimal example that demonstrates how to use the Forms primitives with Select, Checkbox and Switch components. It also documents the ApiResult pattern for mapping server field errors into react-hook-form and points to the per-field async validation helper used in the signup form.
+
+> To add these examples and primitives to your own app via the CLI, the recommended alpha setup is to install Blocks with sections and templates first, then Forms:
+>
+> ```bash
+> npx nextworks add blocks --sections --templates
+> npx nextworks add forms
+> ```
+>
+> The CLI will copy the Forms primitives and example pages into your `components/ui/form/*`, `components/hooks/`, `lib/validation/*`, and `app/examples/forms/*` directories.
+
+Where to find the example
+
+- Example page: /examples/forms/basic
+  - Full path in repo: app/examples/forms/basic/page.tsx
+
+What the example shows
+
+- react-hook-form + zodResolver integration using the project's Form primitives
+- Usage of Select, Checkbox and Switch UI components with FormField (which uses RHF Controller under the hood)
+- A minimal submit handler (client-side) you can copy/replace with your API call
+
+How to try it locally
+
+1. Start the dev server:
+   npm run dev
+2. Open your browser and visit:
+   http://localhost:3000/examples/forms/basic
+
+Note: Some examples that hit the server (such as the wizard/server-action flows) assume you have a Prisma schema and database configured in your app, often via Auth Core/Data. If you haven’t set that up yet, expect those examples to need additional setup.
+
+Tip: If you change the Prisma schema, run:
+npx prisma generate
+npx prisma migrate dev
+
+Copy/paste tips for your app
+
+- Import Form primitives and controls from:
+  - components/ui/form/\* (Form, FormField, FormItem, FormLabel, FormControl, FormMessage)
+  - components/ui/select.tsx, components/ui/checkbox.tsx, components/ui/switch.tsx
+- The example shows how to forward checkbox/switch changes to RHF by using f.onChange(e.target.checked) and setting checked={!!f.value}.
+
+If you want the example to submit to your API, replace the onSubmit handler's console/alert with a fetch() call or server action.
+
+---
+
+Kit manifest & files (for packaging)
+
+If you plan to package a Forms kit (CLI or manual copy), here are the primary files used by the examples and primitives. This manifest is for documentation and packaging reference.
+
+Files
+
+- components/ui/form/form.tsx
+- components/ui/form/form-field.tsx
+- components/ui/form/form-item.tsx
+- components/ui/form/form-control.tsx
+- components/ui/form/form-description.tsx
+- components/ui/form/form-label.tsx
+- components/ui/form/form-message.tsx
+- components/ui/select.tsx
+- components/ui/checkbox.tsx
+- components/ui/switch.tsx
+- components/hooks/useCheckUnique.ts
+- lib/validation/forms.ts
+- lib/validation/wizard.ts
+- lib/forms/map-errors.ts
+- app/examples/forms/basic/page.tsx
+- app/examples/forms/server-action/page.tsx
+- app/examples/forms/server-action/form-client.tsx
+- app/examples/forms/wizard/wizard-client.tsx
+- app/examples/forms/wizard/page.tsx
+
+API routes (used by examples)
+
+- app/api/wizard/route.ts
+
+Notes
+
+- The Forms primitives are UI-only and do not require Prisma or NextAuth to function. The server-action example and the mapping helper demonstrate how to validate server-side and map errors back to react-hook-form.
+- If you are packaging the kit, consider copying only components/ui/form/\* and the select/checkbox/switch files, plus the example pages if you want to keep the demo pages.
+
+If you want, I can create docs/FORMS_MANIFEST.json in the repo with the above manifest for the CLI packaging step.

package/dist/kits/forms/.nextworks/docs/FORMS_README.md

@@ -0,0 +1,60 @@
+Forms kit (cli/kits/forms)
+
+This folder contains the files that the `nextworks` CLI copies into a target Next.js project when you run:
+
+```bash
+npx nextworks add forms
+```
+
+What the kit includes
+
+- Form primitives built on React Hook Form + Zod: components/ui/form/\*
+- Select / Checkbox / Switch primitives wired for form usage
+- Shared validation schemas: lib/validation/forms.ts and lib/validation/wizard.ts
+- Form error mapping helper: lib/forms/map-errors.ts
+- Example pages:
+  - Basic form: app/examples/forms/basic/page.tsx
+  - Server action form: app/examples/forms/server-action/page.tsx and form-client.tsx
+  - Wizard example: app/examples/forms/wizard/page.tsx and wizard-client.tsx
+- Wizard API route: app/api/wizard/route.ts
+
+Notes
+
+- The forms primitives are UI-only and do not require Prisma or NextAuth.
+- The wizard example assumes a basic app/api/wizard/route.ts endpoint; adjust it as needed for your project.
+- Keep this kit folder in sync with cli_manifests/forms_manifest.json.
+
+> **Alpha note**
+>
+> In this early alpha, Forms is tested on top of a **Blocks** install that includes sections and templates. For the smoothest experience, install Blocks first:
+>
+> ```bash
+> npx nextworks add blocks --sections --templates
+> npx nextworks add forms
+> ```
+>
+> Using Forms without Blocks may work but can require manual tweaks (for example around shared UI primitives).
+
+Post-install steps (recommended)
+
+1. Install dependencies (the CLI will merge `package-deps.json` into your `package.json`):
+
+   ```bash
+   npm install
+   ```
+
+2. Ensure you have React Hook Form and Zod installed (if not already present). The CLI will attempt to add these via `package-deps.json`.
+
+3. Start your dev server and explore the examples:
+
+   ```bash
+   npm run dev
+   ```
+
+   - /examples/forms/basic
+   - /examples/forms/server-action
+   - /examples/forms/wizard
+
+CLI behavior (for maintainers)
+
+- In the Nextworks repo, the CLI copies the files listed in `cli/cli_manifests/forms_manifest.json`. Keep that manifest and this kit folder in sync when editing the repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nextworks",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Nextworks CLI - Feature kits installer for Next.js apps",
   "main": "dist/index.js",
   "bin": {