velloo 0.0.0 → 0.2.0

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

@@ -0,0 +1,263 @@
+import type { ComponentDescriptor, Manifest, PropDescriptor } from "@velloo/provider";
+
+/**
+ * Hand-authored MUI manifest for the shipped registry — curated to the props an
+ * agent actually sets (variant/color/size, the `sx` style channel, children),
+ * which reads far better than a generated dump of MUI's vast type surface. A
+ * ts-morph `.d.ts` generator remains an option for breadth, but the curated
+ * manifest is the chosen default; this stays the source of truth.
+ */
+
+const sx: PropDescriptor = {
+  name: "sx",
+  type: "SxProps | undefined",
+  optional: true,
+  control: "string",
+};
+const children: PropDescriptor = {
+  name: "children",
+  type: "ReactNode",
+  optional: true,
+  control: "string",
+};
+const enumProp = (name: string, values: string[], defaultValue?: string): PropDescriptor => ({
+  name,
+  type: values.map((v) => `"${v}"`).join(" | "),
+  optional: true,
+  control: "enum",
+  enumValues: values,
+  defaultValue,
+});
+
+function ui(
+  id: string,
+  props: PropDescriptor[],
+  notes?: string,
+  example?: Record<string, unknown>,
+): ComponentDescriptor {
+  return {
+    id,
+    category: "ui",
+    source: "mui",
+    props: [...props, sx],
+    designModeNotes: notes,
+    example,
+  };
+}
+
+const className: PropDescriptor = {
+  name: "className",
+  type: "string | undefined",
+  optional: true,
+  control: "string",
+};
+
+/** A reused framework-neutral velloo helper (source "velloo") — styled via className, not sx. */
+function helper(
+  id: string,
+  props: PropDescriptor[],
+  notes?: string,
+  example?: Record<string, unknown>,
+): ComponentDescriptor {
+  return {
+    id,
+    category: "ui",
+    source: "velloo",
+    props: [...props, className],
+    designModeNotes: notes,
+    example,
+  };
+}
+
+export const MUI_MANIFEST: Manifest = [
+  ui("Box", [children], "Generic layout primitive; style via sx."),
+  ui(
+    "Stack",
+    [children, enumProp("direction", ["row", "column"], "column")],
+    "Flex layout; set spacing via sx or the spacing prop.",
+  ),
+  ui(
+    "Container",
+    [children, enumProp("maxWidth", ["xs", "sm", "md", "lg", "xl"], "lg")],
+    "Centers + max-widths content.",
+  ),
+  ui("Paper", [children, enumProp("variant", ["elevation", "outlined"], "elevation")]),
+  ui("Card", [children, enumProp("variant", ["elevation", "outlined"], "elevation")]),
+  ui("CardContent", [children]),
+  ui("CardHeader", [
+    { name: "title", type: "ReactNode", optional: true, control: "string" },
+    { name: "subheader", type: "ReactNode", optional: true, control: "string" },
+  ]),
+  ui("CardActions", [children]),
+  ui(
+    "Button",
+    [
+      children,
+      enumProp("variant", ["text", "outlined", "contained"], "text"),
+      enumProp("color", ["primary", "secondary", "success", "error", "inherit"], "primary"),
+      enumProp("size", ["small", "medium", "large"], "medium"),
+    ],
+    "Action button.",
+    { variant: "contained", color: "primary", children: "Submit" },
+  ),
+  ui(
+    "Typography",
+    [
+      children,
+      enumProp(
+        "variant",
+        [
+          "h1",
+          "h2",
+          "h3",
+          "h4",
+          "h5",
+          "h6",
+          "subtitle1",
+          "subtitle2",
+          "body1",
+          "body2",
+          "caption",
+          "overline",
+        ],
+        "body1",
+      ),
+      enumProp("color", ["text.primary", "text.secondary", "primary", "error"]),
+    ],
+    "All text. Pick variant for the type scale; this is MUI's Heading + Text.",
+    { variant: "h4", children: "Team analytics" },
+  ),
+  ui("TextField", [
+    enumProp("variant", ["outlined", "filled", "standard"], "outlined"),
+    { name: "label", type: "string", optional: true, control: "string" },
+    { name: "placeholder", type: "string", optional: true, control: "string" },
+  ]),
+  ui("Chip", [
+    { name: "label", type: "ReactNode", optional: true, control: "string" },
+    enumProp("variant", ["filled", "outlined"], "filled"),
+    enumProp("color", ["default", "primary", "success", "warning", "error"], "default"),
+    enumProp("size", ["small", "medium"], "medium"),
+  ]),
+  ui("Divider", []),
+  ui("Avatar", [children, { name: "src", type: "string", optional: true, control: "string" }]),
+  ui("LinearProgress", [
+    { name: "value", type: "number", optional: true, control: "number" },
+    enumProp("variant", ["determinate", "indeterminate"], "indeterminate"),
+  ]),
+  ui("AppBar", [
+    children,
+    enumProp("position", ["fixed", "static", "sticky"], "fixed"),
+    enumProp("color", ["primary", "default", "transparent", "inherit"], "primary"),
+  ]),
+  ui("Toolbar", [children]),
+  ui("IconButton", [children, enumProp("size", ["small", "medium", "large"], "medium")]),
+  ui("Link", [children, { name: "href", type: "string", optional: true, control: "string" }]),
+  ui("List", [children]),
+  ui("ListItem", [children]),
+  ui("ListItemText", [
+    { name: "primary", type: "ReactNode", optional: true, control: "string" },
+    { name: "secondary", type: "ReactNode", optional: true, control: "string" },
+  ]),
+  ui("Table", [children]),
+  ui("TableHead", [children]),
+  ui("TableBody", [children]),
+  ui("TableRow", [children]),
+  ui("TableCell", [children, enumProp("align", ["left", "center", "right"], "left")]),
+  ui("Tabs", [
+    children,
+    { name: "value", type: "number | string", optional: true, control: "string" },
+  ]),
+  ui("Tab", [{ name: "label", type: "ReactNode", optional: true, control: "string" }]),
+  ui("Badge", [
+    children,
+    { name: "badgeContent", type: "ReactNode", optional: true, control: "string" },
+  ]),
+  ui("Checkbox", [{ name: "checked", type: "boolean", optional: true, control: "boolean" }]),
+  ui("Switch", [{ name: "checked", type: "boolean", optional: true, control: "boolean" }]),
+  ui("Select", [children, enumProp("variant", ["outlined", "filled", "standard"], "outlined")]),
+  ui("MenuItem", [
+    children,
+    { name: "value", type: "string | number", optional: true, control: "string" },
+  ]),
+  ui("Tooltip", [
+    children,
+    { name: "title", type: "ReactNode", optional: true, control: "string" },
+  ]),
+  ui("Alert", [children, enumProp("severity", ["success", "info", "warning", "error"], "success")]),
+
+  // Overlay surface — canvas-safe: rendered OPEN + inline in design mode (no
+  // portal/backdrop), so build the content directly inside them.
+  ui(
+    "Dialog",
+    [children, enumProp("maxWidth", ["xs", "sm", "md", "lg", "xl"], "sm")],
+    "Modal dialog surface — renders open + inline in design mode. Fill it with DialogTitle / DialogContent / DialogActions.",
+    { maxWidth: "sm" },
+  ),
+  ui("DialogTitle", [children], "The dialog's heading row."),
+  ui("DialogContent", [children], "The dialog's body."),
+  ui("DialogContentText", [children], "Secondary text inside DialogContent."),
+  ui("DialogActions", [children], "The dialog's button row (right-aligned)."),
+  ui(
+    "Menu",
+    [children],
+    "A menu surface holding MenuItems — renders open + inline in design mode.",
+  ),
+  ui("Popover", [children], "A popover surface — renders open + inline in design mode."),
+  ui("Drawer", [children], "A side panel — renders inline as a fixed-width column in design mode."),
+  ui(
+    "Snackbar",
+    [children, { name: "message", type: "ReactNode", optional: true, control: "string" }],
+    "A toast — renders inline as a dark pill in design mode. Use `message` or children.",
+    { message: "Saved" },
+  ),
+
+  // Framework-neutral velloo helpers (MUI bundles no icon set; @mui/icons-material
+  // isn't shipped). source:"velloo" — sized/styled via props (NOT sx/Tailwind: a
+  // MUI folder has no JIT). `Icon` emits a lucide-react import in codegen.
+  helper(
+    "Icon",
+    [
+      { name: "name", type: "string", optional: false, control: "icon" },
+      { name: "size", type: "number", optional: true, control: "number" },
+    ],
+    "A lucide icon — MUI has no bundled icon set. Set the pixel `size` prop (not Tailwind). `name` is a lucide id (PascalCase or kebab). Emits a `lucide-react` import.",
+    { name: "ArrowRight", size: 20 },
+  ),
+  helper(
+    "Image",
+    [
+      { name: "src", type: "string", optional: false, control: "string" },
+      { name: "alt", type: "string", optional: false, control: "string" },
+    ],
+    "An image. Use velloo assets (`/assets/…`) or a URL.",
+  ),
+  helper(
+    "Placeholder",
+    [{ name: "label", type: "string", optional: true, control: "string" }],
+    "A labeled placeholder box for imagery you haven't authored yet (avatars, hero shots).",
+  ),
+  helper(
+    "SVG",
+    [
+      { name: "content", type: "string", optional: false, control: "string" },
+      { name: "viewBox", type: "string", optional: false, control: "string" },
+    ],
+    "Raw inline SVG markup.",
+  ),
+  helper("Layer", [children], "An absolutely-positioned overlay layer for stacked composition."),
+  helper(
+    "Gradient",
+    [{ name: "from", type: "string", optional: true, control: "color" }],
+    "A gradient fill block.",
+  ),
+  helper(
+    "Prose",
+    [
+      children,
+      { name: "preset", type: "string", optional: true, control: "string" },
+      { name: "as", type: "string", optional: true, control: "string" },
+    ],
+    "A long-form content region. Everything inside — Typography, headings, lists, quotes, code, tables — picks up the theme typeset's proportions and vertical rhythm automatically. `preset` selects a named typeset (see set_typeset). Reach for this for articles, docs, and marketing copy instead of setting sizes block by block.",
+    { as: "article" },
+  ),
+];

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

