@forgewp/compiler 0.1.7 → 0.1.9

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.
package/lib/blueprints.js CHANGED
@@ -1,316 +1,501 @@
1
- /**
2
- * System File Blueprints — ForgeWP Compiler
3
- *
4
- * These are fallback templates used by the compiler's self-healing preflight check.
5
- * If a developer accidentally deletes a system-critical library file,
6
- * the compiler will automatically recreate it to prevent compilation and runtime errors.
7
- */
8
-
9
- export const SYSTEM_BLUEPRINTS = {
10
- "src/lib/wordpress.tsx": `/**
11
- * ForgeWP WordPress Data Hooks
12
- *
13
- * These hooks provide mock data during local development (Vite dev server).
14
- * When the theme is exported, the ForgeWP compiler replaces every token
15
- * with the equivalent WordPress PHP function call.
16
- *
17
- * ── Available hooks ────────────────────────────────────────────────────────
18
- * useWpTitle() → the_title() / get_the_title()
19
- * useWpContent() → the_content()
20
- * useWpExcerpt() → the_excerpt()
21
- * useWpPermalink() → get_permalink()
22
- * useWpDate() → get_the_date()
23
- * useWpAuthor() → get_the_author()
24
- * useWpFeaturedImage() → get_the_post_thumbnail_url()
25
- * useWpCategories() → the_category()
26
- * useWpArchiveTitle() → the_archive_title()
27
- * WpLoop → while ( have_posts() ) : the_post();
28
- * ──────────────────────────────────────────────────────────────────────────
29
- */
30
- import React from "react";
31
-
32
- const IS_DEV =
33
- typeof import.meta !== "undefined" &&
34
- // @ts-ignore
35
- import.meta.env?.DEV === true;
36
-
37
- // ── Post content ─────────────────────────────────────────────────────────────
38
-
39
- export function useWpTitle() {
40
- if (IS_DEV) return "Sample WordPress Post Title";
41
- return "__FORGEWP_THE_TITLE__";
42
- }
43
-
44
- export function useWpContent() {
45
- if (IS_DEV) {
46
- return "<p>This is sample post content rendered locally so you can design your theme. In WordPress, this is replaced by the actual content from the Gutenberg editor — including blocks, shortcodes, and embeds.</p><p>You can style this area using the <code>.prose</code> utility or any Tailwind class you like.</p>";
47
- }
48
- return "__FORGEWP_THE_CONTENT__";
49
- }
50
-
51
- export function useWpExcerpt() {
52
- if (IS_DEV) {
53
- return "A short excerpt that gives readers a quick preview of what to expect in the full post. ForgeWP replaces this with the_excerpt() on export.";
54
- }
55
- return "__FORGEWP_THE_EXCERPT__";
56
- }
57
-
58
- export function useWpPermalink() {
59
- if (IS_DEV) return "/post";
60
- return "__FORGEWP_THE_PERMALINK__";
61
- }
62
-
63
- // ── Post meta ─────────────────────────────────────────────────────────────────
64
-
65
- /** Returns the formatted post date. Maps to get_the_date() in WordPress. */
66
- export function useWpDate() {
67
- if (IS_DEV) {
68
- return new Date().toLocaleDateString("en-US", {
69
- year: "numeric",
70
- month: "long",
71
- day: "numeric",
72
- });
73
- }
74
- return "__FORGEWP_THE_DATE__";
75
- }
76
-
77
- /** Returns the post author's display name. Maps to get_the_author() in WordPress. */
78
- export function useWpAuthor() {
79
- if (IS_DEV) return "Jane Doe";
80
- return "__FORGEWP_THE_AUTHOR__";
81
- }
82
-
83
- /**
84
- * Returns the featured image URL (large size).
85
- * Maps to get_the_post_thumbnail_url(null, 'large') in WordPress.
86
- *
87
- * In dev, returns a placeholder image from picsum.photos.
88
- * In your JSX, use it as: <img src={featuredImage} alt={title} />
89
- */
90
- export function useWpFeaturedImage() {
91
- if (IS_DEV) return "https://picsum.photos/seed/forgewp/1200/630";
92
- return "__FORGEWP_THE_POST_THUMBNAIL_URL__";
93
- }
94
-
95
- /**
96
- * Returns the post's categories as an HTML string (links separated by commas).
97
- * Maps to the_category(', ') in WordPress.
98
- *
99
- * Use with dangerouslySetInnerHTML since it contains anchor tags.
100
- * @example
101
- * const categories = useWpCategories();
102
- * <div dangerouslySetInnerHTML={{ __html: categories }} />
103
- */
104
- export function useWpCategories() {
105
- if (IS_DEV) {
106
- return '<a href="#">Technology</a>, <a href="#">Design</a>';
107
- }
108
- return "__FORGEWP_THE_CATEGORY_LIST__";
109
- }
110
-
111
- /**
112
- * Returns the archive page title (e.g. "Category: Technology", "Tag: React").
113
- * Maps to the_archive_title() in WordPress.
114
- * Use this in archive.tsx — not needed for single posts.
115
- */
116
- export function useWpArchiveTitle() {
117
- if (IS_DEV) return "Category: Technology";
118
- return "__FORGEWP_THE_ARCHIVE_TITLE__";
119
- }
120
-
121
- // ── Loop ──────────────────────────────────────────────────────────────────────
122
-
123
- /**
124
- * \`<WpLoop>\` — Renders a WordPress post loop.
125
- *
126
- * In dev: renders your children 3 times with mock data so you can design your layout.
127
- * On export: wraps your JSX in a real \`while (have_posts()) : the_post();\` PHP loop.
128
- *
129
- * @example
130
- * <WpLoop>
131
- * <PostCard />
132
- * </WpLoop>
133
- */
134
- export function WpLoop({ children }: { children: React.ReactNode }) {
135
- if (IS_DEV) {
136
- // Render 3 dummy posts so the developer can design the grid/list layout
137
- return (
138
- <>
139
- {children}
140
- {children}
141
- {children}
142
- </>
143
- );
144
- }
145
-
146
- // In production: custom elements become compiler tokens → PHP loop
147
- return (
148
- <>
149
- {/* @ts-ignore — custom elements used as ForgeWP compiler tokens */}
150
- <forgewp-loop-start />
151
- {children}
152
- {/* @ts-ignore */}
153
- <forgewp-loop-end />
154
- </>
155
- );
156
- }
157
- `,
158
-
159
- "src/lib/SEO.tsx": `import * as ReactHelmetAsync from "react-helmet-async";
160
- import { useWpTitle } from "./wordpress";
161
-
162
- // Support both ESM and CommonJS exports of react-helmet-async across Vite and TSX compiler
163
- const Helmet = (ReactHelmetAsync.Helmet || (ReactHelmetAsync as any)["default"]?.Helmet || ReactHelmetAsync) as any;
164
-
165
- /**
166
- * ForgeWP SEO — Internal system file. Do not delete.
167
- *
168
- * Use this component in \`src/app/layout.tsx\` to set global SEO defaults,
169
- * and in individual page files to override them per-page.
170
- *
171
- * The ForgeWP compiler reads the props you pass here and injects them
172
- * directly into the WordPress theme's <head> as native meta tags.
173
- *
174
- * @see https://forgewp.dev/docs/seo
175
- */
176
-
177
- export interface SEOProps {
178
- /** Page title — defaults to the WordPress post title via useWpTitle() */
179
- title?: string;
180
- /** Meta description for search engines and social cards */
181
- description?: string;
182
- /** Comma-separated keywords */
183
- keywords?: string;
184
- /** Open Graph title (falls back to title if omitted) */
185
- ogTitle?: string;
186
- /** Open Graph description (falls back to description if omitted) */
187
- ogDescription?: string;
188
- /** Absolute URL to the Open Graph image */
189
- ogImage?: string;
190
- /** Open Graph type — "website" for homepages, "article" for posts */
191
- ogType?: string;
192
- /** Twitter card type */
193
- twitterCard?: string;
194
- /** Twitter creator handle, e.g. "@username" */
195
- twitterCreator?: string;
196
- /** Canonical URL — tells search engines the preferred version of this page */
197
- canonical?: string;
198
- /** Set to true to prevent this page from being indexed by search engines */
199
- noIndex?: boolean;
200
- }
201
-
202
- /**
203
- * \`<SEO>\` — ForgeWP SEO manager.
204
- *
205
- * Drop this into your **layout.tsx** to set site-wide defaults.
206
- * Then drop it into any **page file** to override for that specific template.
207
- *
208
- * @example
209
- * // layout.tsx — global defaults (the compiler reads these for all pages)
210
- * <SEO
211
- * description="Your site tagline or description."
212
- * keywords="WordPress, React, Tailwind"
213
- * ogImage="https://yoursite.com/og-default.png"
214
- * />
215
- *
216
- * @example
217
- * // single.tsx — per-page override (article-specific metadata)
218
- * <SEO
219
- * ogType="article"
220
- * ogImage="https://yoursite.com/og-post.png"
221
- * twitterCreator="@yourhandle"
222
- * />
223
- */
224
- export function SEO({
225
- title,
226
- description = "A WordPress theme built with ForgeWP — React & Tailwind CSS.",
227
- keywords = "WordPress, React, Tailwind CSS, ForgeWP",
228
- ogTitle,
229
- ogDescription,
230
- ogImage,
231
- ogType = "website",
232
- twitterCard = "summary_large_image",
233
- twitterCreator,
234
- canonical,
235
- noIndex = false,
236
- }: SEOProps) {
237
- const wpTitle = useWpTitle();
238
- const resolvedTitle = title ?? wpTitle;
239
-
240
- return (
241
- <Helmet>
242
- {/* ── Primary ── */}
243
- <title>{resolvedTitle}</title>
244
- <meta name="description" content={description} />
245
- {keywords && <meta name="keywords" content={keywords} />}
246
- {noIndex && <meta name="robots" content="noindex, nofollow" />}
247
- {canonical && <link rel="canonical" href={canonical} />}
248
-
249
- {/* ── Open Graph ── */}
250
- <meta property="og:type" content={ogType} />
251
- <meta property="og:title" content={ogTitle ?? resolvedTitle} />
252
- <meta property="og:description" content={ogDescription ?? description} />
253
- {ogImage && <meta property="og:image" content={ogImage} />}
254
-
255
- {/* ── Twitter ── */}
256
- <meta name="twitter:card" content={twitterCard} />
257
- <meta name="twitter:title" content={ogTitle ?? resolvedTitle} />
258
- <meta name="twitter:description" content={ogDescription ?? description} />
259
- {ogImage && <meta name="twitter:image" content={ogImage} />}
260
- {twitterCreator && <meta name="twitter:creator" content={twitterCreator} />}
261
- </Helmet>
262
- );
263
- }
264
- `,
265
-
266
- "src/lib/PresetsStyle.tsx": `import wpConfig from "../../wp.config";
267
-
268
- const IS_DEV =
269
- typeof import.meta !== "undefined" &&
270
- // @ts-ignore
271
- import.meta.env?.DEV === true;
272
-
273
- /**
274
- * PresetsStyle component — Internal system component.
275
- *
276
- * Dynamically injects WordPress-preset CSS Custom Properties and enqueues Google Fonts
277
- * during local Vite development, keeping your styles perfectly in sync with WordPress.
278
- * In production builds, this returns null and is completely skipped since WordPress
279
- * native styles are enqueued automatically.
280
- */
281
- export function PresetsStyle() {
282
- if (!IS_DEV) return null;
283
-
284
- // Local development fallbacks for WordPress CSS presets
285
- const colors = wpConfig.settings?.color?.palette || [];
286
- const fontSizes = wpConfig.settings?.typography?.fontSizes || [];
287
- const fontFamilies = wpConfig.settings?.typography?.fontFamilies || [];
288
- const layout = wpConfig.settings?.layout || {};
289
- const googleFonts = wpConfig.settings?.typography?.googleFonts || [];
290
-
291
- // Parse and build Google Fonts href for dev injection
292
- const fontsHtml = googleFonts.length > 0
293
- ? \`<link rel="preconnect" href="https://fonts.googleapis.com">
294
- <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
295
- <link href="https://fonts.googleapis.com/css2?family=\${googleFonts.map(f => encodeURIComponent(f)).join("&family=")}&display=swap" rel="stylesheet">\`
296
- : "";
297
-
298
- const css = \`
299
- :root {
300
- \${colors.map((c) => \`--wp--preset--color--\${c.slug}: \${c.color};\`).join("\\n ")}
301
- \${fontSizes.map((f) => \`--wp--preset--font-size--\${f.slug}: \${f.size};\`).join("\\n ")}
302
- \${fontFamilies.map((f) => \`--wp--preset--font-family--\${f.slug}: \${f.fontFamily};\`).join("\\n ")}
303
- \${layout.contentSize ? \`--wp--style--global--content-size: \${layout.contentSize};\` : ""}
304
- \${layout.wideSize ? \`--wp--style--global--wide-size: \${layout.wideSize};\` : ""}
305
- }
306
- \`;
307
-
308
- return (
309
- <>
310
- {fontsHtml && <span dangerouslySetInnerHTML={{ __html: fontsHtml }} />}
311
- <style dangerouslySetInnerHTML={{ __html: css }} />
312
- </>
313
- );
314
- }
315
- `
316
- };
1
+ /**
2
+ * System File Blueprints — ForgeWP Compiler
3
+ *
4
+ * These are fallback templates used by the compiler's self-healing preflight check.
5
+ * If a developer accidentally deletes a system-critical library file,
6
+ * the compiler will automatically recreate it to prevent compilation and runtime errors.
7
+ */
8
+
9
+ export const SYSTEM_BLUEPRINTS = {
10
+ "wordpress/menus.json": `{
11
+ "_comment": "⚡ ForgeWP Navigation Menus — Edit this file to add/remove links in local dev. Run 'pnpm forgewp sync:routes' to auto-scaffold corresponding React pages!",
12
+ "primary": [
13
+ { "title": "Home", "url": "/" },
14
+ { "title": "New", "url": "/new" },
15
+ { "title": "Men", "url": "/men" },
16
+ { "title": "Women", "url": "/women" }
17
+ ],
18
+ "utility": [
19
+ { "title": "Help", "url": "/help" },
20
+ { "title": "Sign In", "url": "/login" }
21
+ ]
22
+ }`,
23
+
24
+ "wordpress/mock-data.json": `{
25
+ "post": [
26
+ {
27
+ "id": 1,
28
+ "title": "Welcome to ForgeWP: The Headless Revolution",
29
+ "excerpt": "Discover how ForgeWP bridges standard WordPress themes with blistering fast React architectures.",
30
+ "content": "<p>This is the first mock post. In local dev, you can modify <code>wordpress/mock-data.json</code> to test layout content changes.</p>",
31
+ "date": "May 10, 2026",
32
+ "author": "Antigravity",
33
+ "featuredImage": "https://picsum.photos/seed/forgewp/1200/630",
34
+ "customFields": {}
35
+ },
36
+ {
37
+ "id": 2,
38
+ "title": "Unlocking Brutalist Web Design Aesthetics",
39
+ "excerpt": "A deep dive into high-contrast grids, sharp corners, and premium flat shadows in modern interfaces.",
40
+ "content": "<p>This is the second mock post. Style these grids using beautiful Tailwind utilities.</p>",
41
+ "date": "May 12, 2026",
42
+ "author": "DeepMind Partner",
43
+ "featuredImage": "https://picsum.photos/seed/brutalist/1200/630",
44
+ "customFields": {}
45
+ }
46
+ ],
47
+ "project": [
48
+ {
49
+ "id": 1,
50
+ "title": "ForgeWP Scaffolding Platform",
51
+ "excerpt": "Building a custom compiler framework to transpile React elements into standard PHP themes.",
52
+ "content": "<p>Detailed description of the ForgeWP compiler pipeline project.</p>",
53
+ "date": "May 15, 2026",
54
+ "author": "Lead Architect",
55
+ "featuredImage": "https://picsum.photos/seed/platform/1200/630",
56
+ "customFields": {
57
+ "client_name": "El Dorado",
58
+ "project_budget": "$45,000"
59
+ }
60
+ },
61
+ {
62
+ "id": 2,
63
+ "title": "Brutalist Starter Theme",
64
+ "excerpt": "A clean, responsive, and robust high-contrast interface leveraging Tailwind CSS v4.",
65
+ "content": "<p>A brutalist theme showcasing raw black borders and vivid accent colors.</p>",
66
+ "date": "May 16, 2026",
67
+ "author": "Theme Engineer",
68
+ "featuredImage": "https://picsum.photos/seed/starter/1200/630",
69
+ "customFields": {
70
+ "client_name": "ForgeWP Community",
71
+ "project_budget": "Open Source"
72
+ }
73
+ }
74
+ ]
75
+ }`,
76
+
77
+ "src/.forgewp/forgewp-config.ts": `export interface ColorPreset {
78
+ name: string;
79
+ slug: string;
80
+ color: string;
81
+ }
82
+
83
+ export interface FontSizePreset {
84
+ name: string;
85
+ slug: string;
86
+ size: string;
87
+ }
88
+
89
+ export interface FontFamilyPreset {
90
+ name: string;
91
+ slug: string;
92
+ fontFamily: string;
93
+ }
94
+
95
+ export interface ForgeWPThemeConfig {
96
+ name: string;
97
+ slug: string;
98
+ version: string;
99
+ description: string;
100
+ textDomain: string;
101
+ /** Design aesthetic style — "forgewp" (sharp edges, high-contrast) or "shadcn" (smooth rounded modern) */
102
+ style?: "forgewp" | "shadcn";
103
+ // Design Tokens (Phase 5)
104
+ settings?: {
105
+ layout?: {
106
+ contentSize?: string;
107
+ wideSize?: string;
108
+ };
109
+ color?: {
110
+ palette?: ColorPreset[];
111
+ custom?: boolean;
112
+ };
113
+ typography?: {
114
+ fontSizes?: FontSizePreset[];
115
+ fontFamilies?: FontFamilyPreset[];
116
+ googleFonts?: string[];
117
+ };
118
+ };
119
+ }
120
+ `,
121
+
122
+ "src/.forgewp/wordpress.tsx": `/**
123
+ * ForgeWP WordPress Data Hooks
124
+ *
125
+ * These hooks provide mock data during local development (Vite dev server).
126
+ * When the theme is exported, the ForgeWP compiler replaces every token
127
+ * with the equivalent WordPress PHP function call.
128
+ */
129
+ import React from "react";
130
+
131
+ // @ts-ignore
132
+ import mockData from "../../wordpress/mock-data.json";
133
+ // @ts-ignore
134
+ import menusData from "../../wordpress/menus.json";
135
+
136
+ import {
137
+ WpQueryLoop as _WpQueryLoop,
138
+ WpMenu as _WpMenu,
139
+ WpShortcode,
140
+ useWpTitle as _useWpTitle,
141
+ useWpContent as _useWpContent,
142
+ useWpExcerpt as _useWpExcerpt,
143
+ useWpPermalink as _useWpPermalink,
144
+ useWpDate as _useWpDate,
145
+ useWpAuthor as _useWpAuthor,
146
+ useWpFeaturedImage as _useWpFeaturedImage,
147
+ useWpCustomField as _useWpCustomField,
148
+ } from "@forgewp/react";
149
+ import type { WpQueryLoopProps, WpMenuProps } from "@forgewp/react";
150
+
151
+ const IS_DEV =
152
+ typeof import.meta !== "undefined" &&
153
+ // @ts-ignore
154
+ import.meta.env?.DEV === true;
155
+
156
+ // ── Re-export pure hooks with compiler token fallbacks ────────────────────────
157
+ // In dev: @forgewp/react hook returns the mock value from WpPostContext.
158
+ // In prod: compiler replaces the call with the PHP equivalent below.
159
+
160
+ export function useWpTitle(): string {
161
+ if (IS_DEV) return _useWpTitle();
162
+ return "__FORGEWP_THE_TITLE__";
163
+ }
164
+ export function useWpContent(): string {
165
+ if (IS_DEV) return _useWpContent();
166
+ return "__FORGEWP_THE_CONTENT__";
167
+ }
168
+ export function useWpExcerpt(): string {
169
+ if (IS_DEV) return _useWpExcerpt();
170
+ return "__FORGEWP_THE_EXCERPT__";
171
+ }
172
+ export function useWpPermalink(): string {
173
+ if (IS_DEV) return _useWpPermalink();
174
+ return "__FORGEWP_THE_PERMALINK__";
175
+ }
176
+ export function useWpDate(): string {
177
+ if (IS_DEV) return _useWpDate();
178
+ return "__FORGEWP_THE_DATE__";
179
+ }
180
+ export function useWpAuthor(): string {
181
+ if (IS_DEV) return _useWpAuthor();
182
+ return "__FORGEWP_THE_AUTHOR__";
183
+ }
184
+ export function useWpFeaturedImage(): string {
185
+ if (IS_DEV) return _useWpFeaturedImage();
186
+ return "__FORGEWP_THE_POST_THUMBNAIL_URL__";
187
+ }
188
+ export function useWpCustomField(fieldName: string, defaultValue = ""): string {
189
+ if (IS_DEV) return _useWpCustomField(fieldName, defaultValue);
190
+ return "__FORGEWP_CUSTOM_FIELD__" + fieldName + "__";
191
+ }
192
+
193
+ export function useWpCategories(): string {
194
+ if (IS_DEV) return '<a href="#">Technology</a>, <a href="#">Design</a>';
195
+ return "__FORGEWP_THE_CATEGORY_LIST__";
196
+ }
197
+ export function useWpArchiveTitle(): string {
198
+ if (IS_DEV) return "Category: Technology";
199
+ return "__FORGEWP_THE_ARCHIVE_TITLE__";
200
+ }
201
+
202
+ // ── WpQueryLoop — data bridge wraps @forgewp/react with mock data ─────────────
203
+
204
+ export function WpQueryLoop({
205
+ postType = "post",
206
+ postsPerPage = 3,
207
+ categoryName = "",
208
+ children,
209
+ }: WpQueryLoopProps) {
210
+ if (IS_DEV) {
211
+ const posts = (mockData as any)?.[postType] || [];
212
+ return (
213
+ <_WpQueryLoop posts={posts} postType={postType} postsPerPage={postsPerPage} categoryName={categoryName}>
214
+ {children}
215
+ </_WpQueryLoop>
216
+ );
217
+ }
218
+
219
+ // Production: compiler transforms these custom elements into WordPress loop PHP
220
+ return (
221
+ <>
222
+ {/* @ts-ignore */}
223
+ <forgewp-query-loop-start postType={postType} postsPerPage={postsPerPage} categoryName={categoryName} />
224
+ {children}
225
+ {/* @ts-ignore */}
226
+ <forgewp-query-loop-end />
227
+ </>
228
+ );
229
+ }
230
+
231
+ // ── WpLoop — simple all-posts loop (no postType arg) ─────────────────────────
232
+
233
+ export function WpLoop({ children }: { children: React.ReactNode }) {
234
+ if (IS_DEV) {
235
+ const posts = (mockData as any)?.post || [];
236
+ return (
237
+ <_WpQueryLoop posts={posts}>
238
+ {children}
239
+ </_WpQueryLoop>
240
+ );
241
+ }
242
+ return (
243
+ <>
244
+ {/* @ts-ignore */}
245
+ <forgewp-loop-start />
246
+ {children}
247
+ {/* @ts-ignore */}
248
+ <forgewp-loop-end />
249
+ </>
250
+ );
251
+ }
252
+
253
+ // ── WpMenu — data bridge wraps @forgewp/react with menus.json ────────────────
254
+
255
+ export function WpMenu({ location = "primary", className = "", linkClassName = "" }: WpMenuProps) {
256
+ if (IS_DEV) {
257
+ const items =
258
+ (menusData as any)?.[location] ||
259
+ (mockData as any).menu?.[location] ||
260
+ [{ title: "Home", url: "/" }, { title: "Blog", url: "/post" }];
261
+ return <_WpMenu items={items} location={location} className={className} linkClassName={linkClassName} />;
262
+ }
263
+
264
+ // Production: compiler transforms this into wp_nav_menu()
265
+ return (
266
+ // @ts-ignore
267
+ <forgewp-menu location={location} className={className} linkClassName={linkClassName} />
268
+ );
269
+ }
270
+
271
+ // ── WpShortcode — pass-through, no data bridging needed ──────────────────────
272
+ export { WpShortcode };
273
+
274
+ // ── Compiler custom element JSX declarations ──────────────────────────────────
275
+
276
+ declare global {
277
+ namespace React {
278
+ namespace JSX {
279
+ interface IntrinsicElements {
280
+ "forgewp-menu": React.DetailedHTMLProps<
281
+ React.HTMLAttributes<HTMLElement> & {
282
+ location?: "primary" | "footer" | "sidebar";
283
+ linkClassName?: string;
284
+ },
285
+ HTMLElement
286
+ >;
287
+ "forgewp-query-loop-start": React.DetailedHTMLProps<
288
+ React.HTMLAttributes<HTMLElement> & {
289
+ postType?: string;
290
+ postsPerPage?: number;
291
+ categoryName?: string;
292
+ },
293
+ HTMLElement
294
+ >;
295
+ "forgewp-query-loop-end": React.DetailedHTMLProps<
296
+ React.HTMLAttributes<HTMLElement>,
297
+ HTMLElement
298
+ >;
299
+ "forgewp-loop-start": React.DetailedHTMLProps<
300
+ React.HTMLAttributes<HTMLElement>,
301
+ HTMLElement
302
+ >;
303
+ "forgewp-loop-end": React.DetailedHTMLProps<
304
+ React.HTMLAttributes<HTMLElement>,
305
+ HTMLElement
306
+ >;
307
+ "forgewp-shortcode": React.DetailedHTMLProps<
308
+ React.HTMLAttributes<HTMLElement> & {
309
+ code?: string;
310
+ },
311
+ HTMLElement
312
+ >;
313
+ }
314
+ }
315
+ }
316
+ }
317
+ `,
318
+
319
+ "src/.forgewp/SEO.tsx": `import * as ReactHelmetAsync from "react-helmet-async";
320
+ import { useWpTitle } from "./wordpress";
321
+
322
+ // Support both ESM and CommonJS exports of react-helmet-async across Vite and TSX compiler
323
+ const Helmet = (ReactHelmetAsync.Helmet || (ReactHelmetAsync as any)["default"]?.Helmet || ReactHelmetAsync) as any;
324
+
325
+ /**
326
+ * ForgeWP SEO — Internal system file. Do not delete.
327
+ *
328
+ * Use this component in \`src/app/layout.tsx\` to set global SEO defaults,
329
+ * and in individual page files to override them per-page.
330
+ *
331
+ * The ForgeWP compiler reads the props you pass here and injects them
332
+ * directly into the WordPress theme's <head> as native meta tags.
333
+ *
334
+ * @see https://forgewp.dev/docs/seo
335
+ */
336
+
337
+ export interface SEOProps {
338
+ /** Page title — defaults to the WordPress post title via useWpTitle() */
339
+ title?: string;
340
+ /** Meta description for search engines and social cards */
341
+ description?: string;
342
+ /** Comma-separated keywords */
343
+ keywords?: string;
344
+ /** Open Graph title (falls back to title if omitted) */
345
+ ogTitle?: string;
346
+ /** Open Graph description (falls back to description if omitted) */
347
+ ogDescription?: string;
348
+ /** Absolute URL to the Open Graph image */
349
+ ogImage?: string;
350
+ /** Open Graph type — "website" for homepages, "article" for posts */
351
+ ogType?: string;
352
+ /** Twitter card type */
353
+ twitterCard?: string;
354
+ /** Twitter creator handle, e.g. "@username" */
355
+ twitterCreator?: string;
356
+ /** Canonical URL — tells search engines the preferred version of this page */
357
+ canonical?: string;
358
+ /** Set to true to prevent this page from being indexed by search engines */
359
+ noIndex?: boolean;
360
+ }
361
+
362
+ /**
363
+ * \`<SEO>\` — ForgeWP SEO manager.
364
+ *
365
+ * Drop this into your **layout.tsx** to set site-wide defaults.
366
+ * Then drop it into any **page file** to override for that specific template.
367
+ *
368
+ * @example
369
+ * // layout.tsx — global defaults (the compiler reads these for all pages)
370
+ * <SEO
371
+ * description="Your site tagline or description."
372
+ * keywords="WordPress, React, Tailwind"
373
+ * ogImage="https://yoursite.com/og-default.png"
374
+ * />
375
+ *
376
+ * @example
377
+ * // single.tsx — per-page override (article-specific metadata)
378
+ * <SEO
379
+ * ogType="article"
380
+ * ogImage="https://yoursite.com/og-post.png"
381
+ * twitterCreator="@yourhandle"
382
+ * />
383
+ */
384
+ export function SEO({
385
+ title,
386
+ description = "A WordPress theme built with ForgeWP — React & Tailwind CSS.",
387
+ keywords = "WordPress, React, Tailwind CSS, ForgeWP",
388
+ ogTitle,
389
+ ogDescription,
390
+ ogImage,
391
+ ogType = "website",
392
+ twitterCard = "summary_large_image",
393
+ twitterCreator,
394
+ canonical,
395
+ noIndex = false,
396
+ }: SEOProps) {
397
+ const wpTitle = useWpTitle();
398
+ const resolvedTitle = title ?? wpTitle;
399
+
400
+ return (
401
+ <Helmet>
402
+ {/* ── Primary ── */}
403
+ <title>{resolvedTitle}</title>
404
+ <meta name="description" content={description} />
405
+ {keywords && <meta name="keywords" content={keywords} />}
406
+ {noIndex && <meta name="robots" content="noindex, nofollow" />}
407
+ {canonical && <link rel="canonical" href={canonical} />}
408
+
409
+ {/* ── Open Graph ── */}
410
+ <meta property="og:type" content={ogType} />
411
+ <meta property="og:title" content={ogTitle ?? resolvedTitle} />
412
+ <meta property="og:description" content={ogDescription ?? description} />
413
+ {ogImage && <meta property="og:image" content={ogImage} />}
414
+
415
+ {/* ── Twitter ── */}
416
+ <meta name="twitter:card" content={twitterCard} />
417
+ <meta name="twitter:title" content={ogTitle ?? resolvedTitle} />
418
+ <meta name="twitter:description" content={ogDescription ?? description} />
419
+ {ogImage && <meta name="twitter:image" content={ogImage} />}
420
+ {twitterCreator && <meta name="twitter:creator" content={twitterCreator} />}
421
+ </Helmet>
422
+ );
423
+ }
424
+ `,
425
+
426
+ "src/.forgewp/PresetsStyle.tsx": `import wpConfig from "../../wp.config";
427
+
428
+ const IS_DEV =
429
+ typeof import.meta !== "undefined" &&
430
+ // @ts-ignore
431
+ import.meta.env?.DEV === true;
432
+
433
+ /**
434
+ * PresetsStyle component — Internal system component.
435
+ *
436
+ * Dynamically injects WordPress-preset CSS Custom Properties and enqueues Google Fonts
437
+ * during local Vite development, keeping your styles perfectly in sync with WordPress.
438
+ * In production builds, this returns only the registry-aesthetic design tokens (like --radius)
439
+ * to keep shadcn components and theme variables responsive to your config.
440
+ */
441
+ export function PresetsStyle() {
442
+ const themeStyle = wpConfig.style || "forgewp";
443
+
444
+ // Production build: only inject custom registry-aesthetic design properties
445
+ if (!IS_DEV) {
446
+ const prodCss = \`
447
+ :root {
448
+ --radius: \${themeStyle === "forgewp" ? "0px" : "0.5rem"};
449
+ --radius-sm: calc(var(--radius) - 4px);
450
+ --radius-md: calc(var(--radius) - 2px);
451
+ --radius-lg: var(--radius);
452
+ --border-width: \${themeStyle === "forgewp" ? "2px" : "1px"};
453
+ --border-color: \${themeStyle === "forgewp" ? "#09090b" : "#e4e4e7"};
454
+ --shadow-offset: \${themeStyle === "forgewp" ? "4px" : "0px"};
455
+ }
456
+ \`;
457
+ return <style dangerouslySetInnerHTML={{ __html: prodCss }} />;
458
+ }
459
+
460
+ // Local development fallbacks for WordPress CSS presets
461
+ const colors = wpConfig.settings?.color?.palette || [];
462
+ const fontSizes = wpConfig.settings?.typography?.fontSizes || [];
463
+ const fontFamilies = wpConfig.settings?.typography?.fontFamilies || [];
464
+ const layout = wpConfig.settings?.layout || {};
465
+ const googleFonts = wpConfig.settings?.typography?.googleFonts || [];
466
+
467
+ // Parse and build Google Fonts href for dev injection
468
+ const fontsHtml = googleFonts.length > 0
469
+ ? \`<link rel="preconnect" href="https://fonts.googleapis.com">
470
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
471
+ <link href="https://fonts.googleapis.com/css2?family=\&{googleFonts.map(f => encodeURIComponent(f)).join("&family=")}&display=swap" rel="stylesheet">\`
472
+ : "";
473
+
474
+ const devCss = \`
475
+ :root {
476
+ \${colors.map((c) => "--wp--preset--color--" + c.slug + ": " + c.color + ";").join("\\n ")}
477
+ \${fontSizes.map((f) => "--wp--preset--font-size--" + f.slug + ": " + f.size + ";").join("\\n ")}
478
+ \${fontFamilies.map((f) => "--wp--preset--font-family--" + f.slug + ": " + f.fontFamily + ";").join("\\n ")}
479
+ \${layout.contentSize ? "--wp--style--global--content-size: " + layout.contentSize + ";" : ""}
480
+ \${layout.wideSize ? "--wp--style--global--wide-size: " + layout.wideSize + ";" : ""}
481
+
482
+ /* Registry Aesthetic Mode Custom Properties */
483
+ --radius: \${themeStyle === "forgewp" ? "0px" : "0.5rem"};
484
+ --radius-sm: calc(var(--radius) - 4px);
485
+ --radius-md: calc(var(--radius) - 2px);
486
+ --radius-lg: var(--radius);
487
+ --border-width: \${themeStyle === "forgewp" ? "2px" : "1px"};
488
+ --border-color: \${themeStyle === "forgewp" ? "#09090b" : "#e4e4e7"};
489
+ --shadow-offset: \${themeStyle === "forgewp" ? "4px" : "0px"};
490
+ }
491
+ \`;
492
+
493
+ return (
494
+ <>
495
+ {fontsHtml && <span dangerouslySetInnerHTML={{ __html: fontsHtml }} />}
496
+ <style dangerouslySetInnerHTML={{ __html: devCss }} />
497
+ </>
498
+ );
499
+ }
500
+ `
501
+ };