create-nextblock 0.15.10 → 0.16.2

package/templates/nextblock-template/docs/01-PROJECT-OVERVIEW.md

@@ -1,94 +1,94 @@
-# 01 Project Overview
-
-## What NextBlock Is
-
-NextBlock is an Nx monorepo centered on a Next.js 16 application
-(`apps/nextblock`) backed by Supabase. The public site, authenticated CMS,
-shared editor, shared database helpers, shared UI primitives, and CLI scaffold
-all live in one workspace.
-
-The repository currently contains:
-
-- `apps/nextblock`: the canonical application. This is the runtime source of
-  truth for the public site, CMS, checkout routes, cron routes, and auth
-  callback behavior.
-- `apps/create-nextblock`: the CLI that copies a sanitized template from the
-  source app and rewrites it for package-based distribution.
-- `libs/db`: Supabase clients, package activation checks, generated database
-  types, and the migration tree under `libs/db/src/supabase/migrations`.
-- `libs/editor`: the reusable Tiptap-based editor package used by the CMS and
-  by scaffolded projects.
-- `libs/ecommerce`: the premium commerce package that provides storefront UI,
-  checkout providers, order handling, shipping, tax, currency, and CMS pages.
-- `libs/sdk`: the block authoring contract used for typed extensibility.
-- `libs/ui` and `libs/utils`: shared UI components, styles, and helper
-  utilities consumed throughout the workspace.
-
-## Runtime Model
-
-The `apps/nextblock/app` tree is split into a few clear surfaces:
-
-- Public routes: `app/[slug]`, `app/article/[slug]`, `app/product/*`,
-  `app/cart`, `app/checkout`, and the shared public `app/layout.tsx`.
-- Auth routes: `app/(auth-pages)/*` plus `app/auth/callback/route.ts`.
-- CMS routes: `app/cms/*`.
-- Operational routes: `app/api/checkout/route.ts`,
-  `app/api/webhooks/*`, `app/api/cron/*`, `robots.txt`, and `sitemap.xml`.
-
-The public root layout loads shared UI and editor styles, resolves cached
-layout data from Supabase, injects the storefront cart drawer, and reads the
-storefront currency cookie. The CMS layout checks whether the ecommerce package
-is active so the client-side CMS shell can show or hide store navigation.
-
-## CMS and Public Site Split
-
-The public application and CMS are not separate projects. They share the same
-Next.js app and database, but expose different route groups and different
-authorization requirements:
-
-- Public content is driven by published pages, posts, navigation, products, and
-  translations stored in Supabase.
-- CMS routes are guarded in the client layout and expect an authenticated user
-  whose profile role is `ADMIN` or `WRITER`.
-- Commerce CMS routes such as products, orders, shipping, taxes, and payments
-  are only meaningful when the ecommerce package is active.
-
-## Package Activation Gating
-
-Premium functionality is gated through `package_activations` and
-`verifyPackageOnline()` in `libs/db/src/lib/package-validation.ts`.
-
-Today that gate is used directly in the app for things like:
-
-- CMS ecommerce navigation visibility.
-- The checkout API.
-- Premium route wrappers and CLI module activation flows.
-
-If a package gate and the actual route behavior disagree, the route file wins.
-
-## Nx Workspace Shape
-
-Nx is used for project graph management, builds, linting, Vite-based library
-output, and Next.js app targets. A few practical notes matter when navigating
-the repo:
-
-- `nextblock` is the main application target.
-- Public libraries such as `db`, `editor`, `sdk`, `ui`, and `utils` are normal
-  Nx projects.
-- `ecommerce` is an Nx library tagged `scope:premium`.
-- The scaffold template under
-  `apps/create-nextblock/templates/nextblock-template` is intentionally copied
-  output, not a normal Nx project.
-
-## Where to Start
-
-- For overall architecture: read [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
-  after this file.
-- For day-to-day setup and commands: read
-  [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md).
-- For CLI behavior and template sync: read
-  [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md).
-- For editor and block work: read
-  [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md).
-- For commerce work: read
-  [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md).
+# 01 Project Overview
+
+## What NextBlock Is
+
+NextBlock is an Nx monorepo centered on a Next.js 16 application
+(`apps/nextblock`) backed by Supabase. The public site, authenticated CMS,
+shared editor, shared database helpers, shared UI primitives, and CLI scaffold
+all live in one workspace.
+
+The repository currently contains:
+
+- `apps/nextblock`: the canonical application. This is the runtime source of
+  truth for the public site, CMS, checkout routes, cron routes, and auth
+  callback behavior.
+- `apps/create-nextblock`: the CLI that copies a sanitized template from the
+  source app and rewrites it for package-based distribution.
+- `libs/db`: Supabase clients, package activation checks, generated database
+  types, and the migration tree under `libs/db/src/supabase/migrations`.
+- `libs/editor`: the reusable Tiptap-based editor package used by the CMS and
+  by scaffolded projects.
+- `libs/ecommerce`: the premium commerce package that provides storefront UI,
+  checkout providers, order handling, shipping, tax, currency, and CMS pages.
+- `libs/sdk`: the block authoring contract used for typed extensibility.
+- `libs/ui` and `libs/utils`: shared UI components, styles, and helper
+  utilities consumed throughout the workspace.
+
+## Runtime Model
+
+The `apps/nextblock/app` tree is split into a few clear surfaces:
+
+- Public routes: `app/[slug]`, `app/article/[slug]`, `app/product/*`,
+  `app/cart`, `app/checkout`, and the shared public `app/layout.tsx`.
+- Auth routes: `app/(auth-pages)/*` plus `app/auth/callback/route.ts`.
+- CMS routes: `app/cms/*`.
+- Operational routes: `app/api/checkout/route.ts`,
+  `app/api/webhooks/*`, `app/api/cron/*`, `robots.txt`, and `sitemap.xml`.
+
+The public root layout loads shared UI and editor styles, resolves cached
+layout data from Supabase, injects the storefront cart drawer, and reads the
+storefront currency cookie. The CMS layout checks whether the ecommerce package
+is active so the client-side CMS shell can show or hide store navigation.
+
+## CMS and Public Site Split
+
+The public application and CMS are not separate projects. They share the same
+Next.js app and database, but expose different route groups and different
+authorization requirements:
+
+- Public content is driven by published pages, posts, navigation, products, and
+  translations stored in Supabase.
+- CMS routes are guarded in the client layout and expect an authenticated user
+  whose profile role is `ADMIN` or `WRITER`.
+- Commerce CMS routes such as products, orders, shipping, taxes, and payments
+  are only meaningful when the ecommerce package is active.
+
+## Package Activation Gating
+
+Premium functionality is gated through `package_activations` and
+`verifyPackageOnline()` in `libs/db/src/lib/package-validation.ts`.
+
+Today that gate is used directly in the app for things like:
+
+- CMS ecommerce navigation visibility.
+- The checkout API.
+- Premium route wrappers and CLI module activation flows.
+
+If a package gate and the actual route behavior disagree, the route file wins.
+
+## Nx Workspace Shape
+
+Nx is used for project graph management, builds, linting, Vite-based library
+output, and Next.js app targets. A few practical notes matter when navigating
+the repo:
+
+- `nextblock` is the main application target.
+- Public libraries such as `db`, `editor`, `sdk`, `ui`, and `utils` are normal
+  Nx projects.
+- `ecommerce` is an Nx library tagged `scope:premium`.
+- The scaffold template under
+  `apps/create-nextblock/templates/nextblock-template` is intentionally copied
+  output, not a normal Nx project.
+
+## Where to Start
+
+- For overall architecture: read [04-DATABASE-AND-AUTH.md](./04-DATABASE-AND-AUTH.md)
+  after this file.
+- For day-to-day setup and commands: read
+  [05-DEVELOPER-GUIDE.md](./05-DEVELOPER-GUIDE.md).
+- For CLI behavior and template sync: read
+  [06-CLI-AND-SCAFFOLDING.md](./06-CLI-AND-SCAFFOLDING.md).
+- For editor and block work: read
+  [03-CMS-AND-EDITOR.md](./03-CMS-AND-EDITOR.md).
+- For commerce work: read
+  [02-ECOMMERCE-CAPABILITIES.md](./02-ECOMMERCE-CAPABILITIES.md).

package/templates/nextblock-template/docs/03-CMS-AND-EDITOR.md

@@ -200,80 +200,80 @@ contract lives in `libs/sdk` and is documented in
 
 If you are changing how blocks work inside the CMS, start here. If you are
 designing a reusable third-party block contract, start with the SDK doc.
-
-## Themes and Colour
-
-### Editable site themes
-
-Themes are rows in `site_themes`, edited at **/cms/settings/global-css**. An
-ADMIN can recolour any theme, create new ones, duplicate, reorder, hide, set the
-site default, and delete non-system themes.
-
-The pipeline is:
-
-1. `app/layout.tsx` reads the table through a cached `getCachedSiteThemes()`
-   (tag `public-layout-site-themes`).
-2. `lib/themes/buildThemeCss.ts` renders each row to a `:root.<slug> { ... }`
-   rule, injected as a `<style id="nb-theme-tokens">` in `<head>` — before the
-   Global CSS box, so custom CSS can still override a theme.
-3. `app/providers.tsx` feeds the slug list and default to `next-themes`, and
-   `context/ThemeCatalogContext.tsx` carries names + icons to the switcher.
-
-`libs/ui/src/styles/theme.css` remains as the fallback palette for standalone
-consumers of the published `@nextblock-cms/ui` package. Generated rules use
-`:root.<slug>` (specificity 0,2,0) so they always beat that file's `.dark` /
-`.vibrant` rules (0,1,0) regardless of stylesheet order.
-
-### Token storage
-
-Colour tokens are stored as **bare HSL triplets** (`"222 47% 11%"`), not hex,
-because `libs/ui/tailwind.config.js` composes them as `hsl(var(--primary))` and
-appends alpha as `hsl(var(--primary) / 0.5)` — only a bare triplet supports
-that. `lib/themes/tokenColor.ts` converts to and from the hex the colour picker
-speaks. The allowed token list lives in `lib/themes/tokens.ts`; anything not on
-it is dropped on save, and values are shape-checked, because the result is
-interpolated into a `<style>` tag.
-
-Per-theme `extra_css` is emitted **nested inside** the theme rule, so authors
-write `& h1 { ... }` and scoping is automatic. `sanitizeExtraCss()` strips `<`
-and unbalanced `}` so it cannot escape the rule or close the style element.
-
-### Known limitation: `dark:` utilities under custom themes
-
-Tailwind's dark variant compiles to `.dark`, and `darkMode: ['class']` is fixed
-at build time. A custom theme with `color_scheme: 'dark'` recolours every token
-and sets CSS `color-scheme`, but does **not** activate `dark:` utilities — the
-same behaviour the shipped `.vibrant` theme has always had.
-
-It cannot be fixed by mapping the theme to two classes: `next-themes` applies
-its value with a single `classList.add(value)`, and `DOMTokenList.add` throws
-`InvalidCharacterError` on a string containing a space. Wiring `dark:` to a data
-attribute would require a pre-hydration script mirroring next-themes' own.
-
-Verify the database → CSS path without booting the app:
-
-```bash
-npm run verify:site-themes
-```
-
-### Block text colour
-
-`apps/nextblock/lib/blocks/blockColors.ts` is the single source of truth for
-block text colour, shared by `HeadingBlockRenderer`, `EditableBlock` and
-`ColumnEditor` so the CMS preview cannot drift from the live page.
-
-A stored value is either a **theme token** keyword (`"primary"` — follows the
-theme) or a **literal CSS colour** (`"#FF8800"` — fixed). Tokens render as a
-static Tailwind class; literals render as an inline `style`. `resolveTextColor()`
-returns `{ className?, style? }` and falls back to `{}` for anything it does not
-recognise, so a hand-edited value degrades to the inherited colour instead of
-emitting a bogus class.
-
-Class names here are written as **complete literals**. Tailwind v4 ignores the
-`safelist` key in the legacy JS config — `libs/ui/tailwind.config.js` still
-carries one, but v4 never reads it, so a class exists only if the scanner finds
-the whole string in a source file.
-
-The editor control is `ColorField` from `libs/ui`, which offers the theme tokens
-and a custom picker (hex, alpha, screen eyedropper, recent colours) with a live
-WCAG contrast badge measured against the section background.
+
+## Themes and Colour
+
+### Editable site themes
+
+Themes are rows in `site_themes`, edited at **/cms/settings/global-css**. An
+ADMIN can recolour any theme, create new ones, duplicate, reorder, hide, set the
+site default, and delete non-system themes.
+
+The pipeline is:
+
+1. `app/layout.tsx` reads the table through a cached `getCachedSiteThemes()`
+   (tag `public-layout-site-themes`).
+2. `lib/themes/buildThemeCss.ts` renders each row to a `:root.<slug> { ... }`
+   rule, injected as a `<style id="nb-theme-tokens">` in `<head>` — before the
+   Global CSS box, so custom CSS can still override a theme.
+3. `app/providers.tsx` feeds the slug list and default to `next-themes`, and
+   `context/ThemeCatalogContext.tsx` carries names + icons to the switcher.
+
+`libs/ui/src/styles/theme.css` remains as the fallback palette for standalone
+consumers of the published `@nextblock-cms/ui` package. Generated rules use
+`:root.<slug>` (specificity 0,2,0) so they always beat that file's `.dark` /
+`.vibrant` rules (0,1,0) regardless of stylesheet order.
+
+### Token storage
+
+Colour tokens are stored as **bare HSL triplets** (`"222 47% 11%"`), not hex,
+because `libs/ui/tailwind.config.js` composes them as `hsl(var(--primary))` and
+appends alpha as `hsl(var(--primary) / 0.5)` — only a bare triplet supports
+that. `lib/themes/tokenColor.ts` converts to and from the hex the colour picker
+speaks. The allowed token list lives in `lib/themes/tokens.ts`; anything not on
+it is dropped on save, and values are shape-checked, because the result is
+interpolated into a `<style>` tag.
+
+Per-theme `extra_css` is emitted **nested inside** the theme rule, so authors
+write `& h1 { ... }` and scoping is automatic. `sanitizeExtraCss()` strips `<`
+and unbalanced `}` so it cannot escape the rule or close the style element.
+
+### Known limitation: `dark:` utilities under custom themes
+
+Tailwind's dark variant compiles to `.dark`, and `darkMode: ['class']` is fixed
+at build time. A custom theme with `color_scheme: 'dark'` recolours every token
+and sets CSS `color-scheme`, but does **not** activate `dark:` utilities — the
+same behaviour the shipped `.vibrant` theme has always had.
+
+It cannot be fixed by mapping the theme to two classes: `next-themes` applies
+its value with a single `classList.add(value)`, and `DOMTokenList.add` throws
+`InvalidCharacterError` on a string containing a space. Wiring `dark:` to a data
+attribute would require a pre-hydration script mirroring next-themes' own.
+
+Verify the database → CSS path without booting the app:
+
+```bash
+npm run verify:site-themes
+```
+
+### Block text colour
+
+`apps/nextblock/lib/blocks/blockColors.ts` is the single source of truth for
+block text colour, shared by `HeadingBlockRenderer`, `EditableBlock` and
+`ColumnEditor` so the CMS preview cannot drift from the live page.
+
+A stored value is either a **theme token** keyword (`"primary"` — follows the
+theme) or a **literal CSS colour** (`"#FF8800"` — fixed). Tokens render as a
+static Tailwind class; literals render as an inline `style`. `resolveTextColor()`
+returns `{ className?, style? }` and falls back to `{}` for anything it does not
+recognise, so a hand-edited value degrades to the inherited colour instead of
+emitting a bogus class.
+
+Class names here are written as **complete literals**. Tailwind v4 ignores the
+`safelist` key in the legacy JS config — `libs/ui/tailwind.config.js` still
+carries one, but v4 never reads it, so a class exists only if the scanner finds
+the whole string in a source file.
+
+The editor control is `ColorField` from `libs/ui`, which offers the theme tokens
+and a custom picker (hex, alpha, screen eyedropper, recent colours) with a live
+WCAG contrast badge measured against the section background.