velloo 0.0.0 → 0.2.0

package/pkgs/helpers/src/icon.tsx

@@ -0,0 +1,53 @@
+// Velloo-owned lucide icon rendered as an inline <svg> from build-time-extracted
+// node data (icon-data.ts, see scripts/generate-icon-data.ts) — no lucide-react
+// at runtime, so bundles carry path data instead of ~2k component exports.
+// The Velloo manifest still carries an "icon" control with the full lucide name
+// set, and codegen lowers <Icon name="X"/> to `<X />` from "lucide-react" so the
+// emitted code has zero Velloo runtime dependencies.
+
+import { pascalizeIconName } from "@velloo/schema/icon-name";
+import * as React from "react";
+import { cn } from "./cn.ts";
+import { ICON_ALIASES, ICON_NODES, type IconNode, LUCIDE_SVG_ATTRIBUTES } from "./icon-data.ts";
+
+export interface IconProps extends React.SVGAttributes<SVGSVGElement> {
+  /** Lucide icon name — PascalCase ("ChevronRight") or kebab-case ("chevron-right"). */
+  name: string;
+  /** Pixel size — the svg's width/height. */
+  size?: number;
+  /** Stroke width. */
+  strokeWidth?: number;
+}
+
+function lookup(name: string): IconNode | undefined {
+  const trimmed = name.trim();
+  const direct = ICON_NODES[trimmed] ?? ICON_NODES[ICON_ALIASES[trimmed] ?? ""];
+  if (direct) return direct;
+  const viaPascal = ICON_ALIASES[pascalizeIconName(trimmed)];
+  return viaPascal === undefined ? undefined : ICON_NODES[viaPascal];
+}
+
+const FALLBACK = lookup("HelpCircle");
+
+export function Icon({ name, className, size = 16, strokeWidth = 2, ...props }: IconProps) {
+  const hit = lookup(name);
+  const node = hit ?? FALLBACK;
+  if (!node) return null;
+  const tint = hit ? className : cn("text-[var(--color-fg-muted)]", className);
+  return (
+    // biome-ignore lint/a11y/noSvgWithoutTitle: decorative by default, like lucide's own components — callers pass aria-* through props.
+    <svg
+      {...LUCIDE_SVG_ATTRIBUTES}
+      width={size}
+      height={size}
+      strokeWidth={strokeWidth}
+      className={tint}
+      {...props}
+    >
+      {node.map(([tag, attrs], i) =>
+        // Node data is static per icon name, so the index key is stable.
+        React.createElement(tag, { ...attrs, key: i }),
+      )}
+    </svg>
+  );
+}

package/pkgs/helpers/src/image.tsx

