Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

refactor: add templates meta support (#4653)

Bogdan Chadkina32d6329edd8
diff --git a/apps/builder/app/builder/features/components/components.tsx b/apps/builder/app/builder/features/components/components.tsx
index bb45a65752..cfe9ee8220 100644
--- a/apps/builder/app/builder/features/components/components.tsx
+++ b/apps/builder/app/builder/features/components/components.tsx
@@ -30,7 +30,10 @@ import {
import { CollapsibleSection } from "~/builder/shared/collapsible-section";
import { dragItemAttribute, useDraggable } from "./use-draggable";
import { MetaIcon } from "~/builder/shared/meta-icon";
-import { $registeredComponentMetas } from "~/shared/nano-states";
+import {
+ $registeredComponentMetas,
+ $registeredTemplates,
+} from "~/shared/nano-states";
import {
findClosestInsertable,
getComponentTemplateData,
@@ -50,31 +53,45 @@ type Meta = {
icon: string;
};
-const $metas = computed([$registeredComponentMetas], (componentMetas) => {
- const availableComponents = new Set<string>();
- const metas: Meta[] = [];
- for (const [name, componentMeta] of componentMetas) {
- availableComponents.add(name);
- metas.push({
- name,
- category: componentMeta.category ?? "hidden",
- order: componentMeta.order,
- label: getInstanceLabel({ component: name }, componentMeta),
- description: componentMeta.description,
- icon: componentMeta.icon,
- });
- }
- const metasByCategory = mapGroupBy(metas, (meta) => meta.category);
- for (const meta of metasByCategory.values()) {
- meta.sort((metaA, metaB) => {
- return (
- (metaA.order ?? Number.MAX_SAFE_INTEGER) -
- (metaB.order ?? Number.MAX_SAFE_INTEGER)
- );
- });
+const $metas = computed(
+ [$registeredComponentMetas, $registeredTemplates],
+ (componentMetas, templates) => {
+ const availableComponents = new Set<string>();
+ const metas: Meta[] = [];
+ for (const [name, componentMeta] of componentMetas) {
+ // only set available components from component meta
+ availableComponents.add(name);
+ metas.push({
+ name,
+ category: componentMeta.category ?? "hidden",
+ order: componentMeta.order,
+ label: getInstanceLabel({ component: name }, componentMeta),
+ description: componentMeta.description,
+ icon: componentMeta.icon,
+ });
+ }
+ for (const [name, templateMeta] of templates) {
+ metas.push({
+ name,
+ category: templateMeta.category ?? "hidden",
+ order: templateMeta.order,
+ label: getInstanceLabel({ component: name }, templateMeta),
+ description: templateMeta.description,
+ icon: templateMeta.icon ?? componentMetas.get(name)?.icon ?? "",
+ });
+ }
+ const metasByCategory = mapGroupBy(metas, (meta) => meta.category);
+ for (const meta of metasByCategory.values()) {
+ meta.sort((metaA, metaB) => {
+ return (
+ (metaA.order ?? Number.MAX_SAFE_INTEGER) -
+ (metaB.order ?? Number.MAX_SAFE_INTEGER)
+ );
+ });
+ }
+ return { metasByCategory, availableComponents };
}
- return { metasByCategory, availableComponents };
-});
+);
type Groups = Array<{
category: Exclude<WsComponentMeta["category"], undefined> | "found";
diff --git a/apps/builder/app/builder/features/settings-panel/props-section/props-section.stories.tsx b/apps/builder/app/builder/features/settings-panel/props-section/props-section.stories.tsx
index 94533128ce..8e040e1eee 100644
--- a/apps/builder/app/builder/features/settings-panel/props-section/props-section.stories.tsx
+++ b/apps/builder/app/builder/features/settings-panel/props-section/props-section.stories.tsx
@@ -206,6 +206,7 @@ const checkProp = (options = defaultOptions, label?: string): PropMeta => ({
registerComponentLibrary({
components: {},
metas: {},
+ templates: {},
propsMetas: {
Box: {
props: {
diff --git a/apps/builder/app/canvas/canvas.tsx b/apps/builder/app/canvas/canvas.tsx
index 62f437054a..daa972b882 100644
--- a/apps/builder/app/canvas/canvas.tsx
+++ b/apps/builder/app/canvas/canvas.tsx
@@ -13,6 +13,7 @@ import * as baseComponents from "@webstudio-is/sdk-components-react";
import * as baseComponentMetas from "@webstudio-is/sdk-components-react/metas";
import * as baseComponentPropsMetas from "@webstudio-is/sdk-components-react/props";
import { hooks as baseComponentHooks } from "@webstudio-is/sdk-components-react/hooks";
+import * as baseComponentTemplates from "@webstudio-is/sdk-components-react/templates";
import * as radixComponents from "@webstudio-is/sdk-components-react-radix";
import * as radixComponentMetas from "@webstudio-is/sdk-components-react-radix/metas";
import * as radixComponentPropsMetas from "@webstudio-is/sdk-components-react-radix/props";
@@ -218,12 +219,14 @@ export const Canvas = () => {
components: {},
metas: coreMetas,
propsMetas: corePropsMetas,
+ templates: {},
});
registerComponentLibrary({
components: baseComponents,
metas: baseComponentMetas,
propsMetas: baseComponentPropsMetas,
hooks: baseComponentHooks,
+ templates: baseComponentTemplates,
});
registerComponentLibrary({
components: {
@@ -233,6 +236,7 @@ export const Canvas = () => {
},
metas: {},
propsMetas: {},
+ templates: {},
});
registerComponentLibrary({
namespace: "@webstudio-is/sdk-components-react-radix",
@@ -240,6 +244,7 @@ export const Canvas = () => {
metas: radixComponentMetas,
propsMetas: radixComponentPropsMetas,
hooks: radixComponentHooks,
+ templates: {},
});
});
diff --git a/apps/builder/app/shared/instance-utils.ts b/apps/builder/app/shared/instance-utils.ts
index 91666263a2..dbdc493870 100644
--- a/apps/builder/app/shared/instance-utils.ts
+++ b/apps/builder/app/shared/instance-utils.ts
@@ -45,6 +45,7 @@ import {
$breakpoints,
$pages,
$resources,
+ $registeredTemplates,
} from "./nano-states";
import {
type DroppableTarget,
@@ -341,14 +342,21 @@ export const insertWebstudioFragmentAt = (
}
};
-export const getComponentTemplateData = (component: string) => {
+export const getComponentTemplateData = (
+ componentOrTemplate: string
+): WebstudioFragment => {
+ const templates = $registeredTemplates.get();
+ const templateMeta = templates.get(componentOrTemplate);
+ if (templateMeta) {
+ return templateMeta.template;
+ }
const metas = $registeredComponentMetas.get();
- const componentMeta = metas.get(component);
+ const componentMeta = metas.get(componentOrTemplate);
// when template not specified fallback to template with the component
const template = componentMeta?.template ?? [
{
type: "instance",
- component,
+ component: componentOrTemplate,
children: [],
},
];
diff --git a/apps/builder/app/shared/nano-states/components.ts b/apps/builder/app/shared/nano-states/components.ts
index e9acbb2456..ffe1646968 100644
--- a/apps/builder/app/shared/nano-states/components.ts
+++ b/apps/builder/app/shared/nano-states/components.ts
@@ -17,6 +17,11 @@ import type { InstanceSelector } from "../tree-utils";
import { $memoryProps, $props } from "./misc";
import { $instances } from "./instances";
import { $awareness, $selectedPage, getInstanceKey } from "../awareness";
+import {
+ renderTemplate,
+ type GeneratedTemplateMeta,
+ type TemplateMeta,
+} from "@webstudio-is/template";
const createHookContext = (): HookContext => {
const metas = $registeredComponentMetas.get();
@@ -166,6 +171,10 @@ export const $registeredComponentMetas = atom(
new Map<string, WsComponentMeta>()
);
+export const $registeredTemplates = atom(
+ new Map<string, GeneratedTemplateMeta>()
+);
+
export const $registeredComponentPropsMetas = atom(
new Map<string, WsComponentPropsMeta>()
);
@@ -176,6 +185,7 @@ export const registerComponentLibrary = ({
metas,
propsMetas,
hooks,
+ templates,
}: {
namespace?: string;
// simplify adding component libraries
@@ -184,6 +194,7 @@ export const registerComponentLibrary = ({
metas: Record<Instance["component"], WsComponentMeta>;
propsMetas: Record<Instance["component"], WsComponentPropsMeta>;
hooks?: Hook[];
+ templates: Record<Instance["component"], TemplateMeta>;
}) => {
const prefix = namespace === undefined ? "" : `${namespace}:`;
@@ -206,6 +217,17 @@ export const registerComponentLibrary = ({
}
$registeredComponentMetas.set(nextMetas);
+ const prevTemplates = $registeredTemplates.get();
+ const nextTemplates = new Map(prevTemplates);
+ for (const [componentName, meta] of Object.entries(templates)) {
+ const { template, ...generatedMeta } = meta;
+ nextTemplates.set(`${prefix}${componentName}`, {
+ ...generatedMeta,
+ template: renderTemplate(template),
+ });
+ }
+ $registeredTemplates.set(nextTemplates);
+
if (hooks) {
const prevHooks = $registeredComponentHooks.get();
const nextHooks = [...prevHooks, ...hooks];
diff --git a/apps/builder/app/shared/sync/sync-stores.ts b/apps/builder/app/shared/sync/sync-stores.ts
index 3dbf104e66..ef386360bd 100644
--- a/apps/builder/app/shared/sync/sync-stores.ts
+++ b/apps/builder/app/shared/sync/sync-stores.ts
@@ -47,6 +47,7 @@ import {
$textToolbar,
$registeredComponentMetas,
$registeredComponentPropsMetas,
+ $registeredTemplates,
$modifierKeys,
} from "~/shared/nano-states";
import { $ephemeralStyles } from "~/canvas/stores";
@@ -167,6 +168,7 @@ export const createObjectPool = () => {
"registeredComponentPropsMetas",
$registeredComponentPropsMetas
),
+ new NanostoresSyncObject("registeredTemplates", $registeredTemplates),
new NanostoresSyncObject("canvasScrollbarWidth", $canvasScrollbarSize),
]);
};
diff --git a/packages/sdk-components-react-radix/src/templates.ts b/packages/sdk-components-react-radix/src/templates.ts
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/sdk-components-react-remix/src/templates.ts b/packages/sdk-components-react-remix/src/templates.ts
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/packages/sdk-components-react/package.json b/packages/sdk-components-react/package.json
index c1271c32c0..f226c477ab 100644
--- a/packages/sdk-components-react/package.json
+++ b/packages/sdk-components-react/package.json
@@ -32,6 +32,11 @@
"webstudio": "./src/hooks.ts",
"types": "./lib/types/hooks.d.ts",
"import": "./lib/hooks.js"
+ },
+ "./templates": {
+ "webstudio": "./src/templates.ts",
+ "types": "./lib/types/templates.d.ts",
+ "import": "./lib/templates.js"
}
},
"scripts": {
@@ -42,9 +47,15 @@
"typecheck": "tsc"
},
"peerDependencies": {
+ "@webstudio-is/template": "workspace:*",
"react": "18.3.0-canary-14898b6a9-20240318",
"react-dom": "18.3.0-canary-14898b6a9-20240318"
},
+ "peerDependenciesMeta": {
+ "@webstudio-is/template": {
+ "optional": true
+ }
+ },
"dependencies": {
"@react-aria/utils": "^3.25.3",
"@webstudio-is/icons": "workspace:*",
@@ -60,6 +71,7 @@
"@types/react": "^18.2.70",
"@types/react-dom": "^18.2.25",
"@webstudio-is/generate-arg-types": "workspace:*",
+ "@webstudio-is/template": "workspace:*",
"@webstudio-is/tsconfig": "workspace:*",
"react": "18.3.0-canary-14898b6a9-20240318",
"react-dom": "18.3.0-canary-14898b6a9-20240318",
diff --git a/packages/sdk-components-react/src/button.template.tsx b/packages/sdk-components-react/src/button.template.tsx
new file mode 100644
index 0000000000..c273c173aa
--- /dev/null
+++ b/packages/sdk-components-react/src/button.template.tsx
@@ -0,0 +1,11 @@
+import { type TemplateMeta, $, PlaceholderValue } from "@webstudio-is/template";
+
+export const meta: TemplateMeta = {
+ category: "forms",
+ order: 2,
+ description:
+ "Use a button to submit forms or trigger actions within a page. Do not use a button to navigate users to another resource or another page - that’s what a link is used for.",
+ template: (
+ <$.Button>{new PlaceholderValue("Button text you can edit")}</$.Button>
+ ),
+};
diff --git a/packages/sdk-components-react/src/button.ws.ts b/packages/sdk-components-react/src/button.ws.ts
index abb537ca30..84a2eacc66 100644
--- a/packages/sdk-components-react/src/button.ws.ts
+++ b/packages/sdk-components-react/src/button.ws.ts
@@ -14,35 +14,18 @@ const presetStyle = {
} satisfies PresetStyle<typeof defaultTag>;
export const meta: WsComponentMeta = {
- category: "forms",
+ icon: ButtonElementIcon,
type: "container",
constraints: {
relation: "ancestor",
component: { $nin: ["Button", "Link"] },
},
- description:
- "Use a button to submit forms or trigger actions within a page. Do not use a button to navigate users to another resource or another page - that’s what a link is used for.",
- icon: ButtonElementIcon,
presetStyle,
states: [
...defaultStates,
{ selector: ":disabled", label: "Disabled" },
{ selector: ":enabled", label: "Enabled" },
],
- order: 2,
- template: [
- {
- type: "instance",
- component: "Button",
- children: [
- {
- type: "text",
- value: "Button text you can edit",
- placeholder: true,
- },
- ],
- },
- ],
};
export const propsMeta: WsComponentPropsMeta = {
diff --git a/packages/sdk-components-react/src/list.template.tsx b/packages/sdk-components-react/src/list.template.tsx
new file mode 100644
index 0000000000..e9f24026fb
--- /dev/null
+++ b/packages/sdk-components-react/src/list.template.tsx
@@ -0,0 +1,20 @@
+import { type TemplateMeta, $, PlaceholderValue } from "@webstudio-is/template";
+
+export const meta: TemplateMeta = {
+ category: "typography",
+ description: "Groups content, like links in a menu or steps in a recipe.",
+ order: 4,
+ template: (
+ <$.List>
+ <$.ListItem>
+ {new PlaceholderValue("List Item text you can edit")}
+ </$.ListItem>
+ <$.ListItem>
+ {new PlaceholderValue("List Item text you can edit")}
+ </$.ListItem>
+ <$.ListItem>
+ {new PlaceholderValue("List Item text you can edit")}
+ </$.ListItem>
+ </$.List>
+ ),
+};
diff --git a/packages/sdk-components-react/src/list.ws.ts b/packages/sdk-components-react/src/list.ws.ts
index c600dfc440..e60bff2ad5 100644
--- a/packages/sdk-components-react/src/list.ws.ts
+++ b/packages/sdk-components-react/src/list.ws.ts
@@ -43,54 +43,10 @@ const presetStyle = {
} satisfies PresetStyle<ListTag>;
export const meta: WsComponentMeta = {
- category: "typography",
type: "container",
- description: "Groups content, like links in a menu or steps in a recipe.",
icon: ListIcon,
states: defaultStates,
presetStyle,
- order: 4,
- template: [
- {
- type: "instance",
- component: "List",
- children: [
- {
- type: "instance",
- component: "ListItem",
- children: [
- {
- type: "text",
- value: "List Item text you can edit",
- placeholder: true,
- },
- ],
- },
- {
- type: "instance",
- component: "ListItem",
- children: [
- {
- type: "text",
- value: "List Item text you can edit",
- placeholder: true,
- },
- ],
- },
- {
- type: "instance",
- component: "ListItem",
- children: [
- {
- type: "text",
- value: "List Item text you can edit",
- placeholder: true,
- },
- ],
- },
- ],
- },
- ],
};
export const propsMeta: WsComponentPropsMeta = {
diff --git a/packages/sdk-components-react/src/templates.ts b/packages/sdk-components-react/src/templates.ts
new file mode 100644
index 0000000000..e577449ff2
--- /dev/null
+++ b/packages/sdk-components-react/src/templates.ts
@@ -0,0 +1,2 @@
+export { meta as Button } from "./button.template";
+export { meta as List } from "./list.template";
diff --git a/packages/template/src/index.ts b/packages/template/src/index.ts
index 02c01f8332..df7c87c7e2 100644
--- a/packages/template/src/index.ts
+++ b/packages/template/src/index.ts
@@ -1 +1,2 @@
export * from "./jsx";
+export * from "./template";
diff --git a/packages/template/src/jsx.test.tsx b/packages/template/src/jsx.test.tsx
index 4936ec5708..e9cfb274d8 100644
--- a/packages/template/src/jsx.test.tsx
+++ b/packages/template/src/jsx.test.tsx
@@ -5,6 +5,7 @@ import {
ExpressionValue,
PageValue,
ParameterValue,
+ PlaceholderValue,
renderTemplate,
} from "./jsx";
@@ -196,3 +197,19 @@ test("render defined props", () => {
},
]);
});
+
+test("render placeholder value", () => {
+ const { instances } = renderTemplate(
+ <$.Body>{new PlaceholderValue("Placeholder text")}</$.Body>
+ );
+ expect(instances).toEqual([
+ {
+ type: "instance",
+ id: "0",
+ component: "Body",
+ children: [
+ { type: "text", value: "Placeholder text", placeholder: true },
+ ],
+ },
+ ]);
+});
diff --git a/packages/template/src/jsx.ts b/packages/template/src/jsx.ts
index 076f9164bd..a41a794581 100644
--- a/packages/template/src/jsx.ts
+++ b/packages/template/src/jsx.ts
@@ -1,5 +1,11 @@
import { Fragment, type JSX, type ReactNode } from "react";
-import type { Instance, Instances, Prop, Props } from "@webstudio-is/sdk";
+import type {
+ Instance,
+ Instances,
+ Prop,
+ Props,
+ WebstudioFragment,
+} from "@webstudio-is/sdk";
export class ExpressionValue {
value: string;
@@ -47,6 +53,13 @@ export class PageValue {
}
}
+export class PlaceholderValue {
+ value: string;
+ constructor(text: string) {
+ this.value = text;
+ }
+}
+
const traverseJsx = (
element: JSX.Element,
callback: (
@@ -65,6 +78,9 @@ const traverseJsx = (
if (typeof child === "string") {
continue;
}
+ if (child instanceof PlaceholderValue) {
+ continue;
+ }
if (child instanceof ExpressionValue) {
continue;
}
@@ -78,6 +94,9 @@ const traverseJsx = (
if (typeof child === "string") {
continue;
}
+ if (child instanceof PlaceholderValue) {
+ continue;
+ }
if (child instanceof ExpressionValue) {
continue;
}
@@ -86,13 +105,7 @@ const traverseJsx = (
return result;
};
-type WebstudioTemplate = {
- children: Instance["children"];
- instances: Instance[];
- props: Prop[];
-};
-
-export const renderTemplate = (root: JSX.Element): WebstudioTemplate => {
+export const renderTemplate = (root: JSX.Element): WebstudioFragment => {
let lastId = -1;
const instances: Instance[] = [];
const props: Prop[] = [];
@@ -160,12 +173,14 @@ export const renderTemplate = (root: JSX.Element): WebstudioTemplate => {
...(element.props?.["ws:label"]
? { label: element.props?.["ws:label"] }
: undefined),
- children: children.map((child) =>
+ children: children.map((child): Instance["children"][number] =>
typeof child === "string"
? { type: "text", value: child }
- : child instanceof ExpressionValue
- ? { type: "expression", value: child.value }
- : { type: "id", value: child.props?.["ws:id"] ?? getId(child) }
+ : child instanceof PlaceholderValue
+ ? { type: "text", value: child.value, placeholder: true }
+ : child instanceof ExpressionValue
+ ? { type: "expression", value: child.value }
+ : { type: "id", value: child.props?.["ws:id"] ?? getId(child) }
),
};
instances.push(instance);
@@ -175,6 +190,13 @@ export const renderTemplate = (root: JSX.Element): WebstudioTemplate => {
children,
instances,
props,
+ assets: [],
+ dataSources: [],
+ resources: [],
+ breakpoints: [],
+ styleSourceSelections: [],
+ styleSources: [],
+ styles: [],
};
};
diff --git a/packages/template/src/template.ts b/packages/template/src/template.ts
new file mode 100644
index 0000000000..c737162840
--- /dev/null
+++ b/packages/template/src/template.ts
@@ -0,0 +1,27 @@
+import type { JSX } from "react";
+import type { WebstudioFragment } from "@webstudio-is/sdk";
+
+export const templateCategories = [
+ "general",
+ "typography",
+ "data",
+ "media",
+ "forms",
+ "radix",
+ "xml",
+ "hidden",
+ "internal",
+] as const;
+
+export type TemplateMeta = {
+ category: (typeof templateCategories)[number];
+ label?: string;
+ description?: string;
+ icon?: string;
+ order?: number;
+ template: JSX.Element;
+};
+
+export type GeneratedTemplateMeta = Omit<TemplateMeta, "template"> & {
+ template: WebstudioFragment;
+};
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 0b1dfa570b..078ff5dc86 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1860,6 +1860,9 @@ importers:
'@webstudio-is/generate-arg-types':
specifier: workspace:*
version: link:../generate-arg-types
+ '@webstudio-is/template':
+ specifier: workspace:*
+ version: link:../template
'@webstudio-is/tsconfig':
specifier: workspace:*
version: link:../tsconfig
diff --git a/vite.sdk-components.config.ts b/vite.sdk-components.config.ts
index f38ffaa97a..6d1436f976 100644
--- a/vite.sdk-components.config.ts
+++ b/vite.sdk-components.config.ts
@@ -15,6 +15,7 @@ export default defineConfig({
"src/metas.ts",
"src/props.ts",
"src/hooks.ts",
+ "src/templates.ts",
],
formats: ["es"],
},