@forgewp/compiler 0.4.3 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (133) hide show
  1. package/README.md +59 -0
  2. package/bin/add.js +20 -14
  3. package/bin/cli.js +145 -70
  4. package/bin/doctor.js +21 -12
  5. package/bin/export.js +69 -20
  6. package/bin/fresh.js +5 -0
  7. package/bin/i18n-extract.js +3 -10
  8. package/bin/i18n-translate.js +15 -24
  9. package/bin/make-block.js +13 -0
  10. package/bin/make-editable.js +166 -0
  11. package/bin/make-form.js +131 -0
  12. package/bin/make-loop.js +40 -43
  13. package/bin/make-mail.js +27 -0
  14. package/bin/make-post-type.js +57 -29
  15. package/bin/make-sandbox.js +62 -11
  16. package/bin/make-section.js +221 -0
  17. package/bin/make-shell.js +375 -0
  18. package/bin/repair.js +14 -26
  19. package/bin/seed.js +119 -0
  20. package/bin/sync-routes.js +107 -85
  21. package/lib/adapters/html-adapter.js +5 -0
  22. package/lib/adapters/stub-adapter.js +4 -0
  23. package/lib/add-component.js +153 -92
  24. package/lib/asset-loader.js +313 -3
  25. package/lib/assets/asset-graph.js +432 -0
  26. package/lib/assets/asset-pipeline.js +125 -0
  27. package/lib/assets/diagnostics-report.js +345 -0
  28. package/lib/assets/external-fetcher.js +173 -0
  29. package/lib/assets/font-orchestrator.js +348 -0
  30. package/lib/assets/font-usage-scanner.js +242 -0
  31. package/lib/assets/image-optimizer.js +229 -0
  32. package/lib/assets/index.js +51 -0
  33. package/lib/assets/preload-generator.js +70 -0
  34. package/lib/assets/public-url.js +153 -0
  35. package/lib/block-authoring-help.js +11 -0
  36. package/lib/blocks/ast-parser.js +67 -0
  37. package/lib/blocks/discover-blocks.js +146 -0
  38. package/lib/blocks/editor-scope.js +733 -0
  39. package/lib/blocks/editor-transpiler.js +1229 -0
  40. package/lib/blocks/index.js +2838 -0
  41. package/lib/blocks/php-transpiler.js +4928 -0
  42. package/lib/blocks/scanner.js +1487 -0
  43. package/lib/blocks/shared-utils.js +290 -0
  44. package/lib/blocks/source-sanitize.js +1449 -0
  45. package/lib/blueprints.js +31 -91
  46. package/lib/build-assets.js +38 -33
  47. package/lib/collect-page-template-routes.js +102 -0
  48. package/lib/collect-static-routes.js +175 -0
  49. package/lib/diagnostics.js +58 -33
  50. package/lib/export-theme.js +84 -5
  51. package/lib/extract-template-content.js +90 -0
  52. package/lib/forms-preview.js +42 -0
  53. package/lib/functions/cpt-routing.js +69 -0
  54. package/lib/functions/forms.js +2461 -0
  55. package/lib/functions/hydration-enqueuer.js +400 -0
  56. package/lib/functions/index.js +1623 -0
  57. package/lib/functions/load-menus.js +112 -0
  58. package/lib/functions/load-translations.js +148 -0
  59. package/lib/functions/rest-endpoints.js +2923 -0
  60. package/lib/functions/routing.js +765 -0
  61. package/lib/functions/seed-mock-data.js +392 -0
  62. package/lib/functions/seed-products.js +481 -0
  63. package/lib/functions/settings-page.js +273 -0
  64. package/lib/functions/theme-setup.js +494 -0
  65. package/lib/generate-theme.js +1916 -339
  66. package/lib/hydration/editable-schemas.js +332 -0
  67. package/lib/hydration/enter-hidden-initial.js +65 -0
  68. package/lib/hydration/form-schemas.js +227 -0
  69. package/lib/hydration/index.js +12 -0
  70. package/lib/hydration/is-interactive.js +951 -0
  71. package/lib/hydration/island-split.js +1231 -0
  72. package/lib/hydration/islands-scanner.js +599 -0
  73. package/lib/hydration/resolve-island-chunk.js +103 -0
  74. package/lib/hydration/resolve-island-component.js +52 -0
  75. package/lib/hydration/rollup-inputs.js +81 -0
  76. package/lib/hydration/root-class-extractor.js +220 -0
  77. package/lib/hydration/scan-app-providers.js +154 -0
  78. package/lib/hydration/static-lint.js +382 -0
  79. package/lib/hydration/transform.js +257 -0
  80. package/lib/hydration/uses-block-area.js +49 -0
  81. package/lib/hydration/utils.js +119 -0
  82. package/lib/i18n/translation-cache.js +141 -0
  83. package/lib/icon-registry.js +72 -0
  84. package/lib/index.d.ts +287 -8
  85. package/lib/index.js +2 -1
  86. package/lib/load-config.js +338 -242
  87. package/lib/mail-templates.js +37 -0
  88. package/lib/markup-processor.js +388 -102
  89. package/lib/node-runtime.js +7 -0
  90. package/lib/page-config-plugin.js +64 -20
  91. package/lib/php-builders.js +383 -44
  92. package/lib/react-adapter.js +983 -235
  93. package/lib/registration-metadata.js +11 -0
  94. package/lib/render-theme.mts +1410 -616
  95. package/lib/route-layout.js +76 -0
  96. package/lib/template-discovery.js +58 -0
  97. package/lib/theme-compatibility.js +32 -0
  98. package/lib/validate-export.js +2 -2
  99. package/lib/validate.js +27 -5
  100. package/lib/virtual-plugin.js +319 -0
  101. package/lib/walkthrough.md +26 -0
  102. package/package.json +16 -5
  103. package/templates/auth/cms/email-logs.json +9 -0
  104. package/templates/auth/cms/menus.json +11 -0
  105. package/templates/auth/cms/mock-data.json +123 -0
  106. package/templates/auth/cms/roles.json +7 -0
  107. package/templates/auth/cms/sessions.json +1 -0
  108. package/templates/auth/cms/site-settings.json +28 -0
  109. package/templates/auth/cms/translations.json +4 -0
  110. package/templates/auth/cms/users.json +46 -0
  111. package/templates/auth/components/forgot-password-form-wrapper.tsx +10 -2
  112. package/templates/auth/components/login-form-wrapper.tsx +118 -21
  113. package/templates/auth/components/reset-password-form-wrapper.tsx +10 -2
  114. package/templates/auth/components/signup-form-wrapper.tsx +2 -2
  115. package/templates/auth/components/verify-email-view-wrapper.tsx +5 -5
  116. package/templates/auth/pages/DashboardPage.tsx +1 -4
  117. package/templates/auth/pages/ForgotPasswordPage.tsx +1 -4
  118. package/templates/auth/pages/LoginPage.tsx +1 -4
  119. package/templates/auth/pages/ResetPasswordPage.tsx +1 -4
  120. package/templates/auth/pages/SignUpPage.tsx +1 -4
  121. package/templates/auth/pages/VerifyEmailPage.tsx +1 -4
  122. package/templates/auth/ui/button.tsx +57 -0
  123. package/templates/auth/ui/card.tsx +76 -0
  124. package/templates/auth/ui/field.tsx +242 -0
  125. package/templates/auth/ui/input.tsx +22 -0
  126. package/templates/auth/ui/label.tsx +24 -0
  127. package/templates/auth/ui/separator.tsx +31 -0
  128. package/templates/menus.json +12 -10
  129. package/templates/users.json +8 -4
  130. package/templates/wordpress.tsx +690 -245
  131. package/lib/block-compiler.js +0 -552
  132. package/lib/functions-builder.js +0 -2970
  133. package/lib/hydration-scanner.js +0 -833