@@ -0,0 +1,124 @@
+import Box from "@mui/material/Box";
+import DialogActions from "@mui/material/DialogActions";
+import DialogContent from "@mui/material/DialogContent";
+import DialogContentText from "@mui/material/DialogContentText";
+import DialogTitle from "@mui/material/DialogTitle";
+import Paper from "@mui/material/Paper";
+import { createElement, type ReactElement, type ReactNode } from "react";
+
+/**
+ * Canvas-safe MUI overlays. MUI's Dialog/Menu/Popover/Drawer/Snackbar portal to
+ * `document.body` and default to closed — 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* in
+ * a Paper inline; the open/anchor/transition machinery is dropped. The
+ * sub-parts (DialogTitle/Content/Actions) are MUI's real components — they're
+ * plain styled boxes that already render inline — re-exported as-is.
+ *
+ * Mirrors 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 } : {}),
+  };
+}
+
+function mergeSx(base: Record<string, unknown>, sx: unknown): Record<string, unknown> {
+  return sx && typeof sx === "object" && !Array.isArray(sx) ? { ...base, ...sx } : base;
+}
+
+const DIALOG_WIDTH: Record<string, number> = { xs: 360, sm: 480, md: 600, lg: 800, xl: 960 };
+
+/** The dialog surface, rendered inline (open, no portal/backdrop). */
+export function Dialog(props: Props): ReactElement {
+  const width = typeof props.maxWidth === "string" ? (DIALOG_WIDTH[props.maxWidth] ?? 600) : 600;
+  return createElement(
+    Paper,
+    {
+      ...chrome(props),
+      elevation: 8,
+      sx: mergeSx(
+        { width: "100%", maxWidth: width, mx: "auto", my: 2, borderRadius: 2, overflow: "hidden" },
+        props.sx,
+      ),
+    },
+    props.children,
+  );
+}
+
+/** A menu surface (a Paper holding MenuItems), rendered inline. */
+export function Menu(props: Props): ReactElement {
+  return createElement(
+    Paper,
+    {
+      ...chrome(props),
+      elevation: 3,
+      sx: mergeSx({ display: "inline-block", minWidth: 180, py: 1, borderRadius: 1.5 }, props.sx),
+    },
+    props.children,
+  );
+}
+
+/** A popover surface, rendered inline. */
+export function Popover(props: Props): ReactElement {
+  return createElement(
+    Paper,
+    {
+      ...chrome(props),
+      elevation: 3,
+      sx: mergeSx({ display: "inline-block", p: 2, borderRadius: 1.5 }, props.sx),
+    },
+    props.children,
+  );
+}
+
+/** A side-drawer panel, rendered inline as a fixed-width column. */
+export function Drawer(props: Props): ReactElement {
+  return createElement(
+    Paper,
+    {
+      ...chrome(props),
+      elevation: 2,
+      square: true,
+      sx: mergeSx({ width: 280, height: "100%", p: 2 }, props.sx),
+    },
+    props.children,
+  );
+}
+
+/** A toast, rendered inline as a dark pill. `message` or children. */
+export function Snackbar(props: Props): ReactElement {
+  const body = props.message !== undefined ? (props.message as ReactNode) : props.children;
+  return createElement(
+    Box,
+    {
+      ...chrome(props),
+      sx: mergeSx(
+        {
+          display: "inline-flex",
+          alignItems: "center",
+          px: 2,
+          py: 1.25,
+          bgcolor: "grey.900",
+          color: "common.white",
+          borderRadius: 1,
+          fontSize: 14,
+        },
+        props.sx,
+      ),
+    },
+    body,
+  );
+}
+
+export { DialogActions, DialogContent, DialogContentText, DialogTitle };

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

