@devxcrew/react-ui 0.0.0-stage → 0.1.7

package/src/design-system/block-registry.ts

@@ -0,0 +1,272 @@
+import type { DesignSystemBlockDefinition, DesignSystemVariantDefinition } from "./contracts";
+
+const defaultVariant: DesignSystemVariantDefinition = {
+  description: "The package-owned application default.",
+  id: "default",
+  name: "Default",
+};
+
+const tableVariants: readonly DesignSystemVariantDefinition[] = [
+  {
+    description: "A complete workspace table with tools, totals, and pagination.",
+    id: "default",
+    name: "Workspace",
+  },
+  {
+    description: "A compact table section without page-level tools.",
+    id: "section",
+    name: "Section",
+  },
+];
+
+const workspaceEntityCardVariants: readonly DesignSystemVariantDefinition[] = [
+  defaultVariant,
+  {
+    description: "A workspace entity card with shared hover treatment for interactive inventory surfaces.",
+    id: "interactive",
+    name: "Interactive",
+  },
+];
+
+export const designSystemBlocks: readonly DesignSystemBlockDefinition[] = [
+  {
+    defaultVariantId: "default",
+    description: "Shared runtime state, health, publish, and route readiness surfaces for workspace dashboards.",
+    id: "workspace-status",
+    name: "Workspace Status",
+    source: "@devxcrew/react-ui/blocks/workspace",
+    variants: [
+      defaultVariant,
+      {
+        description: "Runtime state with optional port, HTTP status, latency, and action.",
+        id: "runtime",
+        name: "Runtime",
+      },
+      { description: "Compact health metric summary.", id: "health", name: "Health" },
+      { description: "Published, review, or draft state badge.", id: "publish", name: "Publish" },
+      { description: "Ready, pending, or blocked route checklist.", id: "routes", name: "Routes" },
+    ],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A reusable entity card for workspace inventories, resources, and live status surfaces.",
+    id: "workspace-entity-card",
+    name: "Workspace Entity Card",
+    source: "@devxcrew/react-ui/blocks/workspace",
+    variants: workspaceEntityCardVariants,
+  },
+  {
+    defaultVariantId: "default",
+    description: "Observed execution state, readiness checklists, and optional startup splash with measured values.",
+    id: "execution-status",
+    name: "Execution Status",
+    source: "@devxcrew/react-ui/blocks/execution-status",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A typed data table with application-owned rows and columns.",
+    id: "table",
+    name: "Table",
+    source: "@devxcrew/react-ui/blocks/table",
+    variants: tableVariants,
+  },
+  {
+    defaultVariantId: "default",
+    description: "A typed application form frame with tabs, lookup fields, and actions.",
+    id: "form",
+    name: "Form",
+    source: "@devxcrew/react-ui/blocks/form",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A pointer-aware, clickable character rendered from two aligned 3x3 sprite sheets.",
+    id: "mascot",
+    name: "Mascot",
+    source: "@devxcrew/react-ui/blocks/mascot",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "breadcrumb-actions",
+    description: "A shared page-level header with breadcrumb, title, filter, resource, and action arrangements.",
+    id: "app-header",
+    name: "App Header",
+    source: "@devxcrew/react-ui/blocks/app-header",
+    variants: [
+      {
+        description: "Breadcrumb context with an optional profile slot and primary action.",
+        id: "breadcrumb-actions",
+        name: "Breadcrumb + action",
+      },
+      {
+        description: "Icon and page title with filter controls and a primary action.",
+        id: "title-actions",
+        name: "Title + filter + action",
+      },
+      {
+        description: "Resource link with a copy affordance at the right edge.",
+        id: "resource-actions",
+        name: "Resource + copy",
+      },
+    ],
+  },
+  {
+    defaultVariantId: "default",
+    description: "An interactive drag-and-drop Kanban board with sortable columns and cards.",
+    id: "kanban",
+    name: "Kanban Board",
+    source: "@devxcrew/react-ui/blocks/kanban",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A hierarchical file and workspace explorer tree with icons, filter, and actions.",
+    id: "file-tree",
+    name: "File Tree",
+    source: "@devxcrew/react-ui/blocks/file-tree",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A drag-and-drop file upload zone with type/size validation and progress tracking.",
+    id: "dropzone",
+    name: "File Dropzone",
+    source: "@devxcrew/react-ui/blocks/dropzone",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A safe live preview for Mermaid diagram source.",
+    id: "mermaid-preview",
+    name: "Mermaid Preview",
+    source: "@devxcrew/react-ui/blocks/mermaid-preview",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A multi-condition query filter builder with combinators and typed operators.",
+    id: "filter-builder",
+    name: "Filter Builder",
+    source: "@devxcrew/react-ui/blocks/filter-builder",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "An e-commerce product card with image zoom, ratings, swatches, and cart actions.",
+    id: "product-card",
+    name: "Product Card",
+    source: "@devxcrew/react-ui/blocks/product-card",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A multi-tier pricing table with monthly/annual interval toggle and feature lists.",
+    id: "pricing",
+    name: "Pricing Table",
+    source: "@devxcrew/react-ui/blocks/pricing",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "An interactive storefront slide-over cart drawer with quantity stepper and shipping threshold meter.",
+    id: "cart",
+    name: "Storefront Cart",
+    source: "@devxcrew/react-ui/blocks/ecommerce/cart",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A storefront category visual grid, megamenu navigation, and pill filter strip.",
+    id: "categories",
+    name: "Categories Showcase",
+    source: "@devxcrew/react-ui/blocks/ecommerce/categories",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A multi-step checkout wizard covering shipping destination, payment method, and order review.",
+    id: "checkout",
+    name: "Checkout Wizard",
+    source: "@devxcrew/react-ui/blocks/ecommerce/checkout",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A side-by-side product comparison matrix with spec rows and difference highlighting.",
+    id: "comparison",
+    name: "Product Comparison",
+    source: "@devxcrew/react-ui/blocks/ecommerce/comparison",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A promotional coupon wallet with voucher cards, instant code copy, and applied discount management.",
+    id: "coupon-wallet",
+    name: "Coupon Wallet",
+    source: "@devxcrew/react-ui/blocks/ecommerce/coupon-wallet",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A visual shipment milestone timeline with courier details and live delivery status.",
+    id: "delivery-tracker",
+    name: "Delivery Tracker",
+    source: "@devxcrew/react-ui/blocks/ecommerce/delivery-tracker",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A checkout payment method selector covering saved cards with CVV entry, UPI, wallets, and COD.",
+    id: "payment-methods",
+    name: "Payment Methods",
+    source: "@devxcrew/react-ui/blocks/ecommerce/payment-methods",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A historical price trend visualization with lowest/peak markers and price drop notifications.",
+    id: "price-history",
+    name: "Price History Tracker",
+    source: "@devxcrew/react-ui/blocks/ecommerce/price-history",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "An aggregate rating breakdown, verified customer reviews list, and write-review form.",
+    id: "reviews",
+    name: "Reviews & Ratings",
+    source: "@devxcrew/react-ui/blocks/ecommerce/reviews",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A saved items wishlist grid with stock availability indicators and quick move-to-cart actions.",
+    id: "wishlist",
+    name: "Wishlist Grid",
+    source: "@devxcrew/react-ui/blocks/ecommerce/wishlist",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description:
+      "A multi-column storefront and content footer with newsletter subscribe, social links, and payment badges.",
+    id: "footer",
+    name: "Site Footer",
+    source: "@devxcrew/react-ui/blocks/footer",
+    variants: [defaultVariant],
+  },
+  {
+    defaultVariantId: "default",
+    description:
+      "An editorial blog suite featuring post cards (standard, horizontal, compact) and rich article reading layout.",
+    id: "blog",
+    name: "Blog & Editorial",
+    source: "@devxcrew/react-ui/blocks/blog",
+    variants: [defaultVariant],
+  },
+];
+
+export function getDesignSystemBlock(blockId: string) {
+  return designSystemBlocks.find(({ id }) => id === blockId);
+}

