velloo 0.0.0 → 0.2.0

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

@@ -0,0 +1,227 @@
+import {
+  Alert,
+  AlertDescription,
+  AlertIcon,
+  AlertTitle,
+  Avatar,
+  Badge,
+  Box,
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  Button,
+  Card,
+  CardBody,
+  CardFooter,
+  CardHeader,
+  Checkbox,
+  Container,
+  chakra,
+  Divider,
+  Flex,
+  Grid,
+  GridItem,
+  Heading,
+  HStack,
+  IconButton,
+  Input,
+  List,
+  ListItem,
+  Progress,
+  Radio,
+  Select,
+  Skeleton,
+  Slider,
+  SliderFilledTrack,
+  SliderThumb,
+  SliderTrack,
+  Spacer,
+  Stack,
+  Stat,
+  StatArrow,
+  StatHelpText,
+  StatLabel,
+  StatNumber,
+  Switch,
+  Tab,
+  TabList,
+  Table,
+  TableContainer,
+  TabPanel,
+  TabPanels,
+  Tabs,
+  Tag,
+  Tbody,
+  Td,
+  Text,
+  Textarea,
+  Th,
+  Thead,
+  Tr,
+  VStack,
+} from "@chakra-ui/react";
+import {
+  Gradient as VellooGradient,
+  Icon as VellooIcon,
+  Image as VellooImage,
+  Layer as VellooLayer,
+  Placeholder as VellooPlaceholder,
+  Prose as VellooProse,
+  SVG as VellooSVG,
+} from "@velloo/helpers";
+import type { ComponentRegistry } from "@velloo/provider";
+import {
+  Drawer,
+  DrawerBody,
+  DrawerContent,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerOverlay,
+  Menu,
+  MenuButton,
+  MenuDivider,
+  MenuItem,
+  MenuList,
+  Modal,
+  ModalBody,
+  ModalCloseButton,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+  ModalOverlay,
+  Popover,
+  PopoverArrow,
+  PopoverBody,
+  PopoverContent,
+  PopoverHeader,
+  PopoverTrigger,
+  Tooltip,
+} from "./overlays.ts";
+
+// `chakra()` makes sx resolve through the same theme/runtime as native Chakra
+// primitives while preserving each helper's Velloo-specific behavior.
+const helperRegistry: ComponentRegistry = {
+  Icon: chakra(VellooIcon),
+  Image: chakra(VellooImage, {
+    // Velloo's fill-mode Image owns a wrapper. Keep layout styles (including
+    // width/height) on that root, and let ordinary Chakra `objectFit` /
+    // `objectPosition` values flow through to the actual child image.
+    baseStyle: {
+      objectFit: "cover",
+      objectPosition: "50% 50%",
+      "& > img": { objectFit: "inherit", objectPosition: "inherit" },
+    },
+  }),
+  Placeholder: chakra(VellooPlaceholder),
+  SVG: chakra(VellooSVG),
+  Layer: chakra(VellooLayer),
+  Gradient: chakra(VellooGradient),
+  Prose: chakra(VellooProse),
+};
+
+/**
+ * The runtime registry for chakra-native folders: design `$ref` ids → real
+ * Chakra v2 components, SSR'd in-process via the adapter's emotion render
+ * pass. The overlay surface (Modal/Drawer/Popover/Menu/Tooltip and their
+ * composition parts) is canvas-safe-wrapped in `overlays.ts` — chakra's own
+ * overlays portal and render NOTHING in SSR, and their sub-parts throw
+ * outside the real parent's context, so the shims render the whole
+ * composition open + inline. Chakra's own `Icon`/`Image` are deliberately not
+ * registered — those ids belong to the framework-neutral velloo helpers
+ * (Icon → lucide), like on the MUI/antd folders.
+ */
+export const registry: ComponentRegistry = {
+  // layout
+  Box,
+  Container,
+  Flex,
+  Grid,
+  GridItem,
+  HStack,
+  Spacer,
+  Stack,
+  VStack,
+  // surfaces + data display
+  Alert,
+  AlertDescription,
+  AlertIcon,
+  AlertTitle,
+  Avatar,
+  Badge,
+  Card,
+  CardBody,
+  CardFooter,
+  CardHeader,
+  Divider,
+  Progress,
+  Skeleton,
+  Stat,
+  StatArrow,
+  StatHelpText,
+  StatLabel,
+  StatNumber,
+  Tag,
+  // typography
+  Heading,
+  Text,
+  // controls
+  Button,
+  Checkbox,
+  IconButton,
+  Input,
+  Radio,
+  Select,
+  Slider,
+  SliderFilledTrack,
+  SliderThumb,
+  SliderTrack,
+  Switch,
+  Textarea,
+  // data
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  List,
+  ListItem,
+  Tab,
+  Table,
+  TableContainer,
+  TabList,
+  TabPanel,
+  TabPanels,
+  Tabs,
+  Tbody,
+  Td,
+  Th,
+  Thead,
+  Tr,
+  // overlays (canvas-safe shims)
+  Drawer,
+  DrawerBody,
+  DrawerContent,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerOverlay,
+  Menu,
+  MenuButton,
+  MenuDivider,
+  MenuItem,
+  MenuList,
+  Modal,
+  ModalBody,
+  ModalCloseButton,
+  ModalContent,
+  ModalFooter,
+  ModalHeader,
+  ModalOverlay,
+  Popover,
+  PopoverArrow,
+  PopoverBody,
+  PopoverContent,
+  PopoverHeader,
+  PopoverTrigger,
+  Tooltip,
+  // Framework-neutral behavior, wrapped so Chakra's sx channel styles the
+  // helper root just like it styles Box/Button/Card.
+  ...helperRegistry,
+};

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