@@ -0,0 +1,120 @@
+import Alert from "@mui/material/Alert";
+import AppBar from "@mui/material/AppBar";
+import Avatar from "@mui/material/Avatar";
+import Badge from "@mui/material/Badge";
+import Box from "@mui/material/Box";
+import Button from "@mui/material/Button";
+import Card from "@mui/material/Card";
+import CardActions from "@mui/material/CardActions";
+import CardContent from "@mui/material/CardContent";
+import CardHeader from "@mui/material/CardHeader";
+import Checkbox from "@mui/material/Checkbox";
+import Chip from "@mui/material/Chip";
+import Container from "@mui/material/Container";
+import Divider from "@mui/material/Divider";
+import IconButton from "@mui/material/IconButton";
+import LinearProgress from "@mui/material/LinearProgress";
+import Link from "@mui/material/Link";
+import List from "@mui/material/List";
+import ListItem from "@mui/material/ListItem";
+import ListItemText from "@mui/material/ListItemText";
+import MenuItem from "@mui/material/MenuItem";
+import Paper from "@mui/material/Paper";
+import Select from "@mui/material/Select";
+import Stack from "@mui/material/Stack";
+import Switch from "@mui/material/Switch";
+import Tab from "@mui/material/Tab";
+import Table from "@mui/material/Table";
+import TableBody from "@mui/material/TableBody";
+import TableCell from "@mui/material/TableCell";
+import TableHead from "@mui/material/TableHead";
+import TableRow from "@mui/material/TableRow";
+import Tabs from "@mui/material/Tabs";
+import TextField from "@mui/material/TextField";
+import Toolbar from "@mui/material/Toolbar";
+import Tooltip from "@mui/material/Tooltip";
+import Typography from "@mui/material/Typography";
+import { helpersRegistry } from "@velloo/helpers";
+import type { ComponentRegistry } from "@velloo/provider";
+import {
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogContentText,
+  DialogTitle,
+  Drawer,
+  Menu,
+  Popover,
+  Snackbar,
+} from "./overlays.ts";
+
+const REUSED_HELPER_IDS = [
+  "Icon",
+  "Image",
+  "Placeholder",
+  "SVG",
+  "Layer",
+  "Gradient",
+  "Prose",
+] as const;
+
+/**
+ * The runtime registry for MUI-native folders: design `$ref` ids → real MUI
+ * components. SSR'd in-process via the adapter's emotion render pass. The
+ * overlay surface (Dialog/Menu/Popover/Drawer/Snackbar) is canvas-safe-wrapped
+ * in `overlays.ts` — rendered open + inline so a screenshot shows it; their
+ * sub-parts (DialogTitle/Content/Actions) are MUI's real inline components.
+ * Tooltip is a passthrough (it renders its child inline in SSR).
+ */
+export const registry: ComponentRegistry = {
+  Alert,
+  AppBar,
+  Avatar,
+  Badge,
+  Box,
+  Button,
+  Card,
+  CardActions,
+  CardContent,
+  CardHeader,
+  Checkbox,
+  Chip,
+  Container,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogContentText,
+  DialogTitle,
+  Divider,
+  Drawer,
+  IconButton,
+  LinearProgress,
+  Link,
+  List,
+  ListItem,
+  ListItemText,
+  Menu,
+  MenuItem,
+  Paper,
+  Popover,
+  Select,
+  Snackbar,
+  Stack,
+  Switch,
+  Tab,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableRow,
+  Tabs,
+  TextField,
+  Toolbar,
+  Tooltip,
+  Typography,
+  // Framework-neutral velloo helpers MUI has no equivalent for — chiefly `Icon`
+  // (lucide; MUI's own @mui/icons-material isn't bundled) + imagery/composition
+  // helpers. Reused verbatim from `@velloo/helpers`, like provider-none. They
+  // size via props (`Icon size`), not Tailwind — the JIT is off on a MUI folder.
+  ...helpersRegistry(REUSED_HELPER_IDS),
+};

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