package/src/design-system/component-registry.ts

@@ -0,0 +1,142 @@
+import type { DesignSystemCategory, DesignSystemComponentDefinition, DesignSystemVariantDefinition } from "./contracts";
+import { buttonDefaultVariant, buttonGroupDefaultOrientation } from "./defaults";
+
+const defaultVariant: DesignSystemVariantDefinition = {
+  description: "The package-owned application default.",
+  id: "default",
+  name: "Default",
+};
+
+const componentNames: Record<DesignSystemCategory, readonly string[]> = {
+  Actions: ["Button", "Button Group", "Toggle", "Toggle Group"],
+  Communication: ["Attachment", "Bubble", "Message", "Message Scroller"],
+  "Data display": [
+    "Avatar",
+    "Badge",
+    "Calendar",
+    "Card",
+    "Carousel",
+    "Chart",
+    "Item",
+    "Kbd",
+    "Marker",
+    "Sparkline",
+    "Table",
+  ],
+  Feedback: ["Alert", "Empty", "Progress", "Skeleton", "Sonner", "Spinner", "Toast"],
+  Forms: [
+    "Checkbox",
+    "Combobox",
+    "Field",
+    "Input",
+    "Input Group",
+    "Input OTP",
+    "Label",
+    "Native Select",
+    "Questionnaire",
+    "Radio Group",
+    "Rich Text Editor",
+    "Select",
+    "Slider",
+    "Switch",
+    "Textarea",
+  ],
+  Layout: ["Aspect Ratio", "Collapsible", "Direction", "Resizable", "Scroll Area", "Separator"],
+  Navigation: ["Accordion", "Breadcrumb", "Menubar", "Navigation Menu", "Pagination", "Sidebar", "Tabs"],
+  Overlays: [
+    "Alert Dialog",
+    "Command",
+    "Context Menu",
+    "Dialog",
+    "Drawer",
+    "Dropdown Menu",
+    "Hover Card",
+    "Popover",
+    "Sheet",
+    "Tooltip",
+  ],
+};
+
+const componentVariants: Readonly<Record<string, readonly DesignSystemVariantDefinition[]>> = {
+  sidebar: [
+    defaultVariant,
+    { id: "outline", name: "Outline", description: "A bordered sidebar menu button." },
+    {
+      id: "accented",
+      name: "Accented",
+      description: "A left-aligned sidebar menu button with a selected accent marker. Supports comfortable 40px rows.",
+    },
+  ],
+  accordion: [
+    {
+      description: "The standard borderless disclosure list.",
+      id: "default",
+      name: "Borderless",
+    },
+    {
+      description: "A connected disclosure list with an outer border.",
+      id: "boxed",
+      name: "Boxed",
+    },
+  ],
+  alert: [
+    { description: "A neutral application notice.", id: "default", name: "Default" },
+    {
+      description: "A destructive or failed-state notice.",
+      id: "destructive",
+      name: "Destructive",
+    },
+  ],
+  button: [
+    { description: "The main action on a surface.", id: "default", name: "Primary" },
+    { description: "A strong action without theme emphasis.", id: "neutral", name: "Neutral" },
+    { description: "An alternative action.", id: "secondary", name: "Secondary" },
+    { description: "A successful completion action.", id: "success", name: "Success" },
+    { description: "An action that needs review.", id: "warning", name: "Warning" },
+    { description: "An informational action.", id: "info", name: "Information" },
+    { description: "An irreversible action.", id: "destructive", name: "Destructive" },
+    { description: "A bordered surface action.", id: "outline", name: "Outline" },
+    { description: "A quiet contextual action.", id: "ghost", name: "Ghost" },
+    { description: "A navigation action.", id: "link", name: "Link" },
+  ],
+  "button-group": [
+    {
+      description: "A connected horizontal action group.",
+      id: buttonGroupDefaultOrientation,
+      name: "Horizontal",
+    },
+    { description: "A connected vertical action group.", id: "vertical", name: "Vertical" },
+  ],
+};
+
+export const designSystemCategories = Object.keys(componentNames) as DesignSystemCategory[];
+
+export const designSystemComponents: readonly DesignSystemComponentDefinition[] = designSystemCategories.flatMap(
+  (category) => componentNames[category].map((name) => createComponentDefinition(category, name)),
+);
+
+export function getDesignSystemComponent(componentId: string) {
+  return designSystemComponents.find(({ id }) => id === componentId);
+}
+
+function createComponentDefinition(category: DesignSystemCategory, name: string): DesignSystemComponentDefinition {
+  const id = toId(name);
+  return {
+    category,
+    defaultVariantId: resolveDefaultVariantId(id),
+    id,
+    name,
+    source: `@devxcrew/react-ui/components/${id}`,
+    variants: componentVariants[id] ?? [defaultVariant],
+  };
+}
+
+function resolveDefaultVariantId(componentId: string) {
+  if (componentId === "button") return buttonDefaultVariant;
+  if (componentId === "button-group") return buttonGroupDefaultOrientation;
+  return "default";
+}
+
+function toId(name: string) {
+  return name.toLowerCase().replaceAll(" ", "-");
+}

