create-momentum-app 0.5.3 → 0.5.5

package/README.md

@@ -32,3 +32,4 @@ npx create-momentum-app my-app --flavor angular --database postgres
 - Drizzle ORM with PostgreSQL or SQLite
 - Docker Compose setup for PostgreSQL (when using postgres)
 - Tailwind CSS with the Momentum admin theme
+- Project-local Claude Code skills under `.claude/skills`, including `headless-ui` for custom app UI built on `@momentumcms/headless`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-momentum-app",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Create a new Momentum CMS application",
   "license": "MIT",
   "author": "Momentum CMS Contributors",

package/templates/analog/src/server/utils/momentum-init.ts.tmpl

@@ -2,6 +2,7 @@ import 'dotenv/config';
 import {
 	initializeMomentumAPI,
 	registerWebhookHooks,
+	syncDatabaseSchema,
 } from '@momentumcms/server-core';
 import { initializeMomentumLogger, createLogger } from '@momentumcms/logger';
 import { PluginRunner } from '@momentumcms/plugins-core';
@@ -44,19 +45,7 @@ async function initialize(): Promise<void> {
 
 	registerWebhookHooks(momentumConfig.collections);
 
-	if (momentumConfig.db.adapter.initialize) {
-		log.info('Initializing database schema...');
-		await momentumConfig.db.adapter.initialize(momentumConfig.collections);
-	}
-
-	if (
-		momentumConfig.db.adapter.initializeGlobals &&
-		momentumConfig.globals &&
-		momentumConfig.globals.length > 0
-	) {
-		log.info(`Initializing globals table for ${momentumConfig.globals.length} global(s)...`);
-		await momentumConfig.db.adapter.initializeGlobals(momentumConfig.globals);
-	}
+	await syncDatabaseSchema(momentumConfig, log);
 
 	log.info('Initializing API...');
 	const api = initializeMomentumAPI(momentumConfig);

package/templates/shared/.claude/agents.md

@@ -17,16 +17,17 @@ Momentum CMS is a headless CMS built with Angular. You define collections in Typ
 
 ## Available Skills
 
-| Skill                  | Usage                          | Description                                                      |
-| ---------------------- | ------------------------------ | ---------------------------------------------------------------- |
-| `/collection <name>`   | `/collection products`         | Generate a new collection with fields, access control, and hooks |
-| `/momentum-api <op>`   | `/momentum-api crud posts`     | Guide for using `injectMomentumAPI()` in Angular components      |
-| `/add-plugin <name>`   | `/add-plugin analytics`        | Add and configure a Momentum CMS plugin                          |
-| `/admin-config <what>` | `/admin-config field-renderer` | Wire admin routes, plugin imports, and custom field renderers    |
-| `/api-route <name>`    | `/api-route health`            | Generate API route handlers for Express or Analog.js             |
-| `/component <name>`    | `/component post-card`         | Generate an Angular component with signals and OnPush            |
-| `/e2e-test <feature>`  | `/e2e-test posts`              | Write Playwright E2E tests (dashboard-first, no blind tests)     |
-| `/migrations <op>`     | `/migrations generate`         | Run migrations, generate schemas, and manage code generation     |
+| Skill                     | Usage                          | Description                                                      |
+| ------------------------- | ------------------------------ | ---------------------------------------------------------------- |
+| `/collection <name>`      | `/collection products`         | Generate a new collection with fields, access control, and hooks |
+| `/momentum-api <op>`      | `/momentum-api crud posts`     | Guide for using `injectMomentumAPI()` in Angular components      |
+| `/add-plugin <name>`      | `/add-plugin analytics`        | Add and configure a Momentum CMS plugin                          |
+| `/admin-config <what>`    | `/admin-config field-renderer` | Wire admin routes, plugin imports, and custom field renderers    |
+| `/admin-customize <what>` | `/admin-customize slot`        | Swappable pages, layout slots, per-collection overrides          |
+| `/api-route <name>`       | `/api-route health`            | Generate API route handlers for Express or Analog.js             |
+| `/component <name>`       | `/component post-card`         | Generate an Angular component with signals and OnPush            |
+| `/e2e-test <feature>`     | `/e2e-test posts`              | Write Playwright E2E tests (dashboard-first, no blind tests)     |
+| `/migrations <op>`        | `/migrations generate`         | Run migrations, generate schemas, and manage code generation     |
 
 ## Common Workflows
 

package/templates/shared/.claude/skills/admin-config/SKILL.md

@@ -46,6 +46,12 @@ browserImports: {
 }
 ```
 
+### Component loaders in generated config
+
+The generator emits `admin.components` (global) and per-collection `admin.components` as lazy-loading functions with rewritten import paths. This means `momentum.config.ts` is the single source of truth for page overrides and layout slots.
+
+For swappable pages and layout slots, see `/admin-customize`.
+
 ## Custom Field Renderers
 
 Field renderers are lazily loaded via `FieldRendererRegistry`. Built-in renderers are registered with `provideMomentumFieldRenderers()`.

package/templates/shared/.claude/skills/admin-customize/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: admin-customize
+description: Customize the admin UI with swappable pages and layout slots. Use when replacing built-in pages (dashboard, list, edit, view), injecting content into layout slots (header, footer, sidebar, before/after), or registering per-collection overrides.
+argument-hint: <page-override|slot|per-collection>
+---
+
+# Admin Customization — Swappable Pages & Layout Slots
+
+Guide for customizing the Momentum CMS admin UI via page replacements and layout slot injection.
+
+## Arguments
+
+- `$ARGUMENTS` - What to customize: `page-override`, `slot`, or `per-collection`
+
+## Two Registration Methods
+
+### 1. Config-level (momentum.config.ts)
+
+Registered in the server config. The code generator emits these as loader functions in the browser-safe generated config. This is the recommended approach — single source of truth.
+
+After changes, run: `npm run generate`
+
+### 2. Provider-level (app.config.ts)
+
+Registered via Angular DI providers. Takes effect immediately, no generation needed. Useful for app-specific customizations or login page slots.
+
+## Swappable Pages (Full Replacement)
+
+### Available Page Keys
+
+| Key               | Built-in Page   |
+| ----------------- | --------------- |
+| `dashboard`       | Dashboard       |
+| `login`           | Login           |
+| `media`           | Media Library   |
+| `collection-list` | Collection List |
+| `collection-edit` | Collection Edit |
+| `collection-view` | Collection View |
+| `global-edit`     | Global Edit     |
+
+### Config-level (momentum.config.ts)
+
+```typescript
+admin: {
+	components: {
+		dashboard: () =>
+			import('./app/custom-dashboard.component').then((m) => m.CustomDashboard),
+	},
+},
+```
+
+### Provider-level (app.config.ts)
+
+```typescript
+import { provideAdminComponent } from '@momentumcms/admin';
+
+providers: [
+	provideAdminComponent('dashboard', () =>
+		import('./custom-dashboard.component').then((m) => m.CustomDashboard),
+	),
+],
+```
+
+### Per-Collection Page Overrides
+
+Override pages for a specific collection only:
+
+#### Config-level (on collection admin.components)
+
+```typescript
+admin: {
+	components: {
+		list: () => import('./custom-articles-list.component').then((m) => m.CustomArticlesList),
+	},
+},
+```
+
+#### Provider-level
+
+```typescript
+provideAdminComponent('collections/articles/list', () =>
+	import('./custom-articles-list.component').then((m) => m.CustomArticlesList),
+);
+```
+
+### Resolution Chain
+
+1. Per-collection override (`collections/{slug}/{type}`)
+2. Global override (`collection-list`)
+3. Built-in default
+
+## Layout Slots (Additive Injection)
+
+Slots inject content around existing pages. Multiple components can register for the same slot.
+
+### Available Slots
+
+| Slot Key                               | Position                        |
+| -------------------------------------- | ------------------------------- |
+| `shell:header`                         | Top of main content area        |
+| `shell:footer`                         | Bottom of main content area     |
+| `shell:nav-start`                      | After Dashboard link in sidebar |
+| `shell:nav-end`                        | After plugin routes in sidebar  |
+| `dashboard:before/after`               | Around dashboard content        |
+| `collection-list:before/after`         | Around list tables              |
+| `collection-edit:before/after/sidebar` | Around edit forms               |
+| `collection-view:before/after`         | Around view pages               |
+| `login:before/after`                   | Around login form               |
+
+### Config-level (momentum.config.ts — admin.components)
+
+| Config Key         | Slot Position      |
+| ------------------ | ------------------ |
+| `beforeNavigation` | `shell:nav-start`  |
+| `afterNavigation`  | `shell:nav-end`    |
+| `header`           | `shell:header`     |
+| `footer`           | `shell:footer`     |
+| `beforeDashboard`  | `dashboard:before` |
+| `afterDashboard`   | `dashboard:after`  |
+| `beforeLogin`      | `login:before`     |
+| `afterLogin`       | `login:after`      |
+
+```typescript
+admin: {
+	components: {
+		beforeDashboard: () =>
+			import('./app/announcement-banner.component').then((m) => m.AnnouncementBanner),
+		footer: () =>
+			import('./app/custom-footer.component').then((m) => m.CustomFooter),
+	},
+},
+```
+
+### Per-collection config keys
+
+`beforeList`, `afterList`, `beforeEdit`, `afterEdit`, `editSidebar`, `beforeView`, `afterView`
+
+### Provider-level (app.config.ts)
+
+```typescript
+import { provideAdminSlot } from '@momentumcms/admin';
+
+providers: [
+	provideAdminSlot('shell:header', () =>
+		import('./env-banner.component').then((m) => m.EnvBanner),
+	),
+	// Per-collection:
+	provideAdminSlot('collection-list:before:articles', () =>
+		import('./articles-filter.component').then((m) => m.ArticlesFilter),
+	),
+],
+```
+
+## Component Template
+
+```typescript
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
+import type { CollectionConfig } from '@momentumcms/core';
+
+@Component({
+	selector: 'app-custom-slot',
+	host: { class: 'block' },
+	template: `
+		<div class="p-4 bg-mcms-muted rounded-lg">
+			@if (collection(); as col) {
+				<p>Collection: {{ col.slug }}</p>
+			}
+		</div>
+	`,
+	changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class CustomSlotComponent {
+	readonly collection = input<CollectionConfig>();
+	readonly entityId = input<string>();
+}
+```
+
+## Exports from @momentumcms/admin
+
+```typescript
+import {
+	provideAdminComponent, // Register page override via DI
+	provideAdminSlot, // Register slot component via DI
+} from '@momentumcms/admin';
+```

package/templates/shared/.claude/skills/headless-ui/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: headless-ui
+description: Use @momentumcms/headless inside generated Momentum apps. Use when building custom public UI, composing accessible primitives, configuring global styles for hdl-* elements, or adding app-level tests around headless interactions.
+argument-hint: <feature-or-primitive>
+---
+
+# Use Headless UI In Generated Apps
+
+Use this skill when a generated app needs custom UI built on `@momentumcms/headless`.
+
+## Prefer Headless For
+
+- Public-facing UI that should not look like the admin
+- App-specific design systems that still need solid keyboard and ARIA behavior
+- Custom menus, dialogs, comboboxes, chips, tabs, and form fields
+
+Use `@momentumcms/admin` when you want the built-in admin screens instead of custom surfaces.
+
+## Workflow
+
+1. Import the needed primitive classes into the Angular component that renders them.
+2. Style them from `src/styles.css` or your global Tailwind layer, not from the library.
+3. Target `data-slot`, `data-state`, `data-disabled`, and overlay classes such as `.hdl-dialog-panel`.
+4. Add visible state readouts for important interactions so browser tests can prove the UI intention.
+5. Update app routes or showcase pages if you are adding a reusable demo surface.
+
+## Styling Rules
+
+- Start with design tokens in `@layer base`.
+- Add shared recipes in `@layer components`.
+- Use host `class=""` only for local one-off overrides.
+- For projected child visuals, style the child markup you render inside the primitive.
+- Keep `[hidden]` behavior intact for slots that collapse or unmount visually.
+
+## Example Shape
+
+```typescript
+import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
+import { HdlCombobox, HdlComboboxInput, HdlComboboxPopup, HdlOption } from '@momentumcms/headless';
+
+@Component({
+	selector: 'app-filter-combobox',
+	imports: [HdlCombobox, HdlComboboxInput, HdlComboboxPopup, HdlOption],
+	template: `
+		<hdl-combobox [value]="selected()" (valueChange)="selected.set($event)">
+			<input hdlComboboxInput [value]="query()" (input)="query.set(search.value)" #search />
+			<hdl-combobox-popup>
+				@for (item of filteredItems(); track item) {
+					<hdl-option [value]="item">{{ item }}</hdl-option>
+				}
+			</hdl-combobox-popup>
+		</hdl-combobox>
+
+		<p>Selected: {{ selected() || 'none' }}</p>
+	`,
+	changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class FilterComboboxComponent {
+	readonly items = ['Articles', 'Pages', 'Authors', 'Media'];
+	readonly query = signal('');
+	readonly selected = signal('');
+	readonly filteredItems = computed(() => {
+		const query = this.query().trim().toLowerCase();
+		return query ? this.items.filter((item) => item.toLowerCase().includes(query)) : this.items;
+	});
+}
+```
+
+## Test Expectations
+
+- Unit tests should cover app-specific state mapping and conditional rendering.
+- Browser tests should assert the intended behavior, not just the presence of `hdl-*` tags.
+- Good assertions: combobox filtering works, menu clicks update the readout, chips remove correctly, dialog actions dismiss as expected.
+
+## If You Need More Than Consumption
+
+If the app task actually requires changing the library itself, switch to the repo skill for maintaining `libs/headless` instead of patching around the library from the app.