@@ -0,0 +1,36 @@
+import createCache from "@emotion/cache";
+import { CacheProvider } from "@emotion/react";
+import createEmotionServer from "@emotion/server/create-instance";
+import { ThemeProvider } from "@mui/material/styles";
+import type { RenderPass } from "@velloo/provider";
+import type { Theme as VellooTheme } from "@velloo/schema";
+import { createElement } from "react";
+import { muiThemeFrom } from "./theme.ts";
+
+/**
+ * A fresh emotion + MUI render pass for one SSR. `wrap` nests the tree under a
+ * per-render emotion CacheProvider + a MUI ThemeProvider built from velloo's
+ * tokens; `css(html)` extracts exactly the emotion rules the rendered markup
+ * uses. The renderer injects that CSS into a `data-velloo-adapter` <style>.
+ *
+ * SSR works in-process because @mui/material 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: "vmui", prepend: true });
+  const server = createEmotionServer(cache);
+  const muiTheme = muiThemeFrom(theme, dark);
+  return {
+    wrap: (element) =>
+      createElement(
+        CacheProvider,
+        { value: cache },
+        createElement(ThemeProvider, { theme: muiTheme }, element),
+      ),
+    css: (html) =>
+      server
+        .extractCriticalToChunks(html)
+        .styles.map((s) => s.css)
+        .join(""),
+  };
+}

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

@@ -0,0 +1,21 @@
+/*
+ * MUI styles components via emotion (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 (or a
+ * `style`-channel escape hatch) 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);
+}