package/src/design-system/contracts.ts

@@ -0,0 +1,69 @@
+export type DesignSystemCategory =
+  "Actions" | "Communication" | "Data display" | "Feedback" | "Forms" | "Layout" | "Navigation" | "Overlays";
+
+export type DesignSystemVariantDefinition = {
+  description: string;
+  id: string;
+  name: string;
+};
+
+export type DesignSystemAssetKind = "block" | "component" | "page" | "template";
+
+export type DesignSystemOwnership = {
+  applicationOwns: readonly string[];
+  packageOwns: readonly string[];
+};
+
+export type DesignSystemAssetManifest = {
+  defaultVariantId: string;
+  description: string;
+  id: string;
+  kind: DesignSystemAssetKind;
+  name: string;
+  ownership: DesignSystemOwnership;
+  source: string;
+  variants: readonly DesignSystemVariantDefinition[];
+};
+
+export type DesignSystemComponentDefinition = {
+  category: DesignSystemCategory;
+  defaultVariantId: string;
+  id: string;
+  name: string;
+  source: string;
+  variants: readonly DesignSystemVariantDefinition[];
+};
+
+export type DesignSystemBlockDefinition = {
+  defaultVariantId: string;
+  description: string;
+  id: string;
+  name: string;
+  source: string;
+  variants: readonly DesignSystemVariantDefinition[];
+};
+
+export type DesignSystemPageDefinition = {
+  defaultVariantId: string;
+  description: string;
+  id: string;
+  name: string;
+  source: string;
+  variants: readonly DesignSystemVariantDefinition[];
+};
+
+export type DesignSystemTemplateDefinition = DesignSystemPageDefinition;
+
+export type DesignSystemSelection = {
+  blocks: Readonly<Record<string, string>>;
+  components: Readonly<Record<string, string>>;
+  pages: Readonly<Record<string, string>>;
+  templates: Readonly<Record<string, string>>;
+};
+
+export type DesignSystemSelectionInput = {
+  blocks?: Readonly<Record<string, string>>;
+  components?: Readonly<Record<string, string>>;
+  pages?: Readonly<Record<string, string>>;
+  templates?: Readonly<Record<string, string>>;
+};