@@ -0,0 +1,111 @@
+// Velloo-owned image helper. Renders a real `<img>` in design mode (so
+// designs look like the user's final page, not like Placeholder
+// abstractions) but carries Velloo-shaped metadata the agent reads when
+// emitting code: focal point for object-position, aspect for sizing,
+// treatment for overlays.
+//
+// The `src` is preserved verbatim in codegen — point at `assets/`,
+// arbitrary URLs, or whatever the host app convention is.
+import type * as React from "react";
+import { cn } from "./cn.ts";
+
+export interface ImageProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, "loading"> {
+  /**
+   * Asset path. Relative paths resolve against the design folder's
+   * `assets/` directory in design mode; the agent emits them verbatim.
+   */
+  src: string;
+  /**
+   * Aspect ratio shorthand. Matches Placeholder's set so designs stay
+   * consistent when swapping placeholder → real image.
+   */
+  aspect?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9";
+  /**
+   * Focal point (0-1 coords). When the image is cropped via aspect,
+   * the cropping window centers on this point. Defaults to center.
+   */
+  focal?: { x: number; y: number };
+  /**
+   * Optional visual treatment layered on top.
+   * `"overlay-dark"` darkens for hero text legibility;
+   * `"overlay-light"` lightens for light-text-on-bright-image cases;
+   * `"blend-multiply"` blends with the theme's primary;
+   * `"grayscale"` desaturates.
+   */
+  treatment?: "overlay-dark" | "overlay-light" | "blend-multiply" | "grayscale";
+  /**
+   * Whether the image should fill its parent (`true`, default — uses
+   * absolute-positioning inside a relative wrapper) or render at intrinsic
+   * size (`false`).
+   */
+  fill?: boolean;
+}
+
+const ASPECT_CLASS: Record<NonNullable<ImageProps["aspect"]>, string> = {
+  "1/1": "aspect-square",
+  "4/3": "aspect-[4/3]",
+  "3/4": "aspect-[3/4]",
+  "16/9": "aspect-video",
+  "21/9": "aspect-[21/9]",
+};
+
+const TREATMENT_CLASS: Record<NonNullable<ImageProps["treatment"]>, string> = {
+  "overlay-dark":
+    "after:absolute after:inset-0 after:bg-black/40 after:pointer-events-none after:rounded-[inherit]",
+  "overlay-light":
+    "after:absolute after:inset-0 after:bg-white/40 after:pointer-events-none after:rounded-[inherit]",
+  "blend-multiply": "[&>img]:mix-blend-multiply",
+  grayscale: "[&>img]:grayscale",
+};
+
+function focalToObjectPosition(focal: { x: number; y: number } | undefined): string | undefined {
+  if (!focal) return undefined;
+  const clamp = (n: number) => Math.max(0, Math.min(1, n));
+  return `${(clamp(focal.x) * 100).toFixed(1)}% ${(clamp(focal.y) * 100).toFixed(1)}%`;
+}
+
+export function Image({
+  src,
+  alt = "",
+  aspect,
+  focal,
+  treatment,
+  fill = true,
+  className,
+  style,
+  ...rest
+}: ImageProps) {
+  const objectPosition = focalToObjectPosition(focal);
+  const aspectClass = aspect ? ASPECT_CLASS[aspect] : "";
+  const treatmentClass = treatment ? TREATMENT_CLASS[treatment] : "";
+
+  if (!fill) {
+    return (
+      <img
+        src={src}
+        alt={alt}
+        data-slot="image"
+        className={cn("inline-block", className)}
+        style={objectPosition ? { ...style, objectPosition } : style}
+        {...rest}
+      />
+    );
+  }
+
+  return (
+    <div
+      data-slot="image-wrapper"
+      className={cn("relative overflow-hidden", aspectClass, treatmentClass, className)}
+      style={style}
+    >
+      <img
+        src={src}
+        alt={alt}
+        data-slot="image"
+        className="absolute inset-0 h-full w-full object-cover"
+        style={objectPosition ? { objectPosition } : undefined}
+        {...rest}
+      />
+    </div>
+  );
+}

package/pkgs/helpers/src/index.ts

@@ -0,0 +1,29 @@
+export { Box } from "./box.tsx";
+export { cn, mergeTailwind } from "./cn.ts";
+export { HELPER_DESCRIPTORS, helperDescriptors } from "./descriptors.ts";
+export { Divider, type DividerProps } from "./divider.tsx";
+export { Gradient, type GradientProps } from "./gradient.tsx";
+export { Heading, type HeadingProps } from "./heading.tsx";
+export { Icon, type IconProps } from "./icon.tsx";
+export {
+  ICON_ALIASES,
+  ICON_NODES,
+  type IconNode,
+  type IconNodeChild,
+  LUCIDE_SVG_ATTRIBUTES,
+  LUCIDE_VERSION,
+} from "./icon-data.ts";
+export { Image, type ImageProps } from "./image.tsx";
+export { Layer, type LayerProps } from "./layer.tsx";
+export {
+  CONTAINER_WIDTH_CLASS,
+  PLACEHOLDER_ASPECT_CLASS,
+  PLACEHOLDER_AVATAR_SIZE_CLASS,
+  STACK_ALIGN_CLASS,
+  STACK_JUSTIFY_CLASS,
+} from "./lowering.ts";
+export { Placeholder, type PlaceholderProps } from "./placeholder.tsx";
+export { Prose, type ProseProps } from "./prose.tsx";
+export { helpersRegistry } from "./registry.ts";
+export { SVG, type SVGProps } from "./svg.tsx";
+export { Text, type TextProps } from "./text.tsx";

