@deneb-ui/ui

v2.0.94

Published

17 minutes ago

Visual-first React component library for editable commerce storefronts. Built for Next.js and Fivora.

Getting Started

Installation

npm install @deneb-ui/ui
# or
pnpm add @deneb-ui/ui
# or
yarn add @deneb-ui/ui

Quick Start Example

import { 
  SiteDataProvider, 
  Navbar, 
  Hero, 
  GoogleFeedback, 
  TestimonialSection, 
  Map, 
  Footer 
} from "@deneb-ui/ui";
import siteData from "@/data/site-data.json";

export default function Page() {
  return (
    <SiteDataProvider initialSiteData={siteData}>
      <Navbar />
      <Hero />
      <GoogleFeedback basePath="feedback" />
      <TestimonialSection basePath="testimonials" />
      <div className="w-full h-96 rounded-2xl overflow-hidden shadow-lg">
        <Map mapUrl={siteData.content.contact?.mapUrl} />
      </div>
      <Footer />
    </SiteDataProvider>
  );
}

SiteDataProvider automatically injects ResponsiveBaseStyles — every component adapts seamlessly across phone, tablet, and desktop without extra configuration.

Canonical Component Catalog & Aliases

@deneb-ui/ui provides both canonical shorthand aliases (shadcn / HeroUI style) and full Editable* identifiers across all commerce categories:

1. Foundational & Layout Primitives

2. Commerce & Storefront Components

3. Hero & Marketing Sections

4. Social Proof & Customer Reviews

5. Services, Pricing & Navigation

6. Smart Actions, Location & Business

7. Runtime State & Theming Primitives

| Component / Hook | Module Path | Purpose | | :--- | :--- | :--- | | SiteDataProvider / DenebDataProvider | SiteDataProvider | Real-time backend catalog fetcher & postMessage preview state synchronizer | | useProducts | SiteDataProvider | React hook to access live synchronized products list (content.products) | | usePlatformProductDetail | PlatformProductDetail | Resolves ?id= against live data and the catalog API for a custom detail design | | useServices | SiteDataProvider | React hook to access live synchronized services list (content.services) | | useSiteCatalog | SiteDataProvider | Returns { products, services, project, siteInstance, api } in one call | | useSiteApi | SiteDataProvider | Returns official Fivora backend endpoints (catalogUrl, contactUrl, analyticsUrl) | | useSiteData / useDenebData | SiteDataProvider | React hook to access full live synchronized siteData | | ThemeStyles | ThemeStyles | Dynamic CSS variable injector for colors, fonts, and radii | | ResponsiveBaseStyles| ResponsiveBaseStyles | Universal fluid typography & responsive baseline styles | | DenebComponentStyles| DenebComponentStyles | Scoped component style definitions | | FontLoader | fonts/FontLoader | Google Fonts pre-fetch & dynamic injection engine | | useDenebFonts | fonts/useDenebFonts | Hook for checking active font definitions | | CartProvider / useCart| cart/useCart | Global cart state management with persistent storage |

Safe product detail routes for static exports

Never link live products to /products/${product.id}. A product created after the template build has no matching static directory, so that URL can return a 404. Export one stable page and pass the product ID in the query string.

// src/app/products/detail/page.tsx
import { PlatformProductDetail } from '@deneb-ui/ui';

export default function ProductDetailPage() {
  return <PlatformProductDetail />;
}

Build product links with the matching helper:

import { platformProductDetailHref } from '@deneb-ui/ui';

<a href={platformProductDetailHref(product.id)}>View product</a>

For a template-specific design, keep the platform data behavior and replace only the renderer:

import { PlatformProductDetail } from '@deneb-ui/ui';

export default function ProductDetailPage() {
  return (
    <PlatformProductDetail
      renderProduct={(product, { productIndex }) => (
        <MyProductDetail product={product} index={productIndex} />
      )}
    />
  );
}

PlatformProductDetail reads /products/detail/?id=PRODUCT_ID, checks the reactive SiteDataProvider catalog, retries api.catalogUrl, and renders safe loading, network-error, and not-found states. usePlatformProductDetail() is also exported for developers who need complete control of the page markup.

If the template already has a native /products/[id] design, the stable page must reuse that renderer through renderProduct (or render the same component from usePlatformProductDetail). The validator rejects a generic stable page next to a different native detail layout because newly-created products would otherwise look different from products present at build time.

Data Fetching & Backend Integration Hooks