package/lib/index.d.ts CHANGED
@@ -18,16 +18,36 @@ export interface FontFamilyPreset {
18
18
 
19
19
  export interface CustomPostTypeConfig {
20
20
  translatable?: boolean;
21
+ icon?: string;
21
22
  labels?: {
22
23
  singular?: string;
23
24
  plural?: string;
24
25
  };
26
+ /** Replaces the default features; [] disables all features (emitted as PHP false). */
27
+ supports?: string[];
28
+ public?: boolean;
29
+ hasArchive?: boolean;
30
+ showInRest?: boolean;
31
+ rewrite?: false | { slug?: string; withFront?: boolean };
32
+ }
33
+
34
+ export interface CustomTaxonomyConfig {
35
+ translatable?: boolean;
36
+ hierarchical?: boolean;
37
+ labels?: {
38
+ singular?: string;
39
+ plural?: string;
40
+ };
41
+ public?: boolean;
42
+ showUi?: boolean;
43
+ showInRest?: boolean;
25
44
  }
26
45
 
27
46
  export interface ForgeWPI18nConfig {
28
47
  locales: string[];
29
48
  defaultLocale: string;
30
49
  provider?: 'local' | 'deepl' | 'libretranslate' | 'google' | string;
50
+ /** Optional project-relative JSON response cache for i18n:translate. */
31
51
  cache?: string;
32
52
  providerConfig?: {
33
53
  apiKey?: string;
@@ -40,13 +60,153 @@ export interface ForgeWpSeoSitemapsConfig {
40
60
  taxonomies: string[];
41
61
  }
42
62
 
63
+ export interface ForgeWPPluginContext {
64
+ fs: typeof import('node:fs');
65
+ path: typeof import('node:path');
66
+ }
67
+
43
68
  export interface ForgeWPPlugin {
44
69
  name: string;
45
- validateConfig?: (config: ForgeWPThemeConfig, themeRoot: string) => void;
46
- transformFunctionsPhp?: (php: string, config: ForgeWPThemeConfig, themeRoot: string) => string;
70
+ validateConfig?: (config: ForgeWPThemeConfig, themeRoot: string, context: ForgeWPPluginContext) => void;
71
+ transformFunctionsPhp?: (
72
+ php: string,
73
+ config: ForgeWPThemeConfig,
74
+ themeRoot: string,
75
+ context: ForgeWPPluginContext,
76
+ ) => string;
77
+ }
78
+
79
+ export type ForgeWPFormFieldType =
80
+ | 'text'
81
+ | 'email'
82
+ | 'tel'
83
+ | 'number'
84
+ | 'textarea'
85
+ | 'select'
86
+ | 'checkbox';
87
+
88
+ export interface ForgeWPFormField {
89
+ type: ForgeWPFormFieldType;
90
+ label?: string;
91
+ required?: boolean;
92
+ options?: string[];
93
+ maxLength?: number;
94
+ placeholder?: string;
95
+ }
96
+
97
+ export type ForgeWPFormFieldSeed = Array<ForgeWPFormField & { name: string }>;
98
+
99
+ export interface ForgeWPFormClientFieldsConfig {
100
+ enabled: boolean;
101
+ /**
102
+ * Initial client-owned field set. A flat array is used for every configured
103
+ * locale (fine for a single-language theme, or as a same-content starting
104
+ * point before translating). For a theme with `i18n.locales.length > 1`,
105
+ * provide a per-locale map instead so each language seeds independently —
106
+ * client-owned labels/options are runtime content, not compiled strings,
107
+ * so they can't go through the usual __()/translations.json pipeline.
108
+ */
109
+ seed: ForgeWPFormFieldSeed | Record<string, ForgeWPFormFieldSeed>;
110
+ }
111
+
112
+ export interface ForgeWPFormConfirmationConfig {
113
+ enabled: boolean;
114
+ emailField: string;
115
+ subject?: string;
116
+ body?: string;
117
+ /** Named plain-text template in cms/mail/<name>.json. */
118
+ template?: string;
119
+ }
120
+
121
+ export interface ForgeWPFormConfig {
122
+ /**
123
+ * 'native' (default): ForgeWP generates the REST endpoint, mail delivery,
124
+ * optional submission storage, and the wp-admin field editor. Requires
125
+ * `mailTo` and `fields`.
126
+ *
127
+ * 'shortcode': escape hatch for clients who want to self-manage a form
128
+ * entirely inside a WordPress plugin (CF7, WPForms, Gravity…). ForgeWP
129
+ * generates none of the above — the developer renders the plugin's
130
+ * markup directly with <WpShortcode code={...} />. Requires `shortcode`.
131
+ * `mailTo`, `fields`, `clientFields`, and `storeSubmissions` are ignored.
132
+ */
133
+ mode?: 'native' | 'shortcode';
134
+ /** Default/example shortcode string for 'shortcode' mode, e.g. '[contact-form-7 id="58" title="Contact Form"]'. */
135
+ shortcode?: string;
136
+ /** 'admin' → get_option('admin_email'); or a literal email;
137
+ * or 'option:some_key' → get_option('some_key'). Required in 'native' mode. */
138
+ mailTo?: string;
139
+ /** Email subject line. Supports {field} interpolation from submitted values. */
140
+ subject?: string;
141
+ /** Optional private-inbox title template. Supports developer-owned {field} values. */
142
+ submissionTitle?: string;
143
+ /** Plain-text notification email body. Supports {field}; blank uses the default field list. */
144
+ notificationBody?: string;
145
+ /** Named notification default in cms/mail/<name>.json. */
146
+ notificationTemplate?: string;
147
+ /** Visitor-facing success message returned by the native submission endpoint. */
148
+ successMessage?: string;
149
+ /** Dev-owned fields — the fixed part of the server-side allowlist. Required in 'native' mode. */
150
+ fields?: Record<string, ForgeWPFormField>;
151
+ clientFields?: ForgeWPFormClientFieldsConfig;
152
+ /** Store each submission in the forgewp_submission CPT (client inbox). Default true. */
153
+ storeSubmissions?: boolean;
154
+ /** Optional plain-text submitter confirmation. Disabled unless enabled. */
155
+ confirmation?: ForgeWPFormConfirmationConfig;
156
+ /** Permanently delete stored submissions after this many days. No cleanup by default. */
157
+ retentionDays?: number;
158
+ }
159
+
160
+ export interface WpOptionField {
161
+ _type:
162
+ | 'text'
163
+ | 'url'
164
+ | 'email'
165
+ | 'textarea'
166
+ | 'toggle'
167
+ | 'number'
168
+ | 'postPicker';
169
+ label?: string;
170
+ default?: string;
171
+ postType?: string;
172
+ }
173
+
174
+ export type WpOptionsSchema = Record<string, WpOptionField>;
175
+
176
+ export type ForgeWPSeedStrategy = boolean | 'once' | 'upsert' | 'force';
177
+
178
+ export interface ForgeWPSeedConfig {
179
+ /**
180
+ * Sync local products from `cms/products.ts` (or `products.json`) into WooCommerce.
181
+ * Default: false
182
+ */
183
+ products?: ForgeWPSeedStrategy;
184
+ /**
185
+ * Sync mock posts, pages, and CPTs from `cms/mock-data.ts` (or `mock-data.json`).
186
+ * A map opts in each post type independently; omitted/false types are disabled,
187
+ * even when invoked with --force. true is equivalent to 'once'.
188
+ * Default: false
189
+ */
190
+ mockData?: ForgeWPSeedStrategy | Record<string, ForgeWPSeedStrategy>;
191
+ /**
192
+ * Automatically sideload remote CDN image URLs into the WordPress Media Library.
193
+ * Default: true
194
+ */
195
+ sideloadImages?: boolean;
196
+ /**
197
+ * Safety guard: Only execute when WP_DEBUG is true, unless explicitly forced.
198
+ * Default: true
199
+ */
200
+ developmentOnly?: boolean;
47
201
  }
48
202
 
49
203
  export interface ForgeWPThemeConfig {
204
+ /** Generated style.css requirements. Raise minima for project dependencies; record testedUpTo after WordPress acceptance. */
205
+ compatibility?: {
206
+ requiresWordPress?: string;
207
+ requiresPhp?: string;
208
+ testedUpTo?: string;
209
+ };
50
210
  name: string;
51
211
  slug: string;
52
212
  version: string;
@@ -65,6 +225,12 @@ export interface ForgeWPThemeConfig {
65
225
  };
66
226
  frameworkAdapter?: 'react' | 'html' | 'stub';
67
227
  style?: 'forgewp' | 'shadcn';
228
+ /** Declare menu location keys. Labels come from settings.menus; use cms/menus.ts for starter entries. */
229
+ menus?: Record<string, string>;
230
+ presets?: {
231
+ /** Whether to add wp-block-styles theme support. Default: true. */
232
+ wordpressCoreStyles?: boolean;
233
+ };
68
234
  headless?: {
69
235
  apiUrl?: string;
70
236
  jwtAuth?: boolean;
@@ -72,6 +238,8 @@ export interface ForgeWPThemeConfig {
72
238
  auth?: {
73
239
  loginField?: 'usernameOnly' | 'emailOnly' | 'usernameAndEmail';
74
240
  defaultRole?: string;
241
+ /** Profile metadata accepted from public signup. Empty by default; reserved keys cannot be allowed. */
242
+ registrationMetaFields?: string[];
75
243
  reservedUsernames?: string[];
76
244
  features?: {
77
245
  registration?: boolean;
@@ -91,8 +259,14 @@ export interface ForgeWPThemeConfig {
91
259
  };
92
260
  };
93
261
  postTypes?: Record<string, CustomPostTypeConfig>;
262
+ taxonomies?: Record<string, CustomTaxonomyConfig>;
263
+ options?: WpOptionsSchema;
264
+ themeMods?: Record<string, any>;
265
+ seed?: ForgeWPSeedConfig;
94
266
  i18n?: ForgeWPI18nConfig;
95
267
  settings?: {
268
+ /** Explicit location descriptions, taking precedence over inferred menu labels. */
269
+ menus?: Record<string, { description?: string }>;
96
270
  layout?: {
97
271
  contentSize?: string;
98
272
  wideSize?: string;
@@ -108,10 +282,15 @@ export interface ForgeWPThemeConfig {
108
282
  };
109
283
  };
110
284
  plugins?: ForgeWPPlugin[];
285
+ forms?: Record<string, ForgeWPFormConfig>;
286
+ /**
287
+ * Capability required to manage form fields and view stored submissions.
288
+ * Defaults to `manage_options`. Granting a lower capability also grants
289
+ * access to submitted form data.
290
+ */
291
+ formsAdminCapability?: string;
111
292
  }
112
293
 
113
-
114
-
115
294
  export interface ForgeWPBuildAssets {
116
295
  cssFile: string;
117
296
  jsFile?: string;
@@ -145,6 +324,26 @@ export interface ForgeWPFrameworkAdapter {
145
324
  pc: any;
146
325
  },
147
326
  ): Promise<void> | void;
327
+ onMakeShell?(
328
+ themeRoot: string,
329
+ options: {
330
+ pascalCase: string;
331
+ nameSlug: string;
332
+ readableTitle: string;
333
+ childrenSlugs: string[];
334
+ shell: { className?: string; gridClassName?: string };
335
+ innerBlocks: {
336
+ allowedBlocks?: string[];
337
+ template?: Array<[string, Record<string, any>?]>;
338
+ templateLock?: boolean | 'all' | 'insert';
339
+ orientation?: 'horizontal' | 'vertical';
340
+ };
341
+ category: string;
342
+ icon: string;
343
+ description: string;
344
+ pc: any;
345
+ },
346
+ ): Promise<void> | void;
148
347
  onMakeLoop?(
149
348
  themeRoot: string,
150
349
  options: {
@@ -177,17 +376,97 @@ export type ForgeWPFrameworkAdapterModule = ForgeWPFrameworkAdapter & {
177
376
  default?: ForgeWPFrameworkAdapter;
178
377
  };
179
378
 
180
- export function exportTheme(options: {
379
+ export interface ForgeWPExportProgress {
380
+ stage: string;
381
+ message: string;
382
+ }
383
+
384
+ export interface ForgeWPExportOptions {
181
385
  themeRoot: string;
182
386
  skipBuild?: boolean;
183
387
  zip?: boolean;
184
388
  packageManager?: string;
185
- }): Promise<{
389
+ validate?: boolean;
390
+ strict?: boolean;
391
+ onProgress?: (progress: ForgeWPExportProgress) => void;
392
+ }
393
+
394
+ export interface ForgeWPExportResult {
186
395
  config: ForgeWPThemeConfig;
187
396
  outDir: string;
188
397
  zipPath: string | null;
189
398
  assets: ForgeWPBuildAssets;
190
- }>;
399
+ }
400
+
401
+ export function exportTheme(options: ForgeWPExportOptions): Promise<ForgeWPExportResult>;
402
+
403
+ export interface ForgeWPValidationOptions {
404
+ themeRoot: string;
405
+ outDir: string;
406
+ assets: ForgeWPBuildAssets;
407
+ config: ForgeWPThemeConfig;
408
+ strict?: boolean;
409
+ }
410
+
411
+ export interface ForgeWPValidationResult {
412
+ missing: string[];
413
+ warnings: string[];
414
+ }
415
+
416
+ export function validateExport(options: ForgeWPValidationOptions): Promise<ForgeWPValidationResult>;
417
+
418
+ export interface ForgeWPHydrationIsland {
419
+ name: string;
420
+ file: string;
421
+ trigger: string;
422
+ preload: string;
423
+ media: string | null;
424
+ connection: string | null;
425
+ clientOnly: boolean;
426
+ smartDiscovered?: boolean;
427
+ rootClassName?: string | null;
428
+ rootClassNameUnresolved?: boolean;
429
+ }
430
+
431
+ export function scanForHydrationIslandsWithProps(themeRoot: string): ForgeWPHydrationIsland[];
432
+
433
+ /** Parsed editable field records; extra provider-specific metadata is retained. */
434
+ export interface ForgeWPEditableField {
435
+ type: string;
436
+ label?: string;
437
+ default?: unknown;
438
+ [key: string]: unknown;
439
+ }
440
+
441
+ export function scanForEditableSchemas(themeRoot: string): Record<string, Record<string, ForgeWPEditableField>>;
442
+
443
+ export interface ForgeWPIslandDiagnostic {
444
+ name: string;
445
+ sizeKb: number;
446
+ isHeavy: boolean;
447
+ chunkPath: string;
448
+ }
449
+
450
+ export interface ForgeWPHydrationAnalysis {
451
+ heavyCount: number;
452
+ results: ForgeWPIslandDiagnostic[];
453
+ violations?: Array<{
454
+ type: string;
455
+ file: string;
456
+ message: string;
457
+ severity: 'warning' | 'error';
458
+ lineContent?: string;
459
+ }>;
460
+ }
461
+
462
+ export function analyzeHydrationIslands(themeRoot: string, mapping: Record<string, string>): ForgeWPHydrationAnalysis;
463
+
464
+ export function generateVisualReport(
465
+ themeRoot: string,
466
+ analysis: ForgeWPHydrationAnalysis,
467
+ islandsWithProps: ForgeWPHydrationIsland[],
468
+ config: ForgeWPThemeConfig,
469
+ ): string;
191
470
 
192
471
  export function loadConfig(themeRoot: string): Promise<ForgeWPThemeConfig>;
193
472
 
@@ -213,4 +492,4 @@ export function loadFrameworkAdapter(
213
492
  ): Promise<ForgeWPFrameworkAdapterModule>;
214
493
 
215
494
  export function forgewpPageConfigPlugin(): any;
216
-
495
+ export function forgewpVirtualPlugin(options?: { projectRoot?: string }): any;
package/lib/index.js CHANGED
@@ -7,7 +7,7 @@ export {
7
7
  findComponentPath,
8
8
  getHydrationRollupInputs,
9
9
  scanForEditableSchemas,
10
- } from './hydration-scanner.js';
10
+ } from './hydration/index.js';
11
11
  export { validateExport } from './validate-export.js';
12
12
  export {
13
13
  resolveFrameworkAdapter,
@@ -18,3 +18,4 @@ export {
18
18
  generateVisualReport,
19
19
  } from './diagnostics.js';
20
20
  export { forgewpPageConfigPlugin } from './page-config-plugin.js';
21
+ export { forgewpVirtualPlugin } from './virtual-plugin.js';