package/src/design-system/defaults.ts

@@ -0,0 +1,3 @@
+export const buttonDefaultSize = 'default' as const
+export const buttonDefaultVariant = 'default' as const
+export const buttonGroupDefaultOrientation = 'horizontal' as const

package/src/design-system/index.ts

@@ -0,0 +1,29 @@
+export { designSystemCategories, designSystemComponents, getDesignSystemComponent } from "./component-registry";
+export { designSystemBlocks, getDesignSystemBlock } from "./block-registry";
+export { designSystemPages, getDesignSystemPage } from "./page-registry";
+export { designSystemTemplates, getDesignSystemTemplate } from "./template-registry";
+export { designSystemManifest, getDesignSystemAsset, validateDesignSystemManifest } from "./agent-manifest";
+export {
+  createDesignSystemSelection,
+  defaultDesignSystemSelection,
+  resolveDesignSystemBlockVariant,
+  resolveDesignSystemComponentVariant,
+  resolveDesignSystemPageVariant,
+  resolveDesignSystemTemplateVariant,
+} from "./selection";
+export { buttonDefaultSize, buttonDefaultVariant, buttonGroupDefaultOrientation } from "./defaults";
+export { actionVariantByIntent, resolveActionVariant } from "./action-intents";
+export type { ActionIntent, ActionVariant } from "./action-intents";
+export type {
+  DesignSystemBlockDefinition,
+  DesignSystemAssetKind,
+  DesignSystemAssetManifest,
+  DesignSystemOwnership,
+  DesignSystemCategory,
+  DesignSystemComponentDefinition,
+  DesignSystemPageDefinition,
+  DesignSystemTemplateDefinition,
+  DesignSystemSelection,
+  DesignSystemSelectionInput,
+  DesignSystemVariantDefinition,
+} from "./contracts";

package/src/design-system/mcp-server.ts