package/pkgs/helpers/src/layer.tsx

@@ -0,0 +1,61 @@
+// Velloo-owned absolute-positioning escape hatch. The default mental
+// model is flex / grid; Layer is for hero compositions where neither
+// makes sense (overlapping decoration, parallax-feel stacks, deliberate
+// off-grid placement).
+//
+// Marked with data-slot="layer" so the canvas can flag heavy usage in
+// inspect_design_quality later — Layer is a "use sparingly" tool.
+import type * as React from "react";
+import { cn } from "./cn.ts";
+
+export interface LayerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Pixel offset from the parent's top edge. Accepts numbers (treated
+   * as px) or any valid CSS length string ("8rem", "12%").
+   */
+  top?: number | string;
+  right?: number | string;
+  bottom?: number | string;
+  left?: number | string;
+  /** Stacking order. Default 1. */
+  z?: number;
+  /**
+   * Whether the layer captures pointer events. Default `true`. Set to
+   * `false` for decorative-only layers that shouldn't block clicks.
+   */
+  pointerEvents?: boolean;
+}
+
+function asLength(v: number | string | undefined): string | undefined {
+  if (v === undefined) return undefined;
+  return typeof v === "number" ? `${v}px` : v;
+}
+
+export function Layer({
+  top,
+  right,
+  bottom,
+  left,
+  z = 1,
+  pointerEvents = true,
+  className,
+  style,
+  ...rest
+}: LayerProps) {
+  return (
+    <div
+      data-slot="layer"
+      className={cn("absolute", className)}
+      style={{
+        top: asLength(top),
+        right: asLength(right),
+        bottom: asLength(bottom),
+        left: asLength(left),
+        zIndex: z,
+        pointerEvents: pointerEvents ? undefined : "none",
+        ...style,
+      }}
+      {...rest}
+    />
+  );
+}

package/pkgs/helpers/src/lowering.ts

@@ -0,0 +1,53 @@
+/**
+ * Codegen lowering tables — the Tailwind class strings each lowered helper
+ * emits, mirroring what the component applies at runtime. Data-only mirrors:
+ * the literals stay duplicated in the co-located `.tsx` components because
+ * the server's Tailwind JIT scans only `.tsx` files for class candidates and
+ * would not see strings that live only in this `.ts` module.
+ *
+ * The typography ladder is the exception, and the model for retiring the rest:
+ * `headingClasses` / `textClasses` in `@velloo/schema/typeset` are called by the
+ * component AND by codegen, because the generated `@source inline(...)` safelist
+ * makes the JIT see those utilities without scanning a literal.
+ */
+
+// Keep in sync with ./placeholder.tsx (`ASPECT_CLASS`).
+export const PLACEHOLDER_ASPECT_CLASS: Record<string, string> = {
+  "1/1": "aspect-square",
+  "4/3": "aspect-[4/3]",
+  "3/4": "aspect-[3/4]",
+  "16/9": "aspect-video",
+  "21/9": "aspect-[21/9]",
+};
+
+// Avatar size ladder — keep in sync with ./placeholder.tsx (`AVATAR_SIZE_CLASS`).
+export const PLACEHOLDER_AVATAR_SIZE_CLASS: Record<string, string> = {
+  sm: "size-8 text-xs",
+  md: "size-10 text-sm",
+  lg: "size-14 text-base",
+  xl: "size-20 text-lg",
+};
+
+// Keep in sync with packages/provider-none/src/components.tsx (Stack/Container
+// live there, not here — these tables ride along so codegen has one home for
+// every lowered-primitive class map).
+export const STACK_ALIGN_CLASS: Record<string, string> = {
+  start: "items-start",
+  center: "items-center",
+  end: "items-end",
+  stretch: "items-stretch",
+};
+export const STACK_JUSTIFY_CLASS: Record<string, string> = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+  around: "justify-around",
+};
+export const CONTAINER_WIDTH_CLASS: Record<string, string> = {
+  sm: "max-w-screen-sm",
+  md: "max-w-screen-md",
+  lg: "max-w-screen-lg",
+  xl: "max-w-screen-xl",
+  full: "max-w-full",
+};