@@ -0,0 +1,55 @@
+import { ChakraProvider, extendTheme } from "@chakra-ui/react";
+import createCache from "@emotion/cache";
+import { CacheProvider } from "@emotion/react";
+import createEmotionServer from "@emotion/server/create-instance";
+import type { RenderPass } from "@velloo/provider";
+import type { Theme as VellooTheme } from "@velloo/schema";
+import { createElement } from "react";
+import { chakraThemeOptions } from "./theme.ts";
+
+/**
+ * A fresh emotion + chakra render pass for one SSR. `wrap` nests the tree
+ * under a per-render emotion CacheProvider + a ChakraProvider carrying
+ * `extendTheme` over the projected velloo tokens; `css(html)` extracts the
+ * emotion rules the render registered — including chakra's Global styles
+ * (the `--chakra-*` CSS variables every component references), which
+ * `extractCriticalToChunks` keeps because globals are never in
+ * `cache.registered`. The renderer injects that CSS into a
+ * `data-velloo-adapter` <style>.
+ *
+ * SSR works in-process because @chakra-ui/react 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({ key: "vchakra", prepend: true });
+  const server = createEmotionServer(cache);
+  const chakraTheme = extendTheme(chakraThemeOptions(theme, dark));
+  return {
+    wrap: (element) =>
+      createElement(
+        CacheProvider,
+        { value: cache },
+        createElement(
+          ChakraProvider,
+          { theme: chakraTheme },
+          // The projected theme already carries real dark values at :root, but
+          // the data-theme/classname scope also switches chakra's own `_dark`
+          // component styling (whiteAlpha borders etc.) — ColorModeScript
+          // would set these on <html> in a real app; SSR has no client pass.
+          createElement(
+            "div",
+            {
+              "data-theme": dark ? "dark" : "light",
+              className: dark ? "chakra-ui-dark" : "chakra-ui-light",
+            },
+            element,
+          ),
+        ),
+      ),
+    css: (html) =>
+      server
+        .extractCriticalToChunks(html)
+        .styles.map((s) => s.css)
+        .join(""),
+  };
+}

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

@@ -0,0 +1,21 @@
+/*
+ * Chakra styles components via emotion (the extendTheme tokens + the `sx`
+ * prop), 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-chakra/src/theme.ts

@@ -0,0 +1,180 @@
+import {
+  type ColorPair,
+  DEFAULT_TYPESET_NAME,
+  resolveColors,
+  typesetScale,
+  type Theme as VellooTheme,
+} from "@velloo/schema";
+import { converter, formatHex, formatRgb, parse } from "culori";
+
+/**
+ * Chakra's color utilities (@ctrl/tinycolor inside @chakra-ui/theme-tools,
+ * behind the Alert/Tag/Badge subtle variants) parse `#hex`, `rgb()/rgba()`,
+ * `hsl()/hsla()` — NOT `oklch()`, which is exactly what velloo themes store.
+ * Convert anything outside that set to `rgb(...)` via culori; pass
+ * chakra-native formats through untouched so a hex theme stays hex (and
+ * round-trips identically in codegen).
+ */
+function chakraColor(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 (chakra-safe). */
+function base(slot: ColorPair | undefined, fallback: string): string {
+  if (typeof slot === "string") return chakraColor(slot);
+  if (slot && typeof slot === "object" && typeof slot.DEFAULT === "string")
+    return chakraColor(slot.DEFAULT);
+  return chakraColor(fallback);
+}
+
+const toOklch = converter("oklch");
+
+/**
+ * Derive a chakra 50–900 `brand` color scale from the theme's primary color.
+ * The primary lands verbatim at `brand.500` (what `colorScheme="brand"` solid
+ * buttons use in light mode); lighter steps walk a fixed OKLCH lightness ramp
+ * with chroma eased toward white, darker steps scale the base lightness down.
+ * Tuned for mid-lightness brand colors (the norm); a gray primary (chroma 0)
+ * degrades to a clean neutral ramp.
+ */
+export function brandScale(primary: string): Record<string, string> {
+  const safe = chakraColor(primary);
+  const okl = (() => {
+    const parsed = parse(primary);
+    return parsed ? toOklch(parsed) : undefined;
+  })();
+  if (!okl) {
+    // Unparsable color: a flat scale keeps every `brand.*` reference resolving.
+    return Object.fromEntries(
+      ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900"].map((k) => [k, safe]),
+    );
+  }
+  const { l = 0.55, c = 0, h } = okl;
+  const at = (lightness: number, chroma: number): string =>
+    formatHex({
+      mode: "oklch",
+      l: Math.min(Math.max(lightness, 0), 1),
+      c: Math.max(chroma, 0),
+      // An achromatic color has no hue — omit the key rather than passing
+      // undefined, which culori's Oklch type (rightly) does not accept.
+      ...(h === undefined ? {} : { h }),
+    });
+  return {
+    50: at(0.982, c * 0.12),
+    100: at(0.955, c * 0.25),
+    200: at(0.9, c * 0.45),
+    300: at(0.83, c * 0.65),
+    400: at(0.73, c * 0.85),
+    500: safe,
+    600: at(l * 0.88, c),
+    700: at(l * 0.74, c * 0.95),
+    800: at(l * 0.6, c * 0.85),
+    900: at(l * 0.47, c * 0.72),
+  };
+}
+
+/** Chakra radii are CSS lengths; coerce velloo's radius.md (number or CSS len). */
+function radiusCss(theme: VellooTheme): string {
+  const md = (theme.radius as Record<string, unknown> | undefined)?.md;
+  if (typeof md === "number") return `${md}px`;
+  if (typeof md === "string") return md;
+  return "8px";
+}
+
+/** The extendTheme input POJO `chakraThemeOptions` projects — typed so tests read fields directly. */
+export interface ChakraThemeOptions {
+  config: { initialColorMode: "light" | "dark"; useSystemColorMode: boolean };
+  colors: { brand: Record<string, string> };
+  semanticTokens: { colors: Record<string, string> };
+  fonts: { heading: string; body: string; mono?: string };
+  fontSizes: Record<string, string>;
+  lineHeights: Record<string, number>;
+  letterSpacings: Record<string, string>;
+  fontWeights: Record<string, number>;
+  radii: { md: string };
+}
+
+/**
+ * Project the default typeset onto chakra's typography scales.
+ *
+ * chakra's theme is a serialized POJO — it ends up in an `extendTheme(...)`
+ * artifact where no CSS variables exist — so this reads `typesetScale`, the
+ * concrete-value form of the same ratio table `typesetCss` uses symbolically.
+ * Keys are the velloo role names, so `fontSize="h1"` in a chakra folder resolves
+ * to the same size the canvas paints.
+ */
+function chakraTypography(
+  theme: VellooTheme,
+  fallbackSans: string,
+): Pick<
+  ChakraThemeOptions,
+  "fonts" | "fontSizes" | "lineHeights" | "letterSpacings" | "fontWeights"
+> {
+  const typography = theme.typography;
+  const scale = typesetScale(typography.typesets?.[DEFAULT_TYPESET_NAME], {
+    ...(typography.fontFamily ? { fontFamily: typography.fontFamily } : {}),
+  });
+  const fontSizes: Record<string, string> = {};
+  const lineHeights: Record<string, number> = {};
+  const letterSpacings: Record<string, string> = {};
+  const fontWeights: Record<string, number> = {};
+  for (const [role, resolved] of Object.entries(scale)) {
+    fontSizes[role] = `${resolved.fontSize}px`;
+    lineHeights[role] = resolved.lineHeight;
+    letterSpacings[role] = resolved.letterSpacing;
+    fontWeights[role] = resolved.fontWeight;
+  }
+  const mono = typography.fontFamily?.mono;
+  return {
+    fonts: {
+      // The heading face, which the typeset names explicitly. Before typesets
+      // this was the body font, so a folder with a display face never used it.
+      heading: scale.h1.fontFamily ?? fallbackSans,
+      body: scale.body.fontFamily ?? fallbackSans,
+      ...(mono ? { mono } : {}),
+    },
+    fontSizes,
+    lineHeights,
+    letterSpacings,
+    fontWeights,
+  };
+}
+
+/**
+ * Project velloo's unified token tree onto chakra `extendTheme` options — the
+ * SINGLE source of the velloo→chakra mapping shared by the runtime render pass
+ * and codegen, so the preview and the emitted theme never diverge.
+ *
+ * Dark is a dark-FLAVORED theme, not a mode flag: `colorsDark` overlays the
+ * color slots and the projected values land as plain strings on chakra's own
+ * semantic tokens (`chakra-body-bg` etc.), so they apply at `:root` — a static
+ * SSR shows real dark surfaces without the client-side `data-theme` attribute
+ * ColorModeScript would set. `initialColorMode` flips too so context-driven
+ * (`useColorModeValue`) styling agrees.
+ */
+export function chakraThemeOptions(theme: VellooTheme, dark = false): ChakraThemeOptions {
+  const c = resolveColors(theme, dark);
+  const fg = chakraColor(c.foreground);
+  const sans = theme.typography.fontFamily?.sans ?? "system-ui, -apple-system, sans-serif";
+  return {
+    config: { initialColorMode: dark ? "dark" : "light", useSystemColorMode: false },
+    colors: { brand: brandScale(base(c.primary, "#4f46e5")) },
+    semanticTokens: {
+      colors: {
+        "chakra-body-bg": chakraColor(c.background),
+        "chakra-body-text": fg,
+        ...(c.border ? { "chakra-border-color": chakraColor(c.border) } : {}),
+        ...(c.muted
+          ? {
+              "chakra-subtle-text": base(c.muted, fg),
+              "chakra-placeholder-color": base(c.muted, fg),
+            }
+          : {}),
+      },
+    },
+    ...chakraTypography(theme, sans),
+    radii: { md: radiusCss(theme) },
+  };
+}

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

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

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

@@ -0,0 +1,117 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { helperSourcePath } from "@velloo/helpers/paths";
+import {
+  type CanvasComponentSpec,
+  catalogFromManifest,
+  type FrameworkAdapter,
+  type Manifest,
+  SX_PROP,
+} from "@velloo/provider";
+import { resolveProviderSrcDir } from "@velloo/provider/src-dir";
+import { MUI_INTRO } from "./intro.ts";
+import { MUI_MANIFEST } from "./manifest.ts";
+import { registry } from "./registry.ts";
+import { makeRenderPass } from "./render-pass.ts";
+import { muiThemeOptions } from "./theme.ts";
+
+/**
+ * Material UI v6 provider — a first-class FrameworkAdapter. MUI ships as a
+ * velloo dependency (pre-bundle), so its components SSR in-process against the shared monorepo
+ * React; the adapter's emotion `renderPass` extracts the critical CSS. Styling
+ * is the `sx` prop (not Tailwind), and the theme projects velloo tokens onto a
+ * MUI `createTheme`. Canvas-safe overlays (Dialog/Menu/Popover/Drawer/Snackbar),
+ * `sx`/`createTheme` codegen, `velloo init --library=mui`, the catalog, and the
+ * installed-component canvas bundle (`canvasBundleSpec`) are all wired. The only
+ * deliberate non-build is a `.d.ts` manifest generator — the curated
+ * `MUI_MANIFEST` reads better than a generated dump of MUI's type surface.
+ */
+
+export { MUI_VERSION } from "./version.ts";
+
+import { MUI_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-mui", process.env.VELLOO_MUI_SRC);
+
+export function createProvider(): FrameworkAdapter {
+  const overlayIds = ["Dialog", "Menu", "Popover", "Drawer", "Snackbar"];
+  return {
+    id: "mui",
+    version: MUI_VERSION,
+    label: "Material UI v6",
+    componentsDir: srcDir,
+    styleEntryPath: join(srcDir, "tailwind-entry.css"),
+    registry,
+    loadManifest: async (): Promise<Manifest> => MUI_MANIFEST,
+    // The catalog is the MUI *library* surface — every `@mui/material` 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(
+        MUI_MANIFEST.filter((c) => c.source === "mui"),
+        { importPath: "@mui/material" },
+      ),
+    styleChannel: SX_PROP,
+    styleChannels: ["sx"],
+    mcpIntro: () => [...MUI_INTRO],
+    renderPass: (theme, dark) => makeRenderPass(theme, dark ?? false),
+    codegenModule: "@mui/material",
+    themeToNative: (theme, dark) => muiThemeOptions(theme, dark),
+    themeModule: {
+      importLines: ['import { createTheme } from "@mui/material/styles";'],
+      factory: "createTheme",
+      defaultPath: "theme.ts",
+    },
+    canvasBundleSpec: {
+      components: (ids) =>
+        ids.flatMap((id): CanvasComponentSpec[] => {
+          const descriptor = MUI_MANIFEST.find((entry) => entry.id === id);
+          if (!descriptor) return [];
+          if (descriptor.source === "velloo") {
+            const path = helperSourcePath(id);
+            return path
+              ? [
+                  {
+                    id,
+                    sources: [
+                      {
+                        importPath: path,
+                        exportName: id,
+                        fidelity: "fallback" as const,
+                        note: "Velloo helper used alongside the host framework.",
+                      },
+                    ],
+                  },
+                ]
+              : [];
+          }
+          return [
+            {
+              id,
+              sources: [
+                {
+                  importPath: `@mui/material/${id}`,
+                  exportName: id,
+                  fidelity: overlayIds.includes(id) ? ("adapted" as const) : ("exact" as const),
+                  ...(overlayIds.includes(id)
+                    ? { note: "Real MUI surface rendered through an inline canvas overlay shim." }
+                    : {}),
+                },
+              ],
+            },
+          ];
+        }),
+      overlayIds,
+      styleRuntime: { kind: "emotion", cacheKey: "vmui", stylesModule: "@mui/material/styles" },
+    },
+  };
+}
+
+/** The id used in `Library.id` to select this provider. */
+export const MUI_PROVIDER_ID = "mui" as const;
+
+export { muiThemeFrom, muiThemeOptions } from "./theme.ts";

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

@@ -0,0 +1,12 @@
+/**
+ * MCP instruction framing for a MUI 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 MUI_INTRO: readonly string[] = [
+  "**This folder targets Material UI.** Components are real MUI: `Box`/`Stack`/`Container`/`Paper` for layout, `Card`/`CardContent`/`CardHeader`/`CardActions`, `Typography` (ALL text — pick `variant` for the type scale), `Button`/`IconButton`, `TextField`, `Chip`, `Divider`, `Avatar`, `List`/`ListItem`, `Table*`, `Tabs`/`Tab`, `Alert`, `Tooltip`, and the overlay surface `Dialog`/`Menu`/`Popover`/`Drawer`/`Snackbar` (rendered 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: 2, p: 3, color: "primary.main" } }` — an object of MUI system props, where spacing is theme units (`p: 2` = 16px). It merges shallowly; an inner `null` drops a key, `style: null` clears. `emit_code` emits `<Component sx={{…}} />` importing from `@mui/material`; `emit_theme` emits a `createTheme(...)` module. Tailwind utility diagnostics do not apply here — style via `sx` plus the shared theme tokens from `get_theme`, which project onto MUI.',
+  "",
+];