@@ -0,0 +1,156 @@
+import {
+  createDesignSystemSelection,
+  resolveDesignSystemBlockVariant,
+  resolveDesignSystemComponentVariant,
+  resolveDesignSystemPageVariant,
+  resolveDesignSystemTemplateVariant,
+} from "./selection";
+import { designSystemManifest, getDesignSystemAsset } from "./agent-manifest";
+import type { DesignSystemAssetKind, DesignSystemSelectionInput } from "./contracts";
+
+const toolDefinitions = [
+  {
+    name: "ui.list_assets",
+    description: "List package-owned UI assets that can be composed by an application.",
+    inputSchema: { type: "object", properties: { kind: { type: "string" }, query: { type: "string" } } },
+  },
+  {
+    name: "ui.get_asset",
+    description: "Return the complete contract for one UI component, block, page, or template.",
+    inputSchema: { type: "object", required: ["id"], properties: { id: { type: "string" }, kind: { type: "string" } } },
+  },
+  {
+    name: "ui.resolve_variant",
+    description: "Resolve and validate one asset variant before generating application code.",
+    inputSchema: {
+      type: "object",
+      required: ["kind", "id"],
+      properties: { kind: { type: "string" }, id: { type: "string" }, variantId: { type: "string" } },
+    },
+  },
+  {
+    name: "ui.validate_selection",
+    description: "Validate package UI selections and reject unknown assets or variants.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        blocks: { type: "object" },
+        components: { type: "object" },
+        pages: { type: "object" },
+        templates: { type: "object" },
+      },
+    },
+  },
+];
+
+export async function handleUiMcpRequest(request: JsonRpcRequest): Promise<JsonRpcResponse | null> {
+  const id = request.id ?? null;
+  if (request.method === "notifications/initialized") return null;
+  if (request.method === "initialize") {
+    return result(id, {
+      protocolVersion: "2025-03-26",
+      serverInfo: { name: "codexsun-ui", version: "1.0.43" },
+      capabilities: { tools: {}, resources: {} },
+    });
+  }
+  if (request.method === "tools/list") return result(id, { tools: toolDefinitions });
+  if (request.method === "resources/list") {
+    return result(id, {
+      resources: [{ uri: "ui://manifest", name: "CODEXSUN UI design-system manifest", mimeType: "application/json" }],
+    });
+  }
+  if (request.method === "resources/read") {
+    if (request.params?.uri === "ui://manifest") return result(id, resource("ui://manifest", designSystemManifest));
+    return error(id, -32004, "Unknown UI resource.");
+  }
+  if (request.method !== "tools/call") return error(id, -32601, "Method not found.");
+
+  try {
+    return result(id, {
+      content: [
+        { type: "text", text: JSON.stringify(callTool(request.params?.name, request.params?.arguments ?? {})) },
+      ],
+    });
+  } catch (cause) {
+    return error(id, -32002, cause instanceof Error ? cause.message : "UI contract validation failed.");
+  }
+}
+
+export async function startUiMcpServer() {
+  process.stdin.setEncoding("utf8");
+  let buffer = "";
+  for await (const chunk of process.stdin) {
+    buffer += chunk;
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines.filter(Boolean)) {
+      let response: JsonRpcResponse | null;
+      try {
+        response = await handleUiMcpRequest(JSON.parse(line) as JsonRpcRequest);
+      } catch {
+        response = error(null, -32700, "Invalid JSON.");
+      }
+      if (response) process.stdout.write(`${JSON.stringify(response)}\n`);
+    }
+  }
+}
+
+type JsonRpcRequest = {
+  id?: string | number | null;
+  method: string;
+  params?: { name?: string; arguments?: Record<string, unknown>; uri?: string };
+};
+type JsonRpcResponse = {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string };
+};
+
+function callTool(name: string | undefined, input: Record<string, unknown>) {
+  if (name === "ui.list_assets") {
+    const kind = typeof input.kind === "string" ? input.kind : undefined;
+    const query = typeof input.query === "string" ? input.query.toLowerCase() : undefined;
+    return designSystemManifest.filter(
+      (asset) =>
+        (!kind || asset.kind === kind) &&
+        (!query || `${asset.id} ${asset.name} ${asset.description}`.toLowerCase().includes(query)),
+    );
+  }
+  if (name === "ui.get_asset") {
+    const kind = typeof input.kind === "string" ? (input.kind as DesignSystemAssetKind) : undefined;
+    const asset = getDesignSystemAsset(String(input.id), kind);
+    if (!asset) throw new Error(`Unknown UI asset: ${String(input.id)}`);
+    return asset;
+  }
+  if (name === "ui.resolve_variant")
+    return resolveVariant(
+      String(input.kind),
+      String(input.id),
+      typeof input.variantId === "string" ? input.variantId : undefined,
+    );
+  if (name === "ui.validate_selection") return createDesignSystemSelection(input as DesignSystemSelectionInput);
+  throw new Error(`Unknown UI tool: ${String(name)}`);
+}
+
+function resolveVariant(kind: string, id: string, variantId?: string) {
+  if (kind === "component") return resolveDesignSystemComponentVariant(id, variantId);
+  if (kind === "block") return resolveDesignSystemBlockVariant(id, variantId);
+  if (kind === "page") return resolveDesignSystemPageVariant(id, variantId);
+  if (kind === "template") return resolveDesignSystemTemplateVariant(id, variantId);
+  throw new Error(`Unknown UI asset kind: ${kind}`);
+}
+
+function resource(uri: string, value: unknown) {
+  return { contents: [{ uri, mimeType: "application/json", text: JSON.stringify(value) }] };
+}
+
+function result(id: string | number | null, value: unknown): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, result: value };
+}
+
+function error(id: string | number | null, code: number, message: string): JsonRpcResponse {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+if (process.argv[1]?.endsWith("mcp-server.ts")) void startUiMcpServer();