package/pkgs/helpers/src/paths.ts

@@ -0,0 +1,47 @@
+// Node-only module — exported as `@velloo/helpers/paths`, deliberately NOT from
+// the package index: the index is compiled into browser bundles (velloo-cloud's
+// share viewer imports the registries from source) where node:* imports fail.
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the helper component sources. The server's Tailwind JIT
+ * adds this directory to its class-candidate scan so the helpers' structural
+ * default classes (Heading's size ladder, Placeholder's aspect classes, …)
+ * compile no matter which provider's `componentsDir` is active. Resolves from
+ * source (`here` = this `src/` dir) and from the bundled CLI, where the CLI's
+ * `build.ts` copies these sources to `<dist>/pkgs/helpers/src`.
+ */
+function resolveDir(): string {
+  const candidates = [
+    process.env.VELLOO_HELPERS_SRC,
+    join(here, "pkgs", "helpers", "src"),
+    here,
+  ].filter((p): p is string => Boolean(p));
+  return candidates.find((d) => existsSync(join(d, "heading.tsx"))) ?? here;
+}
+
+export const helpersComponentsDir: string = resolveDir();
+
+const HELPER_SOURCE_FILES: Record<string, string> = {
+  Box: "box.tsx",
+  Divider: "divider.tsx",
+  Gradient: "gradient.tsx",
+  Heading: "heading.tsx",
+  Icon: "icon.tsx",
+  Image: "image.tsx",
+  Layer: "layer.tsx",
+  Placeholder: "placeholder.tsx",
+  Prose: "prose.tsx",
+  SVG: "svg.tsx",
+  Text: "text.tsx",
+};
+
+/** Absolute source module for a framework-neutral helper, or undefined. */
+export function helperSourcePath(id: string): string | undefined {
+  const file = HELPER_SOURCE_FILES[id];
+  return file ? join(helpersComponentsDir, file) : undefined;
+}

package/pkgs/helpers/src/placeholder.tsx

@@ -0,0 +1,88 @@
+// Velloo-owned placeholder component. Designs often need a "picture goes
+// here" slot — agent-authored marketing pages especially. This stands in
+// for real imagery during design time and emits as a `<div role="img">` in
+// codegen so the user can swap in a real `<img>` / `<Image>` / `<Avatar>`
+// after export.
+import type * as React from "react";
+import { cn } from "./cn.ts";
+
+export interface PlaceholderProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * Visual shape. `"image"` is a rounded rectangle with an optional label;
+   * `"avatar"` is a circle with a fallback letter — both honor a custom
+   * className for sizing.
+   */
+  kind?: "image" | "avatar" | undefined;
+  /**
+   * Fallback letter or short label inside the placeholder. For avatars
+   * this is typically a single initial; for images it's a hint about
+   * the content ("Hero", "Logo", "Product").
+   */
+  label?: string | undefined;
+  /**
+   * Aspect ratio — `"16/9"`, `"4/3"`, `"1/1"`, `"3/4"`. Only used when
+   * `kind: "image"`. Defaults to `"16/9"`.
+   */
+  aspect?: "1/1" | "4/3" | "3/4" | "16/9" | "21/9" | undefined;
+  /**
+   * Size ladder for `kind: "avatar"`. Mirrors shadcn Avatar conventions:
+   * `sm` (size-8) / `md` (size-10, default) / `lg` (size-14) / `xl` (size-20).
+   * Ignored when `kind: "image"` — sizing there is driven by aspect + width.
+   */
+  size?: "sm" | "md" | "lg" | "xl" | undefined;
+}
+
+const ASPECT_CLASS: Record<NonNullable<PlaceholderProps["aspect"]>, string> = {
+  "1/1": "aspect-square",
+  "4/3": "aspect-[4/3]",
+  "3/4": "aspect-[3/4]",
+  "16/9": "aspect-video",
+  "21/9": "aspect-[21/9]",
+};
+
+const AVATAR_SIZE_CLASS: Record<NonNullable<PlaceholderProps["size"]>, string> = {
+  sm: "size-8 text-xs",
+  md: "size-10 text-sm",
+  lg: "size-14 text-base",
+  xl: "size-20 text-lg",
+};
+
+export function Placeholder({
+  kind = "image",
+  label,
+  aspect = "16/9",
+  size = "md",
+  className,
+  ...rest
+}: PlaceholderProps) {
+  if (kind === "avatar") {
+    return (
+      <div
+        role="img"
+        aria-label={label ? `placeholder: ${label}` : "placeholder avatar"}
+        className={cn(
+          "inline-flex items-center justify-center rounded-full bg-muted text-muted-foreground font-medium",
+          AVATAR_SIZE_CLASS[size],
+          className,
+        )}
+        {...rest}
+      >
+        {label?.slice(0, 2).toUpperCase() ?? ""}
+      </div>
+    );
+  }
+  return (
+    <div
+      role="img"
+      aria-label={label ? `placeholder: ${label}` : "placeholder image"}
+      className={cn(
+        "flex w-full items-center justify-center bg-muted text-muted-foreground text-xs uppercase tracking-wider rounded-md border border-dashed border-border",
+        ASPECT_CLASS[aspect],
+        className,
+      )}
+      {...rest}
+    >
+      {label ?? "image"}
+    </div>
+  );
+}

