@puckeditor/cli 0.24.0-canary.c16ace08 → 0.24.0-canary.c9aa1fa8
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/dist/bin.mjs +61 -5
- package/dist/docs/cloud/ai/assembly-mode.md +271 -0
- package/dist/docs/cloud/ai/business-context.md +69 -0
- package/dist/docs/cloud/ai/custom-agents.md +133 -0
- package/dist/docs/cloud/ai/design-mode.md +235 -0
- package/dist/docs/cloud/ai/headless-generation.md +122 -0
- package/dist/docs/cloud/ai/localization.md +43 -0
- package/dist/docs/cloud/ai/model-configuration.md +113 -0
- package/dist/docs/cloud/ai/overview.md +35 -0
- package/dist/docs/cloud/ai/setup.md +65 -0
- package/dist/docs/cloud/ai/tools.md +99 -0
- package/dist/docs/cloud/api-reference/cloud-client/helpers/chat.md +515 -0
- package/dist/docs/cloud/api-reference/cloud-client/helpers/login-url.md +21 -0
- package/dist/docs/cloud/api-reference/cloud-client/helpers/tool.md +128 -0
- package/dist/docs/cloud/api-reference/cloud-client/puck-cloud.md +73 -0
- package/dist/docs/cloud/api-reference/cloud-client/puck-handler.md +434 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/ai-generate.md +523 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/auth-get-session.md +41 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/auth-sign-out.md +24 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-create-version.md +50 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-create.md +45 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-delete.md +42 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-get-by-path.md +34 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-get-published.md +25 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-get.md +34 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-list-versions.md +49 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-list.md +46 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-publish.md +30 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-unpublish.md +25 -0
- package/dist/docs/cloud/api-reference/cloud-client/server-apis/pages-update.md +38 -0
- package/dist/docs/cloud/api-reference/cloud-client/types/ai-generate-field-type.md +33 -0
- package/dist/docs/cloud/api-reference/cloud-client/types/page-list.md +41 -0
- package/dist/docs/cloud/api-reference/cloud-client/types/page.md +61 -0
- package/dist/docs/cloud/api-reference/cloud-client/types/puck-cloud-error.md +34 -0
- package/dist/docs/cloud/api-reference/cloud-client/types/puck-session.md +53 -0
- package/dist/docs/cloud/api-reference/plugin-ai/ai-configuration/components.md +72 -0
- package/dist/docs/cloud/api-reference/plugin-ai/ai-configuration/fields.md +231 -0
- package/dist/docs/cloud/api-reference/plugin-ai/ai-field-type.md +41 -0
- package/dist/docs/cloud/api-reference/plugin-ai/ai-part.md +90 -0
- package/dist/docs/cloud/api-reference/plugin-ai/create-ai-plugin.md +311 -0
- package/dist/docs/cloud/api-reference/plugin-ai/dictionary.md +77 -0
- package/dist/docs/cloud/api-reference/plugin-ai/use-puck-ai.md +175 -0
- package/dist/docs/cloud/api-reference/plugin-ai/with-dynamic-config.md +35 -0
- package/dist/docs/cloud/api-reference/plugin-auth/create-auth-plugin.md +43 -0
- package/dist/docs/cloud/api-reference/plugin-pages/create-pages-plugin.md +65 -0
- package/dist/docs/cloud/auth/overview.md +24 -0
- package/dist/docs/cloud/auth/setup.md +169 -0
- package/dist/docs/cloud/auth-and-identity.md +70 -0
- package/dist/docs/cloud/getting-started.md +47 -0
- package/dist/docs/cloud/overview.md +23 -0
- package/dist/docs/cloud/pages/overview.md +38 -0
- package/dist/docs/cloud/pages/setup.md +80 -0
- package/dist/docs/cloud/server-apis.md +58 -0
- package/dist/docs/cloud/setup-cloud-plugins.md +202 -0
- package/dist/docs/editor/api-reference/actions.md +63 -0
- package/dist/docs/editor/api-reference/components/action-bar-action.md +35 -0
- package/dist/docs/editor/api-reference/components/action-bar-drag-handle.md +33 -0
- package/dist/docs/editor/api-reference/components/action-bar-group.md +24 -0
- package/dist/docs/editor/api-reference/components/action-bar-label.md +25 -0
- package/dist/docs/editor/api-reference/components/action-bar-separator.md +16 -0
- package/dist/docs/editor/api-reference/components/action-bar.md +32 -0
- package/dist/docs/editor/api-reference/components/auto-field.md +62 -0
- package/dist/docs/editor/api-reference/components/drawer-item.md +73 -0
- package/dist/docs/editor/api-reference/components/drawer.md +28 -0
- package/dist/docs/editor/api-reference/components/drop-zone.md +231 -0
- package/dist/docs/editor/api-reference/components/field-group-item.md +39 -0
- package/dist/docs/editor/api-reference/components/field-group.md +86 -0
- package/dist/docs/editor/api-reference/components/field-label.md +135 -0
- package/dist/docs/editor/api-reference/components/field-tab.md +55 -0
- package/dist/docs/editor/api-reference/components/inline-text-field.md +76 -0
- package/dist/docs/editor/api-reference/components/puck-components.md +18 -0
- package/dist/docs/editor/api-reference/components/puck-fields.md +37 -0
- package/dist/docs/editor/api-reference/components/puck-layout.md +26 -0
- package/dist/docs/editor/api-reference/components/puck-outline.md +18 -0
- package/dist/docs/editor/api-reference/components/puck-preview.md +37 -0
- package/dist/docs/editor/api-reference/components/puck.md +564 -0
- package/dist/docs/editor/api-reference/components/render.md +113 -0
- package/dist/docs/editor/api-reference/components/rich-text-menu-control.md +87 -0
- package/dist/docs/editor/api-reference/components/rich-text-menu-group.md +27 -0
- package/dist/docs/editor/api-reference/components/rich-text-menu.md +99 -0
- package/dist/docs/editor/api-reference/components.md +36 -0
- package/dist/docs/editor/api-reference/configuration/component-config.md +611 -0
- package/dist/docs/editor/api-reference/configuration/config.md +108 -0
- package/dist/docs/editor/api-reference/configuration.md +4 -0
- package/dist/docs/editor/api-reference/data-model/app-state.md +182 -0
- package/dist/docs/editor/api-reference/data-model/component-data.md +62 -0
- package/dist/docs/editor/api-reference/data-model/data.md +95 -0
- package/dist/docs/editor/api-reference/data-model/item-selector.md +34 -0
- package/dist/docs/editor/api-reference/data-model/root-data.md +59 -0
- package/dist/docs/editor/api-reference/data-model.md +8 -0
- package/dist/docs/editor/api-reference/dictionary.md +173 -0
- package/dist/docs/editor/api-reference/field-transforms.md +51 -0
- package/dist/docs/editor/api-reference/fields/array.md +211 -0
- package/dist/docs/editor/api-reference/fields/base.md +96 -0
- package/dist/docs/editor/api-reference/fields/checkbox.md +87 -0
- package/dist/docs/editor/api-reference/fields/custom.md +191 -0
- package/dist/docs/editor/api-reference/fields/external.md +413 -0
- package/dist/docs/editor/api-reference/fields/number.md +132 -0
- package/dist/docs/editor/api-reference/fields/object.md +100 -0
- package/dist/docs/editor/api-reference/fields/radio.md +82 -0
- package/dist/docs/editor/api-reference/fields/richtext.md +415 -0
- package/dist/docs/editor/api-reference/fields/select.md +79 -0
- package/dist/docs/editor/api-reference/fields/slot.md +306 -0
- package/dist/docs/editor/api-reference/fields/text.md +93 -0
- package/dist/docs/editor/api-reference/fields/textarea.md +93 -0
- package/dist/docs/editor/api-reference/fields.md +17 -0
- package/dist/docs/editor/api-reference/functions/migrate.md +203 -0
- package/dist/docs/editor/api-reference/functions/register-overlay-portal.md +44 -0
- package/dist/docs/editor/api-reference/functions/resolve-all-data.md +26 -0
- package/dist/docs/editor/api-reference/functions/set-deep.md +54 -0
- package/dist/docs/editor/api-reference/functions/transform-props.md +50 -0
- package/dist/docs/editor/api-reference/functions/use-get-puck.md +23 -0
- package/dist/docs/editor/api-reference/functions/use-puck.md +42 -0
- package/dist/docs/editor/api-reference/functions/walk-tree.md +87 -0
- package/dist/docs/editor/api-reference/functions.md +8 -0
- package/dist/docs/editor/api-reference/overrides/action-bar.md +50 -0
- package/dist/docs/editor/api-reference/overrides/component-overlay.md +41 -0
- package/dist/docs/editor/api-reference/overrides/drawer-item.md +24 -0
- package/dist/docs/editor/api-reference/overrides/drawer.md +19 -0
- package/dist/docs/editor/api-reference/overrides/field-label.md +18 -0
- package/dist/docs/editor/api-reference/overrides/field-types.md +51 -0
- package/dist/docs/editor/api-reference/overrides/fields.md +45 -0
- package/dist/docs/editor/api-reference/overrides/header-actions.md +24 -0
- package/dist/docs/editor/api-reference/overrides/header.md +29 -0
- package/dist/docs/editor/api-reference/overrides/iframe.md +32 -0
- package/dist/docs/editor/api-reference/overrides/outline.md +19 -0
- package/dist/docs/editor/api-reference/overrides/preview.md +19 -0
- package/dist/docs/editor/api-reference/overrides/puck.md +19 -0
- package/dist/docs/editor/api-reference/overrides.md +28 -0
- package/dist/docs/editor/api-reference/permissions.md +55 -0
- package/dist/docs/editor/api-reference/plugin.md +111 -0
- package/dist/docs/editor/api-reference/plugins/blocks-plugin.md +53 -0
- package/dist/docs/editor/api-reference/plugins/fields-plugin.md +64 -0
- package/dist/docs/editor/api-reference/plugins/legacy-side-bar-plugin.md +51 -0
- package/dist/docs/editor/api-reference/plugins/outline-plugin.md +53 -0
- package/dist/docs/editor/api-reference/puck-api.md +279 -0
- package/dist/docs/editor/api-reference/theming/action-bar.md +32 -0
- package/dist/docs/editor/api-reference/theming/button.md +65 -0
- package/dist/docs/editor/api-reference/theming/canvas.md +20 -0
- package/dist/docs/editor/api-reference/theming/computed-values.md +209 -0
- package/dist/docs/editor/api-reference/theming/drawer.md +34 -0
- package/dist/docs/editor/api-reference/theming/field-tabs.md +28 -0
- package/dist/docs/editor/api-reference/theming/fields.md +77 -0
- package/dist/docs/editor/api-reference/theming/global.md +127 -0
- package/dist/docs/editor/api-reference/theming/header.md +19 -0
- package/dist/docs/editor/api-reference/theming/icon-button.md +28 -0
- package/dist/docs/editor/api-reference/theming/outline.md +35 -0
- package/dist/docs/editor/api-reference/theming/plugin-bar.md +24 -0
- package/dist/docs/editor/api-reference/theming/sidebar.md +19 -0
- package/dist/docs/editor/api-reference/theming/slot.md +27 -0
- package/dist/docs/editor/components-and-fields/component-configuration.md +157 -0
- package/dist/docs/editor/components-and-fields/custom-fields.md +131 -0
- package/dist/docs/editor/components-and-fields/dynamic-fields.md +86 -0
- package/dist/docs/editor/components-and-fields/field-grouping.md +149 -0
- package/dist/docs/editor/components-and-fields/field-transforms.md +102 -0
- package/dist/docs/editor/components-and-fields/multi-column-layouts.md +226 -0
- package/dist/docs/editor/components-and-fields/overlay-portals.md +29 -0
- package/dist/docs/editor/components-and-fields/rich-text-editing.md +224 -0
- package/dist/docs/editor/components-and-fields/root-configuration.md +170 -0
- package/dist/docs/editor/customize/categories.md +91 -0
- package/dist/docs/editor/customize/composition.md +53 -0
- package/dist/docs/editor/customize/feature-toggling.md +121 -0
- package/dist/docs/editor/customize/internal-puck-api.md +94 -0
- package/dist/docs/editor/customize/localization.md +216 -0
- package/dist/docs/editor/customize/plugins.md +154 -0
- package/dist/docs/editor/customize/styling.md +117 -0
- package/dist/docs/editor/customize/theming.md +89 -0
- package/dist/docs/editor/customize/ui-overrides.md +130 -0
- package/dist/docs/editor/customize/viewports.md +74 -0
- package/dist/docs/editor/data-and-rendering/dynamic-props.md +136 -0
- package/dist/docs/editor/data-and-rendering/external-data-sources.md +149 -0
- package/dist/docs/editor/data-and-rendering/save-and-render-pages.md +78 -0
- package/dist/docs/editor/data-and-rendering/server-components.md +186 -0
- package/dist/docs/editor/getting-started.md +60 -0
- package/dist/docs/editor/migrations/data-migration.md +83 -0
- package/dist/docs/editor/migrations/dropzones-to-slots.md +136 -0
- package/dist/docs/editor/overview.md +27 -0
- package/dist/docs/index.json +704 -0
- package/dist/templates/next/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/next/app/puck/page.tsx +0 -2
- package/dist/templates/next-ai/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/next-ai/app/puck/page.tsx +0 -2
- package/dist/templates/vinext/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/vinext/app/puck/page.tsx +0 -2
- package/dist/templates/vinext-ai/app/puck/[...puckPath]/page.tsx +3 -2
- package/dist/templates/vinext-ai/app/puck/page.tsx +0 -2
- package/package.json +1 -1
package/dist/bin.mjs
CHANGED
|
@@ -159,6 +159,19 @@ var findStringProperty = (code, filename, key) => {
|
|
|
159
159
|
});
|
|
160
160
|
return result;
|
|
161
161
|
};
|
|
162
|
+
var hasTrueProperty = (code, filename, key) => {
|
|
163
|
+
const ast = tryParseModule(code, filename);
|
|
164
|
+
let found = false;
|
|
165
|
+
if (ast) {
|
|
166
|
+
walk(ast.program, (node) => {
|
|
167
|
+
if (node.type !== "ObjectProperty" || node.computed) return;
|
|
168
|
+
const name = node.key.type === "Identifier" ? node.key.name : node.key.type === "StringLiteral" ? node.key.value : null;
|
|
169
|
+
if (name === key && node.value.type === "BooleanLiteral")
|
|
170
|
+
found ||= node.value.value;
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
return found;
|
|
174
|
+
};
|
|
162
175
|
|
|
163
176
|
// src/detect/package-json.ts
|
|
164
177
|
import path from "path";
|
|
@@ -340,6 +353,18 @@ var findViteConfig = (vfs, root) => firstExisting(
|
|
|
340
353
|
root,
|
|
341
354
|
CONFIG_EXTENSIONS.map((ext) => `vite.config.${ext}`)
|
|
342
355
|
);
|
|
356
|
+
var detectCacheComponents = (vfs, root) => {
|
|
357
|
+
const config = firstExisting(
|
|
358
|
+
vfs,
|
|
359
|
+
root,
|
|
360
|
+
CONFIG_EXTENSIONS.map((ext) => `next.config.${ext}`)
|
|
361
|
+
);
|
|
362
|
+
return config ? hasTrueProperty(
|
|
363
|
+
vfs.readText(path3.join(root, config)) ?? "",
|
|
364
|
+
config,
|
|
365
|
+
"cacheComponents"
|
|
366
|
+
) : false;
|
|
367
|
+
};
|
|
343
368
|
var normalizeDir = (dir) => path3.posix.normalize(dir).replace(/^\.\/?$/, "").replace(/\/+$/, "");
|
|
344
369
|
var dynamicConfig = (file, what) => ({
|
|
345
370
|
status: "unsupported",
|
|
@@ -396,7 +421,8 @@ var detectNext = (vfs, root, range) => {
|
|
|
396
421
|
version,
|
|
397
422
|
major: major2,
|
|
398
423
|
...layout,
|
|
399
|
-
proxyKind: major2 >= 16 ? "proxy" : "middleware"
|
|
424
|
+
proxyKind: major2 >= 16 ? "proxy" : "middleware",
|
|
425
|
+
cacheComponents: detectCacheComponents(vfs, root)
|
|
400
426
|
}
|
|
401
427
|
};
|
|
402
428
|
};
|
|
@@ -418,6 +444,7 @@ var detectVinext = (vfs, root, range) => {
|
|
|
418
444
|
major: majorOf(version) ?? majorOf(range),
|
|
419
445
|
...layout,
|
|
420
446
|
proxyKind: hasMiddleware ? "middleware" : "proxy",
|
|
447
|
+
cacheComponents: false,
|
|
421
448
|
viteConfig: findViteConfig(vfs, root)
|
|
422
449
|
}
|
|
423
450
|
};
|
|
@@ -1918,6 +1945,27 @@ var configImportClause = (shape, local) => {
|
|
|
1918
1945
|
if (shape.named.length === 1) return `{ ${shape.named[0]} as ${local} }`;
|
|
1919
1946
|
return null;
|
|
1920
1947
|
};
|
|
1948
|
+
var INSTANT = `// Cache Components: allow rendering on request, outside <Suspense>
|
|
1949
|
+
export const instant = false;`;
|
|
1950
|
+
var cacheComponentsEdits = (ast, code) => {
|
|
1951
|
+
const dynamic = ast.program.body.find(
|
|
1952
|
+
(s) => s.type === "ExportNamedDeclaration" && s.declaration?.type === "VariableDeclaration" && s.declaration.declarations.some(
|
|
1953
|
+
(d) => d.id.type === "Identifier" && d.id.name === "dynamic"
|
|
1954
|
+
)
|
|
1955
|
+
);
|
|
1956
|
+
if (!dynamic) {
|
|
1957
|
+
return [{ start: code.length, end: code.length, text: `
|
|
1958
|
+
${INSTANT}
|
|
1959
|
+
` }];
|
|
1960
|
+
}
|
|
1961
|
+
return [
|
|
1962
|
+
{
|
|
1963
|
+
start: dynamic.leadingComments?.[0]?.start ?? dynamic.start,
|
|
1964
|
+
end: dynamic.end,
|
|
1965
|
+
text: INSTANT
|
|
1966
|
+
}
|
|
1967
|
+
];
|
|
1968
|
+
};
|
|
1921
1969
|
var TYPE_FALLBACKS = {
|
|
1922
1970
|
UserData: 'import("@puckeditor/core").Data'
|
|
1923
1971
|
};
|
|
@@ -2010,6 +2058,9 @@ var relocateModule = (code, opts) => {
|
|
|
2010
2058
|
});
|
|
2011
2059
|
}
|
|
2012
2060
|
}
|
|
2061
|
+
if (opts.cacheComponents && /(^|\/)page\.[jt]sx?$/.test(opts.to)) {
|
|
2062
|
+
edits.push(...cacheComponentsEdits(ast, code));
|
|
2063
|
+
}
|
|
2013
2064
|
return { ok: true, code: applyEdits(code, edits) };
|
|
2014
2065
|
};
|
|
2015
2066
|
|
|
@@ -2596,6 +2647,7 @@ import "@puckeditor/core/puck.css";
|
|
|
2596
2647
|
${ai ? `import "@puckeditor/plugin-ai/styles.css";
|
|
2597
2648
|
` : ""}import "@puckeditor/plugin-pages/styles.css";
|
|
2598
2649
|
import { Metadata } from "next";
|
|
2650
|
+
import { connection } from "next/server";
|
|
2599
2651
|
import { Client } from "./client";${auth ? `
|
|
2600
2652
|
import { requirePuckSession } from "../../../lib/puck-auth";` : ""}
|
|
2601
2653
|
|
|
@@ -2610,15 +2662,18 @@ ${auth ? `export default async function Page({
|
|
|
2610
2662
|
}: {
|
|
2611
2663
|
searchParams: Promise<Record<string, string>>;
|
|
2612
2664
|
}) {
|
|
2665
|
+
// Puck renders in the browser, so the editor is rendered on every request
|
|
2666
|
+
await connection();
|
|
2613
2667
|
const query = new URLSearchParams(await searchParams).toString();
|
|
2614
2668
|
await requirePuckSession(\`/puck\${query ? \`?\${query}\` : ""}\`);
|
|
2615
2669
|
|
|
2616
2670
|
return <Client />;
|
|
2617
2671
|
}` : `export default async function Page() {
|
|
2672
|
+
// Puck renders in the browser, so the editor is rendered on every request
|
|
2673
|
+
await connection();
|
|
2674
|
+
|
|
2618
2675
|
return <Client />;
|
|
2619
2676
|
}`}
|
|
2620
|
-
|
|
2621
|
-
export const dynamic = "force-dynamic";
|
|
2622
2677
|
`;
|
|
2623
2678
|
var nextPagesRenderPage = (host) => `/**
|
|
2624
2679
|
* This file implements a catch-all route that renders the pages published in
|
|
@@ -3334,7 +3389,8 @@ var nextRelocation = (p, info) => {
|
|
|
3334
3389
|
"lib/puck-auth": `${lib}/puck-auth`,
|
|
3335
3390
|
"puck.config": configModuleTarget(p)
|
|
3336
3391
|
},
|
|
3337
|
-
config: configRelocation(p)
|
|
3392
|
+
config: configRelocation(p),
|
|
3393
|
+
cacheComponents: info.cacheComponents
|
|
3338
3394
|
};
|
|
3339
3395
|
};
|
|
3340
3396
|
var conflictingSegments = (p, appDir) => {
|
|
@@ -11658,7 +11714,7 @@ runCli(process.argv.slice(2), {
|
|
|
11658
11714
|
stdout: process.stdout,
|
|
11659
11715
|
stderr: process.stderr,
|
|
11660
11716
|
stdinIsTTY: Boolean(process.stdin.isTTY),
|
|
11661
|
-
cliVersion: "0.24.0-canary.
|
|
11717
|
+
cliVersion: "0.24.0-canary.c9aa1fa8",
|
|
11662
11718
|
invocation: localInvocation(
|
|
11663
11719
|
fs8.realpathSync(fileURLToPath(import.meta.url)),
|
|
11664
11720
|
fs8.realpathSync(process.cwd()),
|
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
# Assembly Mode
|
|
2
|
+
|
|
3
|
+
Assembly mode allows Puck AI to create pages from your existing components.
|
|
4
|
+
|
|
5
|
+
You can control agent behavior via the `ai` parameter on both [component](/docs/cloud/api-reference/plugin-ai/ai-configuration/components) and [field](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields) configs.
|
|
6
|
+
|
|
7
|
+
## Providing instructions
|
|
8
|
+
|
|
9
|
+
The `instructions` parameter provides the agent with natural-language guidance on how to use a component or field.
|
|
10
|
+
|
|
11
|
+
Here's an example using [`instructions` on components](/docs/cloud/api-reference/plugin-ai/ai-configuration/components#instructions):
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
const config = {
|
|
15
|
+
components: {
|
|
16
|
+
HeadingBlock: {
|
|
17
|
+
ai: {
|
|
18
|
+
instructions: "Always place this first",
|
|
19
|
+
},
|
|
20
|
+
fields: {
|
|
21
|
+
title: {
|
|
22
|
+
type: "text",
|
|
23
|
+
},
|
|
24
|
+
},
|
|
25
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
26
|
+
},
|
|
27
|
+
},
|
|
28
|
+
};
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
And using [`instructions` on fields](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#instructions):
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
const config = {
|
|
35
|
+
components: {
|
|
36
|
+
HeadingBlock: {
|
|
37
|
+
fields: {
|
|
38
|
+
title: {
|
|
39
|
+
type: "text",
|
|
40
|
+
ai: {
|
|
41
|
+
instructions: "Always use caps",
|
|
42
|
+
},
|
|
43
|
+
},
|
|
44
|
+
},
|
|
45
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
46
|
+
},
|
|
47
|
+
},
|
|
48
|
+
};
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Setting a schema
|
|
52
|
+
|
|
53
|
+
Some field types like [`custom`](/docs/editor/api-reference/fields/custom), [`external`](/docs/editor/api-reference/fields/external), or [user fields](/docs/editor/api-reference/overrides/field-types), are not supported without further configuration. This is because the shape of the data produced by those fields is unknown to the agent.
|
|
54
|
+
|
|
55
|
+
To address this, provide a [`schema`](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#schema) using JSON Schema:
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
const config = {
|
|
59
|
+
components: {
|
|
60
|
+
HeadingBlock: {
|
|
61
|
+
fields: {
|
|
62
|
+
title: {
|
|
63
|
+
type: "custom",
|
|
64
|
+
ai: {
|
|
65
|
+
schema: { type: "text" },
|
|
66
|
+
},
|
|
67
|
+
render: () => <input />,
|
|
68
|
+
},
|
|
69
|
+
},
|
|
70
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
71
|
+
},
|
|
72
|
+
},
|
|
73
|
+
};
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
We recommend using [Zod](https://zod.dev/json-schema) to help with producing JSON Schema for complex shapes:
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
|
|
80
|
+
const config = {
|
|
81
|
+
components: {
|
|
82
|
+
HeadingBlock: {
|
|
83
|
+
fields: {
|
|
84
|
+
object: {
|
|
85
|
+
type: "custom",
|
|
86
|
+
ai: {
|
|
87
|
+
schema: z.toJSONSchema(
|
|
88
|
+
z.object({
|
|
89
|
+
title: z.string(),
|
|
90
|
+
})
|
|
91
|
+
),
|
|
92
|
+
},
|
|
93
|
+
render: () => <input />,
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
render: ({ object }) => <h1>{object.title}</h1>,
|
|
97
|
+
},
|
|
98
|
+
},
|
|
99
|
+
};
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Excluding components
|
|
103
|
+
|
|
104
|
+
To completely ignore a component when generating a page, use the [`exclude` API](/docs/cloud/api-reference/plugin-ai/ai-configuration/components#exclude):
|
|
105
|
+
|
|
106
|
+
```tsx
|
|
107
|
+
const config = {
|
|
108
|
+
components: {
|
|
109
|
+
HeadingBlock: {
|
|
110
|
+
fields: {
|
|
111
|
+
title: { type: "text" },
|
|
112
|
+
},
|
|
113
|
+
ai: {
|
|
114
|
+
exclude: true,
|
|
115
|
+
},
|
|
116
|
+
render: ({ title }) => <h1>{title}</h1>,
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
};
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Disabling streaming
|
|
123
|
+
|
|
124
|
+
When using the [AI plugin](/docs/cloud/api-reference/plugin-ai/create-ai-plugin), Puck AI will stream field values wherever possible. This can sometimes result in unexpected behavior when rendering the preview, such as broken image URLs.
|
|
125
|
+
|
|
126
|
+
You can set the [`stream` parameter](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#stream) to `false` to disable streaming of a field:
|
|
127
|
+
|
|
128
|
+
```tsx
|
|
129
|
+
const config = {
|
|
130
|
+
components: {
|
|
131
|
+
HeadingBlock: {
|
|
132
|
+
fields: {
|
|
133
|
+
src: {
|
|
134
|
+
type: "text",
|
|
135
|
+
ai: {
|
|
136
|
+
stream: false,
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
},
|
|
140
|
+
render: ({ src }) => <img src={src} />,
|
|
141
|
+
},
|
|
142
|
+
},
|
|
143
|
+
};
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## Setting required fields
|
|
147
|
+
|
|
148
|
+
By default, all fields provided in [`defaultProps`](/docs/editor/api-reference/configuration/component-config#defaultprops) are considered required by the agent.
|
|
149
|
+
|
|
150
|
+
You can explicitly mark a field as required or optional by using the [`required` parameter](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#required).
|
|
151
|
+
|
|
152
|
+
```tsx
|
|
153
|
+
const config = {
|
|
154
|
+
components: {
|
|
155
|
+
HeadingBlock: {
|
|
156
|
+
fields: {
|
|
157
|
+
src: {
|
|
158
|
+
type: "text",
|
|
159
|
+
ai: {
|
|
160
|
+
required: true, // Mark this as required, even though it doesn't exist in defaultProps
|
|
161
|
+
},
|
|
162
|
+
},
|
|
163
|
+
},
|
|
164
|
+
render: ({ src }) => <img src={src} />,
|
|
165
|
+
defaultProps: {},
|
|
166
|
+
},
|
|
167
|
+
},
|
|
168
|
+
};
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Excluding fields
|
|
172
|
+
|
|
173
|
+
To completely ignore a field when generating a page, use the [`exclude` API](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields#exclude):
|
|
174
|
+
|
|
175
|
+
```tsx
|
|
176
|
+
const config = {
|
|
177
|
+
components: {
|
|
178
|
+
HeadingBlock: {
|
|
179
|
+
fields: {
|
|
180
|
+
src: {
|
|
181
|
+
type: "text",
|
|
182
|
+
ai: {
|
|
183
|
+
exclude: true,
|
|
184
|
+
},
|
|
185
|
+
},
|
|
186
|
+
},
|
|
187
|
+
render: ({ src }) => <img src={src} />,
|
|
188
|
+
},
|
|
189
|
+
},
|
|
190
|
+
};
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
## Registering reusable field types
|
|
194
|
+
|
|
195
|
+
A [user field type](/docs/editor/api-reference/overrides/field-types) can be shared by many fields. Rather than repeating `ai.schema` on each one, describe the type once via `fieldTypes`.
|
|
196
|
+
|
|
197
|
+
Field types can be provided to the AI plugin:
|
|
198
|
+
|
|
199
|
+
```tsx
|
|
200
|
+
const aiPlugin = createAiPlugin({
|
|
201
|
+
fieldTypes: {
|
|
202
|
+
cta: {
|
|
203
|
+
// Included in the prompt, so describe any rules for using the field
|
|
204
|
+
description: "Renders a call-to-action button",
|
|
205
|
+
schema: {
|
|
206
|
+
type: "object",
|
|
207
|
+
properties: {
|
|
208
|
+
label: { type: "string" },
|
|
209
|
+
},
|
|
210
|
+
},
|
|
211
|
+
},
|
|
212
|
+
},
|
|
213
|
+
});
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
or `ai.generate`:
|
|
217
|
+
|
|
218
|
+
```tsx
|
|
219
|
+
const { data } = await puck.ai.generate({
|
|
220
|
+
prompt: "Create a page about our products",
|
|
221
|
+
config,
|
|
222
|
+
fieldTypes: {
|
|
223
|
+
cta: {
|
|
224
|
+
// Included in the prompt, so describe any rules for using the field
|
|
225
|
+
description: "Renders a call-to-action button",
|
|
226
|
+
schema: {
|
|
227
|
+
type: "object",
|
|
228
|
+
properties: {
|
|
229
|
+
label: { type: "string" },
|
|
230
|
+
},
|
|
231
|
+
},
|
|
232
|
+
},
|
|
233
|
+
},
|
|
234
|
+
});
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
When using this field, Puck AI will generate against the `schema`.
|
|
238
|
+
|
|
239
|
+
Omit `schema` and provide a `defaultValue` to have Puck AI add a field without generating the value.
|
|
240
|
+
|
|
241
|
+
```tsx
|
|
242
|
+
const aiPlugin = createAiPlugin({
|
|
243
|
+
fieldTypes: {
|
|
244
|
+
timer: {
|
|
245
|
+
defaultValue: { label: "Countdown" },
|
|
246
|
+
description: "Renders a countdown",
|
|
247
|
+
},
|
|
248
|
+
},
|
|
249
|
+
});
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
## Rendering components as fields
|
|
253
|
+
|
|
254
|
+
By combining `fieldTypes` with [field transforms](/docs/editor/components-and-fields/field-transforms), Puck AI can render your components using fields. This works with [design mode](/docs/cloud/ai/design-mode).
|
|
255
|
+
|
|
256
|
+
```tsx
|
|
257
|
+
const fieldTransforms = {
|
|
258
|
+
cta: ({ value }) => <button>{value.label}</button>,
|
|
259
|
+
};
|
|
260
|
+
|
|
261
|
+
const Example = () => <Puck fieldTransforms={fieldTransforms} />;
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
## Further reading
|
|
265
|
+
|
|
266
|
+
- [Field AI Config API reference](/docs/cloud/api-reference/plugin-ai/ai-configuration/fields)
|
|
267
|
+
- [Component AI Config API reference](/docs/cloud/api-reference/plugin-ai/ai-configuration/components)
|
|
268
|
+
- [`AiFieldType` API reference](/docs/cloud/api-reference/plugin-ai/ai-field-type)
|
|
269
|
+
- [`createAiPlugin()` API reference](/docs/cloud/api-reference/plugin-ai/create-ai-plugin)
|
|
270
|
+
- [Field transforms](/docs/editor/components-and-fields/field-transforms)
|
|
271
|
+
- [Design mode](/docs/cloud/ai/design-mode)
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Business Context
|
|
2
|
+
|
|
3
|
+
Providing business context enables Puck AI to understand your business and build relevant pages. It applies in both assembly and design modes.
|
|
4
|
+
|
|
5
|
+
## Context for AI plugin
|
|
6
|
+
|
|
7
|
+
When using the [AI plugin](/docs/cloud/api-reference/plugin-ai/create-ai-plugin), you can provide context to all interactions by using the [`ai.context`](/docs/cloud/api-reference/cloud-client/puck-handler#aicontext) parameter in the [`puckHandler()`](/docs/cloud/api-reference/cloud-client/puck-handler).
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
|
|
11
|
+
export async function POST(request) {
|
|
12
|
+
return puckHandler(request, {
|
|
13
|
+
ai: {
|
|
14
|
+
context: "We are Google. You create Google landing pages.",
|
|
15
|
+
},
|
|
16
|
+
});
|
|
17
|
+
}
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
You can use this parameter to provide extensive information for your use-case:
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
|
|
24
|
+
const context = `## Overview
|
|
25
|
+
We are Google. You help us build Google landing pages.
|
|
26
|
+
|
|
27
|
+
## Brand guidelines
|
|
28
|
+
|
|
29
|
+
Our brand colors are:
|
|
30
|
+
|
|
31
|
+
- #4285F4 (primary)
|
|
32
|
+
- #DB4437
|
|
33
|
+
- #F4B400
|
|
34
|
+
- #0F9D58
|
|
35
|
+
|
|
36
|
+
## Tone of voice
|
|
37
|
+
|
|
38
|
+
- American English
|
|
39
|
+
- ...
|
|
40
|
+
`;
|
|
41
|
+
|
|
42
|
+
export async function POST(request) {
|
|
43
|
+
return puckHandler(request, {
|
|
44
|
+
ai: {
|
|
45
|
+
context,
|
|
46
|
+
},
|
|
47
|
+
});
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Context for server APIs
|
|
52
|
+
|
|
53
|
+
The `context` parameter on [`ai.generate()`](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate#context) allows you to provide additional business information when [generating pages headlessly](/docs/cloud/ai/headless-generation):
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
|
|
57
|
+
const puck = puckCloud();
|
|
58
|
+
|
|
59
|
+
await puck.ai.generate({
|
|
60
|
+
config,
|
|
61
|
+
context: "We are Google. You help us build Google landing pages.",
|
|
62
|
+
prompt: "Create a page about our maps product",
|
|
63
|
+
});
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Further reading
|
|
67
|
+
|
|
68
|
+
- [`ai.generate()` API reference](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate)
|
|
69
|
+
- [`puckHandler()` API reference](/docs/cloud/api-reference/cloud-client/puck-handler)
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# Custom Agents
|
|
2
|
+
|
|
3
|
+
Build custom chat and AI streaming interfaces using the [`usePuckAi()` API](/docs/cloud/api-reference/plugin-ai/use-puck-ai).
|
|
4
|
+
|
|
5
|
+
## Build a chat interface
|
|
6
|
+
|
|
7
|
+
Use [`usePuckAi().chat`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#returns) to hold a conversation with the agent, sending and reading messages. Changes are automatically applied to the canvas.
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
|
|
11
|
+
function ChatPlugin() {
|
|
12
|
+
const { chat } = usePuckAi();
|
|
13
|
+
const [input, setInput] = useState("");
|
|
14
|
+
|
|
15
|
+
return (
|
|
16
|
+
<div>
|
|
17
|
+
{chat.messages.map((message) =>
|
|
18
|
+
message.parts.map((part, i) =>
|
|
19
|
+
part.type === "text" ? <p key={i}>{part.text}</p> : null
|
|
20
|
+
)
|
|
21
|
+
)}
|
|
22
|
+
|
|
23
|
+
<form
|
|
24
|
+
onSubmit={(e) => {
|
|
25
|
+
e.preventDefault();
|
|
26
|
+
chat.sendMessage(input);
|
|
27
|
+
setInput("");
|
|
28
|
+
}}
|
|
29
|
+
>
|
|
30
|
+
<input value={input} onChange={(e) => setInput(e.target.value)} />
|
|
31
|
+
<button>Send</button>
|
|
32
|
+
</form>
|
|
33
|
+
</div>
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export function Editor() {
|
|
38
|
+
return (
|
|
39
|
+
<Puck
|
|
40
|
+
config={config}
|
|
41
|
+
data={data}
|
|
42
|
+
plugins={[{ name: "chat", label: "Chat", render: ChatPlugin }]}
|
|
43
|
+
/>
|
|
44
|
+
);
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Show the agent's progress
|
|
49
|
+
|
|
50
|
+
Look up each tool part in [`chat.toolStatus`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#chattoolstatus) to show what the agent is doing.
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
message.parts.map((part, i) => {
|
|
54
|
+
if (part.type === "text") return <p key={i}>{part.text}</p>;
|
|
55
|
+
|
|
56
|
+
// For example, "Updating page"
|
|
57
|
+
if ("toolCallId" in part) {
|
|
58
|
+
return <p key={i}>{chat.toolStatus[part.toolCallId]?.label}</p>;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
return null;
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Request a single change
|
|
66
|
+
|
|
67
|
+
Use [`usePuckAi().generate()`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#generateprompt-options) to request a change to the current page, outside of a conversation.
|
|
68
|
+
|
|
69
|
+
```tsx
|
|
70
|
+
|
|
71
|
+
function TranslatePlugin({ language }) {
|
|
72
|
+
const { generate } = usePuckAi();
|
|
73
|
+
|
|
74
|
+
return (
|
|
75
|
+
<button onClick={() => generate(`Translate this page to ${language}`)}>
|
|
76
|
+
Translate
|
|
77
|
+
</button>
|
|
78
|
+
);
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Replaying generations
|
|
83
|
+
|
|
84
|
+
You can replay a generation created headlessly using the server [`ai.generate()`](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate) API.
|
|
85
|
+
|
|
86
|
+
To record a generation, use [`onPart`](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate#onpart) to store each [AI Part](/docs/cloud/api-reference/plugin-ai/ai-part):
|
|
87
|
+
|
|
88
|
+
File: `server.ts`
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
|
|
92
|
+
const puck = puckCloud();
|
|
93
|
+
|
|
94
|
+
await puck.ai.generate({
|
|
95
|
+
prompt: "Add a pricing section",
|
|
96
|
+
config,
|
|
97
|
+
pageData,
|
|
98
|
+
onPart: (part) => {
|
|
99
|
+
// Store the part
|
|
100
|
+
},
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
To replay the parts into the editor, provide the stored parts to [`usePuckAi().applyPart`](/docs/cloud/api-reference/plugin-ai/use-puck-ai#applypartpart-options):
|
|
105
|
+
|
|
106
|
+
File: `ApplyPlugin.tsx`
|
|
107
|
+
|
|
108
|
+
```tsx
|
|
109
|
+
|
|
110
|
+
function ApplyPlugin() {
|
|
111
|
+
const { applyPart } = usePuckAi();
|
|
112
|
+
|
|
113
|
+
const apply = async () => {
|
|
114
|
+
const parts = getMyParts(); // Get parts from wherever you stored them
|
|
115
|
+
|
|
116
|
+
for await (const part of parts) {
|
|
117
|
+
await applyPart(part); // Apply them
|
|
118
|
+
}
|
|
119
|
+
};
|
|
120
|
+
|
|
121
|
+
return <button onClick={apply}>Apply</button>;
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
By default, the server's `ai.generate()` will run a single iteration. See [multi-step headless generation](/docs/cloud/ai/headless-generation#multi-step-headless-generation) to learn more.
|
|
126
|
+
|
|
127
|
+
## Further reading
|
|
128
|
+
|
|
129
|
+
- [`usePuckAi()` API reference](/docs/cloud/api-reference/plugin-ai/use-puck-ai)
|
|
130
|
+
- [`ai.generate()` API reference](/docs/cloud/api-reference/cloud-client/server-apis/ai-generate)
|
|
131
|
+
- [`AIPart` data model](/docs/cloud/api-reference/plugin-ai/ai-part)
|
|
132
|
+
- [`puckHandler()` API reference](/docs/cloud/api-reference/cloud-client/puck-handler)
|
|
133
|
+
- [Headless generation](/docs/cloud/ai/headless-generation)
|