@thorprovider/blocks 0.1.0

package/src/lib/contracts.ts

@@ -0,0 +1,235 @@
+import { z } from 'zod'
+import type { Money, PaymentMethod, ProductPreview } from '@thorprovider/types'
+
+/**
+ * Serialization contracts for spec-driven storefronts.
+ *
+ * These Zod schemas are the *serializable subset* of what a spec may write for
+ * a block. The component keeps its rich React interface; the catalog/registry
+ * is the adapter that maps these props to real component props and binds
+ * callbacks (see storefronts-on-blocks design D3). `z.infer` is the typed
+ * boundary between spec and catalog — a prop outside the schema is a compile
+ * error, not a runtime surprise.
+ *
+ * Data shapes are projections of the @thorprovider/types canon so that
+ * @thorprovider/adapters output validates without conflict:
+ * - Prices are plain numbers here while the canon `Money` is a decimal string
+ *   ({ amount: "45.00", currencyCode }). The projection happens at the
+ *   loader boundary.
+ * - Blocks use `title` while the canon `ProductPreview` uses `name`. Reconcile
+ *   via the canonical aliases below or the catalog/loader adapter.
+ */
+export type CanonMoney = Money
+export type CanonProduct = ProductPreview
+
+/**
+ * Fallback data-URI for required image fields when the data source has no
+ * image. Image fields are non-optional `z.string()` in these contracts, so the
+ * boundary must never emit `""` (React warns about `src=""`); it must emit a
+ * real, renderable value. Hosts may override with their own branded fallback
+ * (e.g. electrostore's `CATEGORY_IMAGE_FALLBACK`), but blocks ship a neutral
+ * one so direct consumers are safe by default.
+ */
+export const PRODUCT_IMAGE_FALLBACK =
+  'data:image/svg+xml;charset=utf-8,' +
+  encodeURIComponent(
+    `<svg xmlns='http://www.w3.org/2000/svg' width='600' height='600'><rect width='100%' height='100%' fill='#e2e8f0'/><g fill='none' stroke='#94a3b8' stroke-width='12' stroke-linecap='round'><path d='M150 300h300M300 150v300'/><path d='M220 230h50M220 300h50M220 370h50'/><path d='M330 230h50M330 300h50M330 370h50'/></g></svg>`,
+  )
+
+// ---------------------------------------------------------------------------
+// Data contracts
+// ---------------------------------------------------------------------------
+
+export const cardProductSchema = z.object({
+  id: z.union([z.string(), z.number()]),
+  title: z.string(),
+  price: z.number(),
+  originalPrice: z.number().optional(),
+  image: z.string(),
+  badge: z.string().optional(),
+})
+export type CardProduct = z.infer<typeof cardProductSchema>
+
+export const cartItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+  quantity: z.number().int().min(0),
+  image: z.string(),
+  variant: z.string().optional(),
+})
+export type CartItem = z.infer<typeof cartItemSchema>
+
+export const recentlyViewedItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  price: z.number(),
+  image: z.string(),
+})
+export type RecentlyViewedItem = z.infer<typeof recentlyViewedItemSchema>
+
+export const promotionSchema = z.object({
+  threshold: z.number(),
+  reward: z.string(),
+  icon: z.string().default('gift'),
+})
+export type Promotion = z.infer<typeof promotionSchema>
+
+const storeCategoryBase = {
+  label: z.string(),
+  href: z.string(),
+  emphasis: z.boolean().optional(),
+}
+
+export const storeCategorySchema: z.ZodType<StoreCategory> = z.lazy(() =>
+  z.object({
+    ...storeCategoryBase,
+    children: z.array(storeCategorySchema).optional(),
+  }),
+)
+export type StoreCategory = {
+  label: string
+  href: string
+  children?: StoreCategory[]
+  emphasis?: boolean
+}
+
+export const utilityLinkSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+})
+export type UtilityLink = z.infer<typeof utilityLinkSchema>
+
+export const navCartItemSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  variant: z.string(),
+  price: z.number(),
+  qty: z.number().int().min(0),
+  image: z.string(),
+})
+export type NavCartItem = z.infer<typeof navCartItemSchema>
+
+export const storeUserSchema = z.object({
+  name: z.string(),
+  email: z.string(),
+  avatar: z.string(),
+  initials: z.string(),
+})
+export type StoreUser = z.infer<typeof storeUserSchema>
+
+export const accountMenuItemSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+  description: z.string().optional(),
+  icon: z.enum(['orders', 'wishlist', 'addresses', 'settings']).optional(),
+})
+export type AccountMenuItem = z.infer<typeof accountMenuItemSchema>
+
+/**
+ * Serialization contract for a payment method offered at checkout.
+ *
+ * A projection of `@thorprovider/types` `PaymentMethod` — the storefront-facing
+ * shape produced by the adapters transform. Checkout blocks render the method
+ * list from this data instead of hardcoding providers.
+ */
+export const paymentMethodSchema: z.ZodType<PaymentMethod> = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.enum([
+    'card',
+    'wallet',
+    'bank_transfer',
+    'buy_now_pay_later',
+    'cash_on_delivery',
+    'crypto',
+    'other',
+  ]),
+  isEnabled: z.boolean(),
+  requiresSetup: z.boolean(),
+  description: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  features: z
+    .object({
+      saveForLater: z.boolean().optional(),
+      requires3DS: z.boolean().optional(),
+      supportsRefunds: z.boolean().optional(),
+      minAmount: z.number().optional(),
+      maxAmount: z.number().optional(),
+      supportedCurrencies: z.array(z.string()).optional(),
+      requiresVerification: z.boolean().optional(),
+    })
+    .optional(),
+  logo: z.string().optional(),
+})
+
+// ---------------------------------------------------------------------------
+// Block prop schemas
+// ---------------------------------------------------------------------------
+
+export const buttonPropsSchema = z.object({
+  variant: z
+    .enum(['default', 'destructive', 'outline', 'secondary', 'ghost', 'link'])
+    .optional(),
+  size: z
+    .enum(['default', 'xs', 'sm', 'lg', 'icon', 'icon-xs', 'icon-sm', 'icon-lg'])
+    .optional(),
+  disabled: z.boolean().optional(),
+  className: z.string().optional(),
+})
+export type ButtonSpecProps = z.infer<typeof buttonPropsSchema>
+
+export const storeContainer1PropsSchema = z.object({
+  size: z.enum(['default', 'narrow', 'wide', 'full']).optional(),
+  className: z.string().optional(),
+})
+export type StoreContainer1SpecProps = z.infer<typeof storeContainer1PropsSchema>
+
+export const productCard1PropsSchema = z.object({
+  products: z.array(cardProductSchema),
+  heading: z.string().optional(),
+  maxItems: z.number().int().positive().optional(),
+})
+export type ProductCard1SpecProps = z.infer<typeof productCard1PropsSchema>
+
+export const shoppingCart4PropsSchema = z.object({
+  items: z.array(cartItemSchema),
+  promotions: z.array(promotionSchema).default([]),
+  recentlyViewed: z.array(recentlyViewedItemSchema).optional(),
+  taxRate: z.number().optional(),
+  titleLabel: z.string().optional(),
+  subtotalLabel: z.string().optional(),
+  taxLabel: z.string().optional(),
+  shippingLabel: z.string().optional(),
+  shippingFreeLabel: z.string().optional(),
+  totalLabel: z.string().optional(),
+  awayFromLabel: z.string().optional(),
+  activatedLabel: z.string().optional(),
+  itemsLabel: z.string().optional(),
+  expressCheckoutLabel: z.string().optional(),
+  expressLabel: z.string().optional(),
+  standardLabel: z.string().optional(),
+  estimatedDeliveryLabel: z.string().optional(),
+  secureCheckoutLabel: z.string().optional(),
+  recentlyViewedLabel: z.string().optional(),
+  collapseLabel: z.string().optional(),
+  expandLabel: z.string().optional(),
+  checkoutLabel: z.string().optional(),
+  quickCheckoutLabel: z.string().optional(),
+  checkoutNowLabel: z.string().optional(),
+})
+export type ShoppingCart4SpecProps = z.infer<typeof shoppingCart4PropsSchema>
+
+export const navbar4PropsSchema = z.object({
+  storeCategories: z.array(storeCategorySchema),
+  shippingNote: z.string(),
+  utilityLinks: z.array(utilityLinkSchema),
+  logoText: z.string(),
+  logoHref: z.string().optional(),
+  accountHref: z.string().optional(),
+  searchQuery: z.string().optional(),
+  items: z.array(navCartItemSchema).optional(),
+  user: storeUserSchema.optional(),
+  accountMenuItems: z.array(accountMenuItemSchema).optional(),
+})
+export type Navbar4SpecProps = z.infer<typeof navbar4PropsSchema>