package/pkgs/helpers/src/prose.tsx

@@ -0,0 +1,42 @@
+// Velloo-owned long-form content region.
+//
+// `typeset` is velloo CSS, not a Tailwind utility — `themeToCss` ships it on
+// every channel — so Prose lives here in the framework-neutral helpers rather
+// than in the shadcn provider. A MUI, Ant Design, Chakra, or no-framework
+// folder gets the same behavior from the same class.
+//
+// It exists to make the common case declarative: long-form content is a
+// *region* with a rhythm, not a stack of individually-classed blocks. Inside
+// one, headings, paragraphs, lists, quotes, code, and tables all pick up the
+// typeset's proportions and vertical spacing automatically.
+
+import type * as React from "react";
+import { createElement } from "react";
+import { cn } from "./cn.ts";
+
+export interface ProseProps extends React.ComponentProps<"div"> {
+  /**
+   * A named typeset from the theme (`set_typeset`). Omitted uses the folder
+   * baseline. The class is emitted unconditionally so a preset added to the
+   * theme later starts applying without touching the screen.
+   */
+  preset?: string;
+  /** HTML tag to render. Defaults to `div`; `article` / `section` are common. */
+  as?: string;
+}
+
+const TAG = /^[a-z][a-z0-9]*$/;
+const PRESET = /^[A-Za-z0-9_-]+$/;
+
+export function Prose({ preset, as, className, ...props }: ProseProps) {
+  const tag = typeof as === "string" && TAG.test(as) ? as : "div";
+  // A preset name reaches CSS as a class, so reject anything not ident-shaped
+  // rather than emitting it.
+  const presetClass =
+    typeof preset === "string" && PRESET.test(preset) ? `typeset-${preset}` : undefined;
+  return createElement(tag, {
+    "data-slot": "prose",
+    className: cn("typeset", presetClass, className),
+    ...props,
+  });
+}

package/pkgs/helpers/src/registry.ts

@@ -0,0 +1,41 @@
+import type { ComponentRegistry } from "@velloo/provider";
+import { Box } from "./box.tsx";
+import { Divider } from "./divider.tsx";
+import { Gradient } from "./gradient.tsx";
+import { Heading } from "./heading.tsx";
+import { Icon } from "./icon.tsx";
+import { Image } from "./image.tsx";
+import { Layer } from "./layer.tsx";
+import { Placeholder } from "./placeholder.tsx";
+import { Prose } from "./prose.tsx";
+import { SVG } from "./svg.tsx";
+import { Text } from "./text.tsx";
+
+const ALL: ComponentRegistry = {
+  Box,
+  Divider,
+  Gradient,
+  Heading,
+  Icon,
+  Image,
+  Layer,
+  Placeholder,
+  Prose,
+  SVG,
+  Text,
+};
+
+/**
+ * Build a registry subset of the velloo helpers. Each provider passes its own
+ * deliberate id list (provider-none reuses nine, its inline channel seven,
+ * provider-mui six; the shadcn snapshot takes all ten) — the *mechanism* is
+ * shared, the lists are not. Unknown ids are skipped.
+ */
+export function helpersRegistry(ids: readonly string[]): ComponentRegistry {
+  const out: ComponentRegistry = {};
+  for (const id of ids) {
+    const component = ALL[id];
+    if (component) out[id] = component;
+  }
+  return out;
+}

