velloo 0.0.0 → 0.2.0

package/pkgs/provider-antd/src/overlays.ts

@@ -0,0 +1,176 @@
+import type { MenuProps } from "antd";
+import { Card as AntCard, Menu as AntMenu } from "antd";
+import {
+  type CSSProperties,
+  createElement,
+  Fragment,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+/**
+ * Canvas-safe antd overlays. antd's Modal/Drawer/Popover/Tooltip/Dropdown
+ * portal to `document.body` and, in SSR, render nothing at all (rc-util's
+ * Portal is client-only — verified: `open` overlays SSR to an empty string).
+ * In design mode we want them rendered **open + inline** (in normal flow, no
+ * escaping portal, no fixed backdrop) so a screenshot shows their surface.
+ * These shims render the overlay's *content* on an inline antd Card surface;
+ * the open/anchor/transition machinery is dropped. Trigger-wrapping overlays
+ * (Popover/Tooltip/Dropdown) render their child trigger inline, followed by
+ * the pinned-open surface.
+ *
+ * Mirrors the MUI adapter's `overlays.ts` and the shadcn snapshot's
+ * pinned-open overlay stance.
+ */
+
+type Props = Record<string, unknown> & { children?: ReactNode };
+
+/** Pass-through props every node carries — className for styling, data-node-path for canvas selection. */
+function chrome(props: Props): { className?: string; "data-node-path"?: string } {
+  // Only the keys that are actually present: the return type says these may be
+  // *absent*, and under `exactOptionalPropertyTypes` an explicit `undefined` is
+  // a different thing from an omitted key.
+  const className = typeof props.className === "string" ? props.className : undefined;
+  const nodePath = props["data-node-path"];
+  return {
+    ...(className !== undefined ? { className } : {}),
+    ...(typeof nodePath === "string" ? { "data-node-path": nodePath } : {}),
+  };
+}
+
+/** Merge the node's authored `style` (this provider's style channel) over the shim's base. */
+function mergeStyle(baseStyle: CSSProperties, style: unknown): CSSProperties {
+  return style && typeof style === "object" && !Array.isArray(style)
+    ? { ...baseStyle, ...(style as CSSProperties) }
+    : baseStyle;
+}
+
+const SURFACE_SHADOW = "0 6px 16px rgba(0, 0, 0, 0.08), 0 3px 6px -4px rgba(0, 0, 0, 0.12)";
+
+/** The modal surface, rendered inline (open, no portal/backdrop). `footer` renders as a right-aligned row. */
+export function Modal(props: Props): ReactElement {
+  const width = typeof props.width === "number" ? props.width : 520;
+  const footer = props.footer as ReactNode | undefined;
+  return createElement(
+    AntCard,
+    {
+      ...chrome(props),
+      title: props.title as ReactNode,
+      style: mergeStyle(
+        { width: "100%", maxWidth: width, margin: "16px auto", boxShadow: SURFACE_SHADOW },
+        props.style,
+      ),
+    },
+    props.children,
+    footer
+      ? createElement(
+          "div",
+          { style: { display: "flex", justifyContent: "flex-end", gap: 8, marginTop: 16 } },
+          footer,
+        )
+      : null,
+  );
+}
+
+/** A side-drawer panel, rendered inline as a fixed-width column. */
+export function Drawer(props: Props): ReactElement {
+  return createElement(
+    AntCard,
+    {
+      ...chrome(props),
+      title: props.title as ReactNode,
+      style: mergeStyle(
+        { width: 320, height: "100%", borderRadius: 0, boxShadow: SURFACE_SHADOW },
+        props.style,
+      ),
+    },
+    props.children,
+  );
+}
+
+/** The trigger child inline, followed by the popover surface (title + content), pinned open. */
+export function Popover(props: Props): ReactElement {
+  return createElement(
+    Fragment,
+    null,
+    props.children,
+    createElement(
+      AntCard,
+      {
+        ...chrome(props),
+        size: "small",
+        title: props.title as ReactNode,
+        style: mergeStyle(
+          { display: "inline-block", maxWidth: 320, marginTop: 8, boxShadow: SURFACE_SHADOW },
+          props.style,
+        ),
+      },
+      props.content as ReactNode,
+    ),
+  );
+}
+
+/** The trigger child inline; `title` renders beside it as a dark tooltip pill. */
+export function Tooltip(props: Props): ReactElement {
+  const tip = props.title as ReactNode | undefined;
+  return createElement(
+    Fragment,
+    null,
+    props.children,
+    tip == null
+      ? null
+      : createElement(
+          "span",
+          {
+            ...chrome(props),
+            style: mergeStyle(
+              {
+                display: "inline-block",
+                background: "rgba(0, 0, 0, 0.85)",
+                color: "#fff",
+                borderRadius: 6,
+                padding: "4px 8px",
+                fontSize: 12,
+                lineHeight: 1.4,
+                marginLeft: 8,
+                verticalAlign: "middle",
+              },
+              props.style,
+            ),
+          },
+          tip,
+        ),
+  );
+}
+
+/** The trigger child inline, followed by the dropdown's menu surface (from `menu.items`), pinned open. */
+export function Dropdown(props: Props): ReactElement {
+  const menu = props.menu as { items?: MenuProps["items"] } | undefined;
+  return createElement(
+    Fragment,
+    null,
+    props.children,
+    createElement(
+      "div",
+      {
+        ...chrome(props),
+        style: mergeStyle(
+          {
+            display: "inline-block",
+            minWidth: 160,
+            marginTop: 4,
+            borderRadius: 8,
+            boxShadow: SURFACE_SHADOW,
+            overflow: "hidden",
+          },
+          props.style,
+        ),
+      },
+      createElement(AntMenu, {
+        items: menu?.items ?? [],
+        selectable: false,
+        style: { borderInlineEnd: "none" },
+      }),
+    ),
+  );
+}

package/pkgs/provider-antd/src/registry.ts

@@ -0,0 +1,104 @@
+import { helpersRegistry } from "@velloo/helpers";
+import type { ComponentRegistry } from "@velloo/provider";
+import {
+  Alert,
+  Avatar,
+  Badge,
+  Breadcrumb,
+  Button,
+  Card,
+  Checkbox,
+  Col,
+  Divider,
+  Empty,
+  Flex,
+  Input,
+  List,
+  Menu,
+  Pagination,
+  Progress,
+  Radio,
+  Rate,
+  Row,
+  Segmented,
+  Select,
+  Skeleton,
+  Slider,
+  Space,
+  Statistic,
+  Steps,
+  Switch,
+  Table,
+  Tabs,
+  Tag,
+  Typography,
+} from "antd";
+import { Drawer, Dropdown, Modal, Popover, Tooltip } from "./overlays.ts";
+
+const REUSED_HELPER_IDS = [
+  "Icon",
+  "Image",
+  "Placeholder",
+  "SVG",
+  "Layer",
+  "Gradient",
+  "Prose",
+] as const;
+
+/**
+ * The runtime registry for antd-native folders: design `$ref` ids → real antd
+ * components, SSR'd in-process via the adapter's cssinjs render pass. Dotted
+ * antd subcomponents get manifest-friendly flat ids (`Typography.Title` ⇒
+ * `TypographyTitle`, `List.Item` ⇒ `ListItem`) — the MCP intro tells the agent
+ * how those destructure in emitted code. The overlay surface
+ * (Modal/Drawer/Popover/Tooltip/Dropdown) is canvas-safe-wrapped in
+ * `overlays.ts` — antd's own overlays portal and render NOTHING in SSR, so the
+ * shims render them open + inline instead.
+ */
+export const registry: ComponentRegistry = {
+  Alert,
+  Avatar,
+  Badge,
+  Breadcrumb,
+  Button,
+  Card,
+  Checkbox,
+  Col,
+  Divider,
+  Drawer,
+  Dropdown,
+  Empty,
+  Flex,
+  Input,
+  List,
+  ListItem: List.Item,
+  ListItemMeta: List.Item.Meta,
+  Menu,
+  Modal,
+  Pagination,
+  Popover,
+  Progress,
+  Radio,
+  Rate,
+  Row,
+  Segmented,
+  Select,
+  Skeleton,
+  Slider,
+  Space,
+  Statistic,
+  Steps,
+  Switch,
+  Table,
+  Tabs,
+  Tag,
+  Tooltip,
+  TypographyParagraph: Typography.Paragraph,
+  TypographyText: Typography.Text,
+  TypographyTitle: Typography.Title,
+  // Framework-neutral velloo helpers antd has no equivalent for — chiefly
+  // `Icon` (lucide; @ant-design/icons isn't surfaced) + imagery/composition
+  // helpers. Reused verbatim from `@velloo/helpers`, like provider-mui. They
+  // size via props (`Icon size`), not Tailwind — the JIT is off on an antd folder.
+  ...helpersRegistry(REUSED_HELPER_IDS),
+};

package/pkgs/provider-antd/src/render-pass.ts

@@ -0,0 +1,43 @@
+import { createCache, extractStyle, StyleProvider } from "@ant-design/cssinjs";
+import type { RenderPass } from "@velloo/provider";
+import type { Theme as VellooTheme } from "@velloo/schema";
+import { ConfigProvider } from "antd";
+import { createElement } from "react";
+import { antdThemeConfig } from "./theme.ts";
+
+/**
+ * A fresh cssinjs + antd render pass for one SSR. `wrap` nests the tree under
+ * a per-render cssinjs StyleProvider + an antd ConfigProvider carrying the
+ * projected velloo tokens (with `cssVar: true`, so `--ant-*` variables reach
+ * inline styles); `css()` extracts the style rules the render registered in
+ * the cache. The renderer injects that CSS into a `data-velloo-adapter`
+ * <style>. Unlike emotion, cssinjs extraction reads the cache directly — the
+ * rendered HTML isn't needed.
+ *
+ * SSR works in-process because antd is a velloo dependency, so it links the
+ * shared monorepo React — no dual-React hazard.
+ */
+export function makeRenderPass(theme: VellooTheme, dark = false): RenderPass {
+  const cache = createCache();
+  const config = antdThemeConfig(theme, dark);
+  return {
+    wrap: (element) =>
+      createElement(
+        StyleProvider,
+        { cache },
+        createElement(ConfigProvider, { theme: config }, element),
+      ),
+    // `plain: true` returns bare CSS text; strip <style> wrappers defensively
+    // anyway — the RenderPass contract returns CSS, not markup.
+    css: () => stripStyleTags(extractStyle(cache, { plain: true })),
+  };
+}
+
+function stripStyleTags(css: string): string {
+  let current = css;
+  for (;;) {
+    const next = current.replace(/<\/?style[^>]*>/gi, "");
+    if (next === current) return next;
+    current = next;
+  }
+}

package/pkgs/provider-antd/src/tailwind-entry.css

@@ -0,0 +1,21 @@
+/*
+ * antd styles components via cssinjs (the ConfigProvider theme + inline
+ * `style` objects), not Tailwind utility classes — so this entry mostly exists
+ * to satisfy the JIT contract. It still imports Tailwind + declares the token
+ * @theme so any stray utility class resolves, and the canvas base reads themed.
+ */
+@import "tailwindcss";
+
+@theme {
+  --color-background: oklch(1 0 0);
+  --color-foreground: oklch(0.145 0 0);
+  --color-primary: oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+  --font-sans: system-ui, -apple-system, sans-serif;
+}
+
+html, body {
+  background: var(--color-background);
+  color: var(--color-foreground);
+  font-family: var(--font-sans);
+}

package/pkgs/provider-antd/src/theme.ts

@@ -0,0 +1,132 @@
+import { identifierRef } from "@velloo/provider";
+import {
+  type ColorPair,
+  DEFAULT_TYPESET_NAME,
+  resolveColors,
+  typesetScale,
+  type Theme as VellooTheme,
+} from "@velloo/schema";
+import type { ThemeConfig } from "antd";
+import { theme as antdTheme } from "antd";
+import { formatRgb, parse } from "culori";
+
+/**
+ * antd's token engine derives its palette ramps with @ant-design/fast-color,
+ * which parses `#hex`, `rgb()/rgba()`, `hsl()/hsla()` — NOT `oklch()`, which is
+ * exactly what velloo themes store. Convert anything outside that set to
+ * `rgb(...)` via culori; pass antd-native formats through untouched so a hex
+ * theme stays hex (and round-trips identically in codegen).
+ */
+function antdColor(css: string): string {
+  const s = css.trim();
+  if (/^(#|rgb|hsl)/i.test(s)) return s;
+  return formatRgb(parse(s)) ?? s;
+}
+
+/** A color slot is a CSS string or a { DEFAULT, foreground } pair — pull the base color (antd-safe). */
+function base(slot: ColorPair | undefined, fallback: string): string {
+  if (typeof slot === "string") return antdColor(slot);
+  if (slot && typeof slot === "object" && typeof slot.DEFAULT === "string")
+    return antdColor(slot.DEFAULT);
+  return antdColor(fallback);
+}
+
+/** antd's `borderRadius` token is a px number; coerce velloo's radius.md (number or CSS len). */
+function radiusPx(theme: VellooTheme): number {
+  const md = (theme.radius as Record<string, unknown> | undefined)?.md;
+  if (typeof md === "number") return md;
+  if (typeof md === "string") {
+    const n = Number.parseFloat(md);
+    return Number.isFinite(n) ? (md.includes("rem") ? n * 16 : n) : 8;
+  }
+  return 8;
+}
+
+/**
+ * Project velloo's unified token tree onto antd's seed tokens — the SINGLE
+ * source of the velloo→antd mapping shared by the runtime render pass and
+ * codegen, so the preview and the emitted theme never diverge. In dark mode,
+ * overlay the theme's dark color slots — otherwise the dark algorithm would
+ * derive from the light color values.
+ */
+function antdTokens(theme: VellooTheme, dark: boolean): NonNullable<ThemeConfig["token"]> {
+  const c = resolveColors(theme, dark);
+  return {
+    colorPrimary: base(c.primary, "#4f46e5"),
+    colorBgBase: antdColor(c.background),
+    colorTextBase: antdColor(c.foreground),
+    colorError: base(c.destructive, "#dc2626"),
+    borderRadius: radiusPx(theme),
+    ...antdTypography(theme),
+    ...(c.card ? { colorBgContainer: base(c.card, c.background) } : {}),
+  };
+}
+
+/**
+ * Project the default typeset onto antd's typography seed tokens.
+ *
+ * antd derives its whole type scale from `fontSize` plus the five
+ * `fontSizeHeading*` tokens, which is close enough to velloo's ladder to map
+ * directly. Values come from `typesetScale` — the concrete-value form of the
+ * same ratio table `typesetCss` uses symbolically — because a seed token ends
+ * up in a serialized `ThemeConfig` where no CSS variables exist.
+ *
+ * antd has only five heading tokens (h1–h5), so the velloo `h6` rung has no
+ * antd equivalent and is intentionally dropped here; `Prose` regions still get
+ * it from the typeset CSS.
+ */
+function antdTypography(theme: VellooTheme): NonNullable<ThemeConfig["token"]> {
+  const typography = theme.typography;
+  const scale = typesetScale(typography.typesets?.[DEFAULT_TYPESET_NAME], {
+    ...(typography.fontFamily ? { fontFamily: typography.fontFamily } : {}),
+  });
+  return {
+    fontFamily:
+      scale.body.fontFamily ??
+      typography.fontFamily?.sans ??
+      "system-ui, -apple-system, sans-serif",
+    fontSize: scale.body.fontSize,
+    fontSizeSM: scale.caption.fontSize,
+    fontSizeLG: scale.lead.fontSize,
+    fontSizeHeading1: scale.h1.fontSize,
+    fontSizeHeading2: scale.h2.fontSize,
+    fontSizeHeading3: scale.h3.fontSize,
+    fontSizeHeading4: scale.h4.fontSize,
+    fontSizeHeading5: scale.h5.fontSize,
+    lineHeight: scale.body.lineHeight,
+    lineHeightHeading1: scale.h1.lineHeight,
+    lineHeightHeading2: scale.h2.lineHeight,
+    lineHeightHeading3: scale.h3.lineHeight,
+    lineHeightHeading4: scale.h4.lineHeight,
+    lineHeightHeading5: scale.h5.lineHeight,
+  };
+}
+
+/**
+ * The runtime `ThemeConfig` for the render pass — carries the REAL algorithm
+ * function (antd derives its map tokens by calling it). `cssVar: true` also
+ * publishes every token as an `--ant-*` CSS variable, so inline `style`
+ * objects (this provider's style channel) can reference theme values.
+ */
+export function antdThemeConfig(theme: VellooTheme, dark = false): ThemeConfig {
+  return {
+    cssVar: true,
+    algorithm: dark ? antdTheme.darkAlgorithm : antdTheme.defaultAlgorithm,
+    token: antdTokens(theme, dark),
+  };
+}
+
+/**
+ * The codegen projection (`themeToNative`): the same token mapping, but the
+ * algorithm emits as a bare identifier (`antdTheme.darkAlgorithm`) that the
+ * theme module's import line brings into scope — a function can't serialize.
+ * The light flavor references `defaultAlgorithm` explicitly (identical to
+ * antd's default) so the aliased import is always used in the emitted module.
+ */
+export function antdThemeOptions(theme: VellooTheme, dark = false): unknown {
+  return {
+    cssVar: true,
+    algorithm: identifierRef(dark ? "antdTheme.darkAlgorithm" : "antdTheme.defaultAlgorithm"),
+    token: antdTokens(theme, dark),
+  };
+}

package/pkgs/provider-antd/src/version.ts

@@ -0,0 +1,8 @@
+/**
+ * Lives in its own module (exported as `@velloo/provider-antd/version`) so
+ * version-only consumers — the CLI init wizard — don't pull the provider's
+ * registry (and with it all of antd) into their import graph. The bundled
+ * CLI lazy-loads the full provider per folder config; see
+ * `packages/server/src/providers.ts`.
+ */
+export const ANTD_VERSION = "5" as const;

package/pkgs/provider-chakra/src/index.ts

@@ -0,0 +1,80 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  catalogFromManifest,
+  type FrameworkAdapter,
+  type Manifest,
+  SX_PROP,
+} from "@velloo/provider";
+import { resolveProviderSrcDir } from "@velloo/provider/src-dir";
+import { CHAKRA_INTRO } from "./intro.ts";
+import { CHAKRA_MANIFEST } from "./manifest.ts";
+import { registry } from "./registry.ts";
+import { makeRenderPass } from "./render-pass.ts";
+import { chakraThemeOptions } from "./theme.ts";
+
+/**
+ * Chakra UI v2 provider — a first-class FrameworkAdapter. Chakra ships as a
+ * velloo dependency (pre-bundled), so its components SSR in-process against
+ * the shared monorepo React; the adapter's emotion `renderPass` extracts the
+ * critical CSS (chakra rides the same emotion machinery as MUI). Styling is
+ * the native `sx` prop, and the theme projects velloo tokens onto an
+ * `extendTheme` POJO (brand scale, semantic body colors, radii, fonts).
+ * Canvas-safe overlays (Modal/Drawer/Popover/Menu/Tooltip compositions),
+ * `"@chakra-ui/react"` codegen, an `extendTheme` theme emit,
+ * `velloo init --library=chakra`, and the catalog are all wired.
+ */
+
+export { CHAKRA_VERSION } from "./version.ts";
+
+import { CHAKRA_VERSION } from "./version.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Resolve the provider src (Tailwind entry + sources), from dev + the bundled CLI. */
+const srcDir = resolveProviderSrcDir(here, "provider-chakra", process.env.VELLOO_CHAKRA_SRC);
+
+export function createProvider(): FrameworkAdapter {
+  return {
+    id: "chakra",
+    version: CHAKRA_VERSION,
+    label: "Chakra UI v2",
+    componentsDir: srcDir,
+    styleEntryPath: join(srcDir, "tailwind-entry.css"),
+    registry,
+    loadManifest: async (): Promise<Manifest> => CHAKRA_MANIFEST,
+    // The catalog is the chakra *library* surface — every curated chakra
+    // component, all installed (bundled). The reused velloo helpers (source
+    // "velloo", e.g. Icon→lucide) are always-available built-ins, not library
+    // components to install, so they're excluded.
+    catalog: async () =>
+      catalogFromManifest(
+        CHAKRA_MANIFEST.filter((c) => c.source === "chakra"),
+        { importPath: "@chakra-ui/react" },
+      ),
+    styleChannel: SX_PROP,
+    styleChannels: ["sx"],
+    mcpIntro: () => [...CHAKRA_INTRO],
+    renderPass: (theme, dark) => makeRenderPass(theme, dark ?? false),
+    codegenModule: "@chakra-ui/react",
+    themeToNative: (theme, dark) => chakraThemeOptions(theme, dark),
+    themeModule: {
+      importLines: ['import { extendTheme } from "@chakra-ui/react";'],
+      factory: "extendTheme",
+      defaultPath: "chakra-theme.ts",
+    },
+    // canvasBundleSpec is deliberately absent in v1: the server's bundle-entry
+    // builder implements only the MUI-shaped emotion style runtime (its entry
+    // template expects `ThemeProvider` + `createTheme` from `stylesModule`);
+    // chakra needs `ChakraProvider` + `extendTheme`, so chakra folders render
+    // via the in-process emotion SSR path. Extending it means teaching the
+    // emotion `CanvasStyleRuntime` a provider/factory shape (or a new union
+    // member) in packages/provider/src/adapter.ts plus a branch in
+    // packages/server/src/live/canvas-bundle.ts.
+  };
+}
+
+/** The id used in `Library.id` to select this provider. */
+export const CHAKRA_PROVIDER_ID = "chakra" as const;
+
+export { brandScale, chakraThemeOptions } from "./theme.ts";

package/pkgs/provider-chakra/src/intro.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP instruction framing for a chakra folder (`FrameworkAdapter.mcpIntro`).
+ *
+ * The server's base brief is framework-neutral, so this states the vocabulary
+ * and the style channel positively rather than correcting a shadcn claim.
+ */
+export const CHAKRA_INTRO: readonly string[] = [
+  "**This folder targets Chakra UI v2.** Components are real Chakra: `Box`/`Flex`/`Stack`/`HStack`/`VStack`/`Grid`+`GridItem`/`Container`/`Spacer` for layout, `Card`+`CardHeader`/`CardBody`/`CardFooter`, `Heading`/`Text` (ALL text — `size` picks the heading scale), `Button`/`IconButton`, `Input`/`Textarea`/`Select`/`Checkbox`/`Radio`/`Switch`/`Slider`+parts, `Badge`/`Tag`/`Avatar`/`Alert`+parts/`Stat`+parts/`Progress`/`Skeleton`, `TableContainer`+`Table`/`Thead`/`Tbody`/`Tr`/`Th`/`Td`, `Tabs`+parts, `List`/`ListItem`, `Breadcrumb`+parts, and the overlay surface `Modal`/`Drawer`/`Popover`/`Menu`/`Tooltip` (chakra's composition parts are registered and render open + inline in design mode). Call `list_components` for the full set and per-component `example` props.",
+  "",
+  '**Style through `sx`.** `update_props { style: { display: "flex", alignItems: "center", gap: 4, p: 6, color: "brand.600" } }` — an object (merges shallowly; an inner `null` drops a key, `style: null` clears). `sx` keys are Chakra style props; spacing is the chakra scale (`p: 4` = 16px); color values take theme tokens — `"brand.500"` is the theme\'s primary scale, `"chakra-body-bg"`/`"chakra-subtle-text"` are the semantic surfaces, and `"gray.600"` etc. work too. Prefer component props (`colorScheme`, `variant`, `size`, `spacing`) over sx where they exist — `colorScheme="brand"` is the primary-colored variant.',
+  "",
+  '`emit_code` emits idiomatic `<Component sx={{…}} />` importing from `"@chakra-ui/react"`; `emit_theme` emits an `extendTheme(...)` module (default `chakra-theme.ts`) — wire it with `<ChakraProvider theme={theme}>`. Overlays are design-mode shims rendered pinned open: the emitted composition (`Modal > ModalContent > …`) is real chakra, but add the `isOpen`/`onClose` disclosure wiring when implementing. Tailwind utility diagnostics do not apply here.',
+  "",
+];