1. `useProducts(fallback?: ProductItem[])`

Retrieves the live products list from the site data. Automatically resolves top-level content.products, nested content.home.products, and live backend rehydration updates from api.catalogUrl.

import { useProducts, ProductGrid } from '@deneb-ui/ui';

export default function CatalogSection() {
  const products = useProducts();

  return (
    <ProductGrid
      title="Featured Collection"
      subtitle="Handpicked Styles"
      products={products}
      categories={['All', 'Accessories', 'Apparel']}
      cardVariant="modern-glass" // 'modern-glass' | 'classic' | 'minimal' | 'horizontal'
      columns={{ mobile: 1, tablet: 2, desktop: 3 }}
    />
  );
}

2. `useSiteApi()`

Returns the official backend API configuration object (SiteDataApiConfig) defined in site-data.json. Use this hook whenever you need to connect custom forms or direct API calls to the backend:

import { useSiteApi } from '@deneb-ui/ui';

export default function ApiDemo() {
  const api = useSiteApi();

  // api?.baseUrl      -> "https://api.fivora.site"
  // api?.catalogUrl   -> "https://api.fivora.site/site-catalog/:slug/live-data"
  // api?.contactUrl   -> "https://api.fivora.site/site-contact"
  // api?.analyticsUrl -> "https://api.fivora.site/site-analytics/page-view"
  
  return null;
}

3. `useSiteCatalog()`

Convenience hook that bundles catalog metadata and live status together:

import { useSiteCatalog } from '@deneb-ui/ui';

export default function CatalogOverview() {
  const { products, services, project, siteInstance, api } = useSiteCatalog();

  return (
    <div>
      <h3>{project?.title}</h3>
      <p>Active live products: {products.length}</p>
      <p>Active live services: {services.length}</p>
    </div>
  );
}

4. `useServices(fallback?: ServiceItem[])`

Retrieves the live services list from content.services or content.home.services:

import { useServices, ServiceCard } from '@deneb-ui/ui';

export default function ServicesList() {
  const services = useServices();

  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
      {services.map((service, index) => (
        <ServiceCard
          key={service.id || index}
          itemPath={`services[${index}]`}
          service={service}
        />
      ))}
    </div>
  );
}

Component Guides & API Reference

1. `GoogleFeedback` (`EditableGoogleFeedback`)

The GoogleFeedback component renders an authentic Google Reviews card experience. It features the official Google multi-colored badge, aggregate rating pill, verified buyer checks, and a responsive grid of customer reviews.

Key Capabilities