package/src/lib/types/menu.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+
+/**
+ * Canonical navigation types: recursive menu item and collection item.
+ *
+ * Ported from the legacy `@thorprovider/components` navigation library
+ * (source: branch `feat/storefronts`) into the blocks catalog so any
+ * consumer can feed a multi-level category tree to the navigation blocks.
+ */
+
+export const menuItemSchema: z.ZodType<{
+  id: string
+  label: string
+  icon?: string
+  image?: string
+  href?: string
+  badge?: string
+  featured?: boolean
+  children?: MenuItem[]
+}> = z.lazy(() =>
+  z.object({
+    id: z.string(),
+    label: z.string(),
+    icon: z.string().optional(),
+    image: z.string().optional(),
+    href: z.string().optional(),
+    badge: z.string().optional(),
+    featured: z.boolean().optional(),
+    children: z.array(menuItemSchema).optional(),
+  }),
+)
+
+export type MenuItem = z.infer<typeof menuItemSchema>
+
+export const collectionItemSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  description: z.string().optional(),
+  image: z.string().optional(),
+  href: z.string().optional(),
+})
+
+export type CollectionItem = z.infer<typeof collectionItemSchema>

package/src/lib/types.ts

@@ -0,0 +1,4 @@
+export interface CTA {
+  label: string
+  href?: string
+}

package/src/lib/utils.ts

@@ -0,0 +1,10 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/**
+ * Merge Tailwind CSS class names safely.
+ * Deduplicates conflicting utilities (e.g. `p-4` vs `p-2` → keeps last).
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/ui/accordion.tsx

@@ -0,0 +1,65 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "cn"
+import { ChevronDownIcon } from "lucide-react"
+import { Accordion as AccordionPrimitive } from "radix-ui"
+
+function Accordion({
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Root>) {
+  return <AccordionPrimitive.Root data-slot="accordion" {...props} />
+}
+
+function AccordionItem({
+  className,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Item>) {
+  return (
+    <AccordionPrimitive.Item
+      data-slot="accordion-item"
+      className={cn("border-b last:border-b-0", className)}
+      {...props}
+    />
+  )
+}
+
+function AccordionTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Trigger>) {
+  return (
+    <AccordionPrimitive.Header className="flex">
+      <AccordionPrimitive.Trigger
+        data-slot="accordion-trigger"
+        className={cn(
+          "flex flex-1 items-start justify-between gap-4 rounded-md py-4 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <ChevronDownIcon className="pointer-events-none size-4 shrink-0 translate-y-0.5 text-muted-foreground transition-transform duration-200" />
+      </AccordionPrimitive.Trigger>
+    </AccordionPrimitive.Header>
+  )
+}
+
+function AccordionContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof AccordionPrimitive.Content>) {
+  return (
+    <AccordionPrimitive.Content
+      data-slot="accordion-content"
+      className="overflow-hidden text-sm data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down"
+      {...props}
+    >
+      <div className={cn("pt-0 pb-4", className)}>{children}</div>
+    </AccordionPrimitive.Content>
+  )
+}
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }

package/src/ui/avatar.tsx

@@ -0,0 +1,108 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "cn"
+import { Avatar as AvatarPrimitive } from "radix-ui"
+
+function Avatar({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Root> & {
+  size?: "default" | "sm" | "lg"
+}) {
+  return (
+    <AvatarPrimitive.Root
+      data-slot="avatar"
+      data-size={size}
+      className={cn(
+        "group/avatar relative flex size-8 shrink-0 overflow-hidden rounded-full select-none data-[size=lg]:size-10 data-[size=sm]:size-6",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarImage({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Image>) {
+  return (
+    <AvatarPrimitive.Image
+      data-slot="avatar-image"
+      className={cn("aspect-square size-full", className)}
+      {...props}
+    />
+  )
+}
+
+function AvatarFallback({
+  className,
+  ...props
+}: React.ComponentProps<typeof AvatarPrimitive.Fallback>) {
+  return (
+    <AvatarPrimitive.Fallback
+      data-slot="avatar-fallback"
+      className={cn(
+        "flex size-full items-center justify-center rounded-full bg-muted text-sm text-muted-foreground group-data-[size=sm]/avatar:text-xs",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarBadge({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="avatar-badge"
+      className={cn(
+        "absolute right-0 bottom-0 z-10 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground ring-2 ring-background select-none",
+        "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden",
+        "group-data-[size=default]/avatar:size-2.5 group-data-[size=default]/avatar:[&>svg]:size-2",
+        "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="avatar-group"
+      className={cn(
+        "group/avatar-group flex -space-x-2 *:data-[slot=avatar]:ring-2 *:data-[slot=avatar]:ring-background",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AvatarGroupCount({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="avatar-group-count"
+      className={cn(
+        "relative flex size-8 shrink-0 items-center justify-center rounded-full bg-muted text-sm text-muted-foreground ring-2 ring-background group-has-data-[size=lg]/avatar-group:size-10 group-has-data-[size=sm]/avatar-group:size-6 [&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 group-has-data-[size=sm]/avatar-group:[&>svg]:size-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+  AvatarBadge,
+  AvatarGroup,
+  AvatarGroupCount,
+}

package/src/ui/badge.tsx

@@ -0,0 +1,47 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "cn"
+import { Slot } from "radix-ui"
+
+const badgeVariants = cva(
+  "inline-flex w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&>svg]:pointer-events-none [&>svg]:size-3",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground [a&]:hover:bg-primary/90",
+        secondary:
+          "bg-secondary text-secondary-foreground [a&]:hover:bg-secondary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40 [a&]:hover:bg-destructive/90",
+        outline:
+          "border-border text-foreground [a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
+        ghost: "[a&]:hover:bg-accent [a&]:hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 [a&]:hover:underline",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function Badge({
+  className,
+  variant = "default",
+  asChild = false,
+  ...props
+}: React.ComponentProps<"span"> &
+  VariantProps<typeof badgeVariants> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot.Root : "span"
+
+  return (
+    <Comp
+      data-slot="badge"
+      data-variant={variant}
+      className={cn(badgeVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+export { Badge, badgeVariants }

package/src/ui/breadcrumb.tsx

@@ -0,0 +1,108 @@
+import * as React from "react"
+import { cn } from "cn"
+import { ChevronRight, MoreHorizontal } from "lucide-react"
+import { Slot } from "radix-ui"
+
+function Breadcrumb({ ...props }: React.ComponentProps<"nav">) {
+  return <nav aria-label="breadcrumb" data-slot="breadcrumb" {...props} />
+}
+
+function BreadcrumbList({ className, ...props }: React.ComponentProps<"ol">) {
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      className={cn(
+        "flex flex-wrap items-center gap-1.5 text-sm break-words text-muted-foreground sm:gap-2.5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      className={cn("inline-flex items-center gap-1.5", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbLink({
+  asChild,
+  className,
+  ...props
+}: React.ComponentProps<"a"> & {
+  asChild?: boolean
+}) {
+  const Comp = asChild ? Slot.Root : "a"
+
+  return (
+    <Comp
+      data-slot="breadcrumb-link"
+      className={cn("transition-colors hover:text-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbPage({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-page"
+      role="link"
+      aria-disabled="true"
+      aria-current="page"
+      className={cn("font-normal text-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function BreadcrumbSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn("[&>svg]:size-3.5", className)}
+      {...props}
+    >
+      {children ?? <ChevronRight />}
+    </li>
+  )
+}
+
+function BreadcrumbEllipsis({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="breadcrumb-ellipsis"
+      role="presentation"
+      aria-hidden="true"
+      className={cn("flex size-9 items-center justify-center", className)}
+      {...props}
+    >
+      <MoreHorizontal className="size-4" />
+      <span className="sr-only">More</span>
+    </span>
+  )
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+}