package/pkgs/helpers/src/svg.tsx

@@ -0,0 +1,62 @@
+// Velloo-owned helper. Inline SVG that takes its content via the `content`
+// prop (markup string) or via children (full JSX). Used for hero
+// illustrations, decorative shapes, brand marks — anywhere the static
+// design needs custom vector art without re-creating a real `<svg>` tree
+// node-by-node.
+//
+// Codegen emits this as `<svg dangerouslySetInnerHTML={{ __html: ... }}>`
+// when `content` is set, or a regular `<svg>{children}</svg>` otherwise.
+
+import { sanitizeSvgMarkup } from "@velloo/schema/svg-sanitize";
+import type * as React from "react";
+import { cn } from "./cn.ts";
+
+export interface SVGProps extends Omit<React.SVGAttributes<SVGSVGElement>, "content"> {
+  /**
+   * Inline SVG markup. Pass the contents *inside* the outer `<svg>` —
+   * the wrapper element handles viewBox / xmlns. Wins over `children`.
+   */
+  content?: string;
+  /**
+   * viewBox for the wrapper svg. Defaults to "0 0 24 24" so single-glyph
+   * paths line up; override for full-bleed illustrations.
+   */
+  viewBox?: string;
+  /**
+   * The fill / currentColor source. Defaults to "currentColor" so the
+   * SVG inherits the parent's text color and theme-flips correctly.
+   */
+  color?: "currentColor" | "primary" | "accent" | "muted" | string;
+}
+
+const COLOR_CLASS: Record<string, string> = {
+  primary: "text-primary",
+  accent: "text-accent",
+  muted: "text-muted-foreground",
+};
+
+export function SVG({
+  content,
+  viewBox = "0 0 24 24",
+  color = "currentColor",
+  className,
+  children,
+  ...rest
+}: SVGProps) {
+  const colorClass = COLOR_CLASS[color] ?? "";
+  const props = {
+    xmlns: "http://www.w3.org/2000/svg",
+    viewBox,
+    fill: color === "currentColor" ? "currentColor" : undefined,
+    "data-slot": "svg",
+    className: cn("inline-block", colorClass, className),
+    ...rest,
+  };
+
+  if (content) {
+    // biome-ignore lint/security/noDangerouslySetInnerHtml: this is the whole point of the SVG helper
+    return <svg {...props} dangerouslySetInnerHTML={{ __html: sanitizeSvgMarkup(content) }} />;
+  }
+  // biome-ignore lint/a11y/noSvgWithoutTitle: consumer supplies title via children when needed
+  return <svg {...props}>{children}</svg>;
+}

package/pkgs/helpers/src/text.tsx

@@ -0,0 +1,16 @@
+// Velloo-owned typography primitive — no shadcn equivalent exists.
+import { textClasses } from "@velloo/schema/typeset";
+import * as React from "react";
+import { cn } from "./cn.ts";
+
+export interface TextProps extends React.HTMLAttributes<HTMLParagraphElement> {
+  /** Visual weight. Selects a rung of the theme's type ladder plus a tone. */
+  variant?: "default" | "muted" | "small" | "lead";
+}
+
+export const Text = React.forwardRef<HTMLParagraphElement, TextProps>(
+  ({ variant = "default", className, ...props }, ref) => (
+    <p ref={ref} className={cn(textClasses(variant), className)} {...props} />
+  ),
+);
+Text.displayName = "Text";