Google Design Fidelity: Uses Google Material star vectors with authentic warm gold (#fa7014) and neutral grey (#dadce0).
Live 1–5 Star DOM Sync: Typing numbers 1 through 5 into the Fivora live inspector immediately recalculates and repaints the star fills in real time via an internal MutationObserver.
Zero-Latency Visual Editing: Built-in data-preview-field-path and data-preview-list-path attributes compliant with the Fivora Strict Visual Editing Contract.
Auto-Fallbacks: Provides elegant fallback review data if no feedbacks array is passed.

Props Reference

`FeedbackItem` Schema

export interface FeedbackItem {
  id?: string | number;
  name?: string;              // Reviewer full name
  avatar?: string;            // Avatar image URL
  rating?: number | string;   // Star rating value (1 to 5)
  date?: string;              // Relative date (e.g. "2 days ago")
  comment?: string;           // Review body text
  verified?: boolean;         // Verified customer badge
}

Fivora Data Contract (`site-data.json`)

{
  "content": {
    "feedback": {
      "badgeIcon": "https://upload.wikimedia.org/wikipedia/commons/c/c1/Google_%22G%22_logo.svg",
      "badgeTitle": "Google",
      "badgeRating": "4.9",
      "badgeReviewsCount": "128 reviews",
      "heading": "Loved by Coffee Lovers Across the World",
      "subheading": "Real stories and reviews from our community of coffee purists and daily ritualists.",
      "feedbacks": [
        {
          "id": "1",
          "name": "Elena Vance",
          "avatar": "https://images.unsplash.com/photo-1534528741775-53994a69daeb",
          "rating": 5,
          "date": "3 days ago",
          "comment": "The Yirgacheffe pour-over is unmatched. Clean notes of jasmine and bergamot.",
          "verified": true
        }
      ]
    }
  }
}

Fivora `editorSchema` Section

{
  "id": "feedback",
  "path": "feedback",
  "type": "object",
  "label": "Google Customer Feedback",
  "pageKey": "home",
  "fields": [
    { "key": "badgeIcon", "type": "image", "label": "Badge Icon URL" },
    { "key": "badgeTitle", "type": "text", "label": "Badge Title" },
    { "key": "badgeRating", "type": "text", "label": "Aggregate Rating" },
    { "key": "badgeReviewsCount", "type": "text", "label": "Reviews Count" },
    { "key": "heading", "type": "text", "label": "Section Heading" },
    { "key": "subheading", "type": "textarea", "label": "Section Subheading" },
    {
      "key": "feedbacks",
      "type": "list",
      "label": "Customer Reviews",
      "itemLabel": "Review",
      "minItems": 1,
      "maxItems": 12,
      "fields": [
        { "key": "name", "type": "text", "label": "Reviewer Name", "required": true },
        { "key": "avatar", "type": "image", "label": "Profile Picture" },
        { "key": "rating", "type": "number", "label": "Star Rating (1-5)" },
        { "key": "date", "type": "text", "label": "Review Date" },
        { "key": "comment", "type": "textarea", "label": "Review Comment", "required": true }
      ]
    }
  ]
}

Usage Example

import { GoogleFeedback, useSiteData } from "@deneb-ui/ui";

export function FeedbackSection() {
  const { siteData } = useSiteData();
  const feedbackData = siteData?.content?.feedback || {};

  return (
    <section className="py-20 bg-amber-50/40">
      <GoogleFeedback
        basePath="feedback"
        badgeIcon={feedbackData.badgeIcon}
        badgeTitle={feedbackData.badgeTitle}
        badgeRating={feedbackData.badgeRating}
        badgeReviewsCount={feedbackData.badgeReviewsCount}
        heading={feedbackData.heading}
        subheading={feedbackData.subheading}
        feedbacks={feedbackData.feedbacks}
      />
    </section>
  );
}

2. `TestimonialSection` (`EditableTestimonialSection`)

The TestimonialSection component provides an editorial, magazine-grade layout for connoisseur quotes, culinary critics, and press reviews.

Key Capabilities

Editorial Typography: Large quotation marks, serif italic styling, and prominent author metadata.
Accreditation Tags: Includes specialty tags (e.g. "Michelin Guide", "World Barista Judge").
Synchronized Star Ratings: Dynamic star rating with live inspector sync.
Clean Layout: Fluid responsive grid adapting from 1 column on mobile to 3 columns on desktop.

Props Reference

`TestimonialSectionItem` Schema

export interface TestimonialSectionItem {
  id?: string | number;
  quote?: string;             // Testimonial quote text
  author?: string;            // Author full name
  role?: string;              // Profession, publication, or title
  avatar?: string;            // Author portrait URL
  tag?: string;               // Category or accreditation badge
  rating?: number | string;   // Star rating (1 to 5)
}

Usage Example

import { TestimonialSection, useSiteData } from "@deneb-ui/ui";

export function EditorialReviews() {
  const { siteData } = useSiteData();
  const data = siteData?.content?.testimonials || {};

  return (
    <TestimonialSection
      basePath="testimonials"
      badge={data.badge}
      heading={data.heading}
      subheading={data.subheading}
      testimonials={data.testimonials}
    />
  );
}

3. `Map` (`EditableMap`)

The Map component is an intelligent universal Google Maps embedder. It converts any format of Google Maps URL or search query into a high-performance, responsive iframe embed.

Universal Link Parser Features

The underlying parseGoogleMapsEmbedUrl engine seamlessly processes:

Full <iframe> Snippets: Extracts the src attribute automatically when developers or merchants paste standard Google Maps embed HTML.
Standard Embed URLs: Passes through existing google.com/maps/embed?... URLs directly.
Coordinate URLs: Parses @lat,lng patterns (e.g. google.com/maps/@6.9271,79.8612,15z).
Place URLs: Extracts place names from /maps/place/Name paths.
Search Query URLs: Parses ?q=... parameters.
Short Links: Handles maps.app.goo.gl links with automatic fallback to merchant address.
Raw Search Strings: Directly wraps street addresses or city names into valid Google Maps embed queries.

Props Reference

Usage Example

import { Map } from "@deneb-ui/ui";

export function ContactMapSection({ mapUrl, address }: { mapUrl?: string; address?: string }) {
  return (
    <div className="w-full h-96 sm:h-[480px] rounded-3xl overflow-hidden shadow-2xl border border-stone-200">
      <Map
        data-preview-field-path="contact.mapUrl"
        mapUrl={mapUrl}
        address={address}
        className="w-full h-full border-0"
      />
    </div>
  );
}

ARC Engine & Fivora Platform Architecture

@deneb-ui/ui is built from the ground up for the ARC Engine (@deneb-ui/cli) and the Fivora Visual Commerce Platform.

┌─────────────────────────────────────────────────────────────┐
│                    Fivora Admin Portal                      │
│                  (Inspector / Live Studio)                  │
└──────────────────────────────┬──────────────────────────────┘
                               │ Live PostMessage Protocol
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                  Fivora Preview Focus Bridge                │
│    - Focus Target Identification (data-preview-field-path)  │
│    - Fast DOM Mutation & Star Fill Repainting               │
└──────────────────────────────┬──────────────────────────────┘
                               │ Instant DOM / Observer Sync
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                       DENEB UI                              │
│    - GoogleFeedback (MutationObserver Dual-Layer Rating)    │
│    - TestimonialSection (Editorial Critic Cards)            │
│    - EditableMap (Universal URL Parsing Engine)             │
└─────────────────────────────────────────────────────────────┘

Dual-Layer Live Rating Architecture

When editing ratings in visual site builders, updating an element's text content usually destroys child SVG icons. DENEB UI solves this through a dual-layer architecture:

Inspector Target: A dedicated <span data-preview-field-path="..."> renders the numeric string (e.g. "5").
Visual Star Array: A sibling <div data-fivora-stars-row="true"> contains the 5 vector SVG stars with fill colors #fa7014 (gold) and #dadce0 (grey).
MutationObserver: An internal observer listens for inspector text mutations on the numeric span and immediately updates the SVG star fills without remounting or re-rendering errors.
Focus Bridge Support: The CLI preview bridge recognizes star rating containers and synchronizes fills directly during live keystrokes.

ARC Engine Automated Scaffolding

When running the ARC Engine:

npx @deneb-ui/cli arc init

The engine automatically:

Identifies GoogleFeedback, TestimonialSection, and Map components.
Creates semantic field paths (feedback.feedbacks, testimonials.testimonials, contact.mapUrl).
Generates typed editorSchema sections with proper numeric, image, and textarea descriptors.
Adds non-editable internal IDs to visualEditing.controlOnlyPaths to guarantee 100% contract compliance with Fivora platform ingestion.

Related Packages

Authors

Created and maintained by Chamika Gayashan and Induranga Kawishwara.

Part of the DENEB UI ecosystem · In collaboration with Fivora.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Getting Started

Installation

Quick Start Example

Canonical Component Catalog & Aliases

1. Foundational & Layout Primitives

2. Commerce & Storefront Components

3. Hero & Marketing Sections

4. Social Proof & Customer Reviews

5. Services, Pricing & Navigation

6. Smart Actions, Location & Business

7. Runtime State & Theming Primitives

Safe product detail routes for static exports

Data Fetching & Backend Integration Hooks

1. useProducts(fallback?: ProductItem[])

2. useSiteApi()

3. useSiteCatalog()

4. useServices(fallback?: ServiceItem[])

Component Guides & API Reference

1. GoogleFeedback (EditableGoogleFeedback)

Key Capabilities

Props Reference

FeedbackItem Schema

Fivora Data Contract (site-data.json)

Fivora editorSchema Section

Usage Example

2. TestimonialSection (EditableTestimonialSection)

Key Capabilities

Props Reference

TestimonialSectionItem Schema

Usage Example

3. Map (EditableMap)

Universal Link Parser Features

Props Reference

Usage Example

ARC Engine & Fivora Platform Architecture

Dual-Layer Live Rating Architecture

ARC Engine Automated Scaffolding

Related Packages

Authors

1. `useProducts(fallback?: ProductItem[])`

2. `useSiteApi()`

3. `useSiteCatalog()`

4. `useServices(fallback?: ServiceItem[])`

1. `GoogleFeedback` (`EditableGoogleFeedback`)

`FeedbackItem` Schema

Fivora Data Contract (`site-data.json`)

Fivora `editorSchema` Section

2. `TestimonialSection` (`EditableTestimonialSection`)

`TestimonialSectionItem` Schema

3. `Map` (`EditableMap`)