@akinon/projectzero 2.0.0-beta.19 → 2.0.0-beta.20

package/app-template/src/views/breadcrumb/breadcrumb-client.tsx

@@ -0,0 +1,190 @@
+'use client';
+
+import { Fragment, CSSProperties } from 'react';
+import { Icon, Link } from '@theme/components';
+import { ROUTES } from '@theme/routes';
+import { useLocalization } from '@akinon/next/hooks';
+import { BreadcrumbResultType } from '@akinon/next/types';
+import { capitalize } from '@akinon/next/utils';
+import BreadcrumbRegistrar, { useBreadcrumb } from './breadcrumb-registrar';
+import {
+  BREADCRUMB_SECTION_ID,
+  BREADCRUMB_PLACEHOLDER_ID,
+  BreadcrumbProperties
+} from './constants';
+
+export interface BreadcrumbClientProps {
+  breadcrumbList?: BreadcrumbResultType[];
+  initialSettings?: {
+    sectionStyles?: Record<string, unknown>;
+    properties?: BreadcrumbProperties;
+  };
+}
+
+/**
+ * Breadcrumb Client Component
+ *
+ * Displays a breadcrumb navigation with customizable styles via Theme Editor.
+ * Wraps content with BreadcrumbRegistrar for native widget support.
+ */
+export default function BreadcrumbClient(props: BreadcrumbClientProps) {
+  return (
+    <BreadcrumbRegistrar initialSettings={props.initialSettings}>
+      <BreadcrumbContent breadcrumbList={props.breadcrumbList} />
+    </BreadcrumbRegistrar>
+  );
+}
+
+function BreadcrumbContent(props: { breadcrumbList?: BreadcrumbResultType[] }) {
+  const { t, locale } = useLocalization();
+  const { breadcrumbList = [] } = props;
+  const { sectionStyles, properties, isBreadcrumbSectionSelected, isDesigner } =
+    useBreadcrumb();
+
+  // Handle click in designer mode - select section instead of navigating
+  const handleDesignerClick = (e: React.MouseEvent) => {
+    if (!isDesigner) return;
+    e.preventDefault();
+    e.stopPropagation();
+    window.parent?.postMessage(
+      {
+        type: 'SELECT_SECTION',
+        data: {
+          placeholderId: BREADCRUMB_PLACEHOLDER_ID,
+          sectionId: BREADCRUMB_SECTION_ID
+        }
+      },
+      '*'
+    );
+  };
+
+  const list = [
+    { url: ROUTES.HOME, text: t('common.breadcrumb.homepage') },
+    ...breadcrumbList.map((breadcrumb) => ({
+      url: breadcrumb.url,
+      text: breadcrumb.label
+    }))
+  ];
+
+  // Helper to format style value with unit if needed
+  const formatStyleValue = (
+    value: unknown,
+    unit = 'px'
+  ): string | undefined => {
+    if (value === undefined || value === null || value === '') return undefined;
+    // If already has unit (string like '17px'), return as is
+    if (typeof value === 'string' && value.includes(unit)) return value;
+    // If number or numeric string, add unit
+    return `${value}${unit}`;
+  };
+
+  // Build CSS styles from section styles
+  const containerStyles: CSSProperties = {
+    fontSize: formatStyleValue(sectionStyles['font-size']),
+    fontWeight: sectionStyles['font-weight'] as CSSProperties['fontWeight'],
+    color: sectionStyles['color'] as string,
+    gap: formatStyleValue(sectionStyles['gap']),
+    paddingTop: formatStyleValue(sectionStyles['padding-top']),
+    paddingRight: formatStyleValue(sectionStyles['padding-right']),
+    paddingBottom: formatStyleValue(sectionStyles['padding-bottom']),
+    paddingLeft: formatStyleValue(sectionStyles['padding-left']),
+    backgroundColor: sectionStyles['background-color'] as string,
+    borderRadius: formatStyleValue(sectionStyles['border-radius'])
+  };
+
+  // Link styles
+  const linkStyles: CSSProperties = {
+    color: sectionStyles['link-color'] as string,
+    textDecoration: sectionStyles['link-text-decoration'] as string
+  };
+
+  // Separator styles
+  const separatorStyles: CSSProperties = {
+    color: sectionStyles['separator-color'] as string
+  };
+
+  // Separator icon from properties
+  const separatorIcon = (properties.separatorIcon as string) || 'chevron-end';
+
+  // Extract numeric value from separator-icon-size (may come as '10px' or 10)
+  const separatorIconSizeRaw = sectionStyles['separator-icon-size'];
+  const separatorIconSize =
+    typeof separatorIconSizeRaw === 'string'
+      ? parseInt(separatorIconSizeRaw.replace(/[^0-9]/g, ''), 10) || 8
+      : Number(separatorIconSizeRaw) || 8;
+
+  // Home icon settings
+  const showHomeIcon = properties.showHomeIcon ?? false;
+
+  // Render separator based on type
+  const renderSeparator = () => {
+    const separatorStyle: CSSProperties = {
+      ...separatorStyles,
+      fontSize: `${separatorIconSize}px`,
+      lineHeight: 1,
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center'
+    };
+
+    // Text-based separators
+    if (separatorIcon === 'slash') {
+      return <span style={separatorStyle}>/</span>;
+    }
+    if (separatorIcon === 'dot') {
+      return <span style={separatorStyle}>•</span>;
+    }
+
+    // Icon-based separators
+    return (
+      <span
+        style={{
+          display: 'var(--theme-breadcrumb-icon-display, inline-flex)',
+          ...separatorStyles
+        }}
+      >
+        <Icon name={separatorIcon} size={separatorIconSize} />
+      </span>
+    );
+  };
+
+  return (
+    <div
+      data-section-id={BREADCRUMB_SECTION_ID}
+      className="flex items-center leading-4"
+      onClick={handleDesignerClick}
+      style={{
+        fontSize: containerStyles.fontSize || '12px',
+        gap: containerStyles.gap || '12px',
+        fontWeight: containerStyles.fontWeight,
+        color: containerStyles.color,
+        paddingTop: containerStyles.paddingTop,
+        paddingRight: containerStyles.paddingRight,
+        paddingBottom: containerStyles.paddingBottom,
+        paddingLeft: containerStyles.paddingLeft,
+        backgroundColor: containerStyles.backgroundColor,
+        borderRadius: containerStyles.borderRadius,
+        outline: isBreadcrumbSectionSelected ? '2px solid #3b82f6' : undefined,
+        outlineOffset: isBreadcrumbSectionSelected ? '-2px' : undefined,
+        cursor: isDesigner ? 'pointer' : undefined
+      }}
+    >
+      {list.map((item, index) => (
+        <Fragment key={index}>
+          {index === 0 && showHomeIcon ? (
+            <Link href={item.url} style={linkStyles}>
+              <Icon name="home" size={14} />
+            </Link>
+          ) : (
+            <Link href={item.url} style={linkStyles}>
+              {capitalize(item.text.toLocaleLowerCase(locale))}
+            </Link>
+          )}
+          {index !== list.length - 1 && renderSeparator()}
+        </Fragment>
+      ))}
+    </div>
+  );
+}
+
+export { BreadcrumbRegistrar, useBreadcrumb };

package/app-template/src/views/breadcrumb/breadcrumb-registrar.tsx

@@ -0,0 +1,286 @@
+'use client';
+
+/**
+ * Breadcrumb Section Registrar
+ *
+ * This component registers the "Breadcrumb" section as a native widget.
+ * The breadcrumb section allows customization of styles and appearance
+ * via the Theme Editor on list and product detail pages.
+ */
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  PropsWithChildren
+} from 'react';
+import {
+  registerPlaceholder,
+  unregisterPlaceholder
+} from '@akinon/next/components/theme-editor/placeholder-registry';
+import {
+  BREADCRUMB_PLACEHOLDER_ID,
+  BREADCRUMB_SECTION_ID,
+  BreadcrumbProperties
+} from './constants';
+
+// Re-export constants for external use
+export {
+  BREADCRUMB_PLACEHOLDER_ID,
+  BREADCRUMB_SECTION_ID,
+  BREADCRUMB_WIDGET_SLUG
+} from './constants';
+export type { BreadcrumbProperties } from './constants';
+
+// Global flag to track if registration has been done
+declare global {
+  interface Window {
+    __breadcrumbRegistered?: boolean;
+  }
+}
+
+/**
+ * Check if running inside designer iframe
+ */
+function isInDesignerMode(): boolean {
+  if (typeof window === 'undefined') return false;
+  return window.self !== window.top;
+}
+
+interface ThemeSection {
+  id: string;
+  visible?: boolean;
+  properties?: Record<string, unknown>;
+  styles?: Record<string, unknown>;
+}
+
+interface ThemePlaceholder {
+  slug: string;
+  sections: ThemeSection[];
+}
+
+interface BreadcrumbContextValue {
+  isDesigner: boolean;
+  isBreadcrumbSectionSelected: boolean;
+  properties: BreadcrumbProperties;
+  sectionStyles: Record<string, unknown>;
+}
+
+const BreadcrumbContext = createContext<BreadcrumbContextValue>({
+  isDesigner: false,
+  isBreadcrumbSectionSelected: false,
+  properties: {
+    separatorIcon: 'chevron-end',
+    showHomeIcon: false
+  },
+  sectionStyles: {}
+});
+
+export const useBreadcrumb = () => useContext(BreadcrumbContext);
+
+interface BreadcrumbRegistrarProps extends PropsWithChildren {
+  /**
+   * Initial settings from server-side parsing (to avoid flash)
+   */
+  initialSettings?: {
+    sectionStyles?: Record<string, unknown>;
+    properties?: BreadcrumbProperties;
+  };
+}
+
+/**
+ * BreadcrumbRegistrar
+ *
+ * Registers the Breadcrumb native section with Theme Editor.
+ * This section allows customizing breadcrumb appearance including
+ * font size, color, separator icon, spacing, etc.
+ */
+export default function BreadcrumbRegistrar({
+  children,
+  initialSettings = {}
+}: BreadcrumbRegistrarProps) {
+  const isDesignerRef = useRef(false);
+  const [sectionProperties, setSectionProperties] =
+    useState<BreadcrumbProperties>(
+      initialSettings.properties || {
+        separatorIcon: 'chevron-end',
+        showHomeIcon: false
+      }
+    );
+  const [sectionStyles, setSectionStyles] = useState<Record<string, unknown>>(
+    initialSettings.sectionStyles || {}
+  );
+  const [isBreadcrumbSelected, setIsBreadcrumbSelected] = useState(false);
+  const hasRegisteredNativeWidget = useRef(false);
+
+  useEffect(() => {
+    isDesignerRef.current = isInDesignerMode();
+  }, []);
+
+  const isDesigner = isDesignerRef.current;
+
+  // Register native widget - only once on mount
+  useEffect(() => {
+    const isInIframe =
+      typeof window !== 'undefined' && window.self !== window.top;
+    if (!isInIframe || !window.parent) {
+      return;
+    }
+
+    // Register placeholder for save functionality
+    registerPlaceholder(BREADCRUMB_PLACEHOLDER_ID);
+
+    // Skip if already registered
+    if (
+      typeof window !== 'undefined' &&
+      window.__breadcrumbRegistered &&
+      hasRegisteredNativeWidget.current
+    ) {
+      return;
+    }
+
+    // Send native widget registration to Theme Editor
+    const nativeWidgetConfig = {
+      placeholderId: BREADCRUMB_PLACEHOLDER_ID,
+      autoAdd: true,
+      section: {
+        id: BREADCRUMB_SECTION_ID,
+        type: 'native',
+        label: 'Breadcrumb',
+        blocks: [],
+        properties: initialSettings.properties || {
+          separatorIcon: 'chevron-end',
+          showHomeIcon: false
+        },
+        styles: initialSettings.sectionStyles || {}
+      }
+    };
+
+    window.parent.postMessage(
+      {
+        type: 'REGISTER_NATIVE_WIDGETS',
+        data: { widgets: [nativeWidgetConfig] }
+      },
+      '*'
+    );
+
+    // Mark as registered
+    window.__breadcrumbRegistered = true;
+    hasRegisteredNativeWidget.current = true;
+
+    // Cleanup: unregister placeholder on unmount
+    return () => {
+      unregisterPlaceholder(BREADCRUMB_PLACEHOLDER_ID);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Listen for theme updates and selection changes from Theme Editor
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleMessage = (event: MessageEvent) => {
+      const { type, data } = event.data || {};
+
+      // Handle theme updates - styles come as { 'font-size': { desktop: 14 } }
+      if (
+        (type === 'UPDATE_THEME' || type === 'LOAD_THEME') &&
+        data?.theme?.placeholders
+      ) {
+        const placeholder = data.theme.placeholders?.find(
+          (p: ThemePlaceholder) => p.slug === BREADCRUMB_PLACEHOLDER_ID
+        );
+
+        const breadcrumbSection = placeholder?.sections?.find(
+          (s: ThemeSection) => s.id === BREADCRUMB_SECTION_ID
+        );
+
+        if (breadcrumbSection) {
+          // Update properties
+          if (breadcrumbSection.properties) {
+            setSectionProperties((prev) => ({
+              ...prev,
+              ...extractPropertiesValues(breadcrumbSection.properties)
+            }));
+          }
+
+          // Update styles - extract from responsive format
+          if (breadcrumbSection.styles) {
+            const extractedStyles = extractStylesValues(
+              breadcrumbSection.styles as Record<string, unknown>
+            );
+            setSectionStyles(extractedStyles);
+          }
+        }
+      }
+
+      // Handle section selection
+      if (type === 'SELECT_SECTION') {
+        setIsBreadcrumbSelected(
+          data?.placeholderId === BREADCRUMB_PLACEHOLDER_ID &&
+            data?.sectionId === BREADCRUMB_SECTION_ID
+        );
+      }
+    };
+
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, []);
+
+  return (
+    <BreadcrumbContext.Provider
+      value={{
+        isDesigner,
+        isBreadcrumbSectionSelected: isBreadcrumbSelected,
+        properties: sectionProperties,
+        sectionStyles
+      }}
+    >
+      {children}
+    </BreadcrumbContext.Provider>
+  );
+}
+
+/**
+ * Extract property values handling responsive format
+ */
+function extractPropertiesValues(
+  properties: Record<string, unknown>
+): BreadcrumbProperties {
+  const result: Record<string, unknown> = {};
+
+  Object.entries(properties).forEach(([key, value]) => {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      // Responsive format: { desktop: value, mobile: value }
+      const obj = value as Record<string, unknown>;
+      result[key] = obj.desktop ?? obj.mobile ?? Object.values(obj)[0];
+    } else {
+      result[key] = value;
+    }
+  });
+
+  return result as BreadcrumbProperties;
+}
+
+/**
+ * Extract style values handling responsive format
+ */
+function extractStylesValues(
+  styles: Record<string, unknown>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  Object.entries(styles).forEach(([key, value]) => {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      // Responsive format: { desktop: value, mobile: value }
+      const obj = value as Record<string, unknown>;
+      result[key] = obj.desktop ?? obj.mobile ?? Object.values(obj)[0];
+    } else {
+      result[key] = value;
+    }
+  });
+
+  return result;
+}

package/app-template/src/views/breadcrumb/constants.ts

@@ -0,0 +1,15 @@
+/**
+ * Breadcrumb Constants
+ *
+ * Shared constants for breadcrumb native widget.
+ * This file can be imported by both server and client components.
+ */
+
+export const BREADCRUMB_PLACEHOLDER_ID = 'breadcrumb';
+export const BREADCRUMB_SECTION_ID = 'breadcrumb-section';
+export const BREADCRUMB_WIDGET_SLUG = 'breadcrumb-styles';
+
+export interface BreadcrumbProperties {
+  separatorIcon?: string;
+  showHomeIcon?: boolean;
+}

package/app-template/src/views/breadcrumb/index.tsx

@@ -0,0 +1,127 @@
+import 'server-only';
+
+import { getWidgetData } from '@akinon/next/data/server/widget';
+import { BreadcrumbResultType } from '@akinon/next/types';
+import BreadcrumbClient from './breadcrumb-client';
+import {
+  BREADCRUMB_SECTION_ID,
+  BREADCRUMB_WIDGET_SLUG,
+  BreadcrumbProperties
+} from './constants';
+
+export interface BreadcrumbProps {
+  breadcrumbList?: BreadcrumbResultType[];
+}
+
+export interface BreadcrumbSettings {
+  sectionStyles?: Record<string, unknown>;
+  properties?: BreadcrumbProperties;
+}
+
+/**
+ * Extract responsive value from theme editor format
+ * { desktop: value, mobile: value } -> value
+ */
+function extractResponsiveValue(value: unknown): unknown {
+  if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+    const obj = value as Record<string, unknown>;
+    return obj.desktop ?? obj.mobile ?? Object.values(obj)[0];
+  }
+  return value;
+}
+
+/**
+ * Parse breadcrumb settings from widget data (server-side)
+ */
+function parseServerBreadcrumbSettings(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  widgetData: any
+): BreadcrumbSettings {
+  const result: BreadcrumbSettings = {};
+
+  if (!widgetData?.attributes) {
+    return result;
+  }
+
+  const attrs = widgetData.attributes;
+
+  // Parse section-level styles and properties
+  const sectionData = attrs[BREADCRUMB_SECTION_ID];
+  if (sectionData) {
+    try {
+      const data =
+        typeof sectionData === 'string'
+          ? JSON.parse(sectionData)
+          : typeof sectionData === 'object' && 'value' in sectionData
+          ? JSON.parse((sectionData as { value: string }).value)
+          : null;
+
+      if (data) {
+        // Parse properties
+        if (data.properties) {
+          const properties: BreadcrumbProperties = {};
+
+          if (data.properties.separatorIcon !== undefined) {
+            properties.separatorIcon = extractResponsiveValue(
+              data.properties.separatorIcon
+            ) as string;
+          }
+
+          if (data.properties.showHomeIcon !== undefined) {
+            const showHomeIcon = extractResponsiveValue(
+              data.properties.showHomeIcon
+            );
+            properties.showHomeIcon =
+              showHomeIcon === 'true' || Boolean(showHomeIcon);
+          }
+
+          result.properties = properties;
+        }
+
+        // Parse styles
+        if (data.styles) {
+          const styles: Record<string, unknown> = {};
+
+          Object.entries(data.styles).forEach(([key, value]) => {
+            styles[key] = extractResponsiveValue(value);
+          });
+
+          result.sectionStyles = styles;
+        }
+      }
+    } catch {
+      // Parsing failed, return empty result
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Breadcrumb Server Component
+ *
+ * Fetches widget settings server-side and passes to client component
+ * to avoid flash of unstyled content on page load.
+ */
+export default async function Breadcrumb({ breadcrumbList }: BreadcrumbProps) {
+  // Fetch breadcrumb widget settings server-side
+  const widgetData = await getWidgetData({
+    slug: BREADCRUMB_WIDGET_SLUG
+  }).catch(() => null);
+
+  const initialSettings = parseServerBreadcrumbSettings(widgetData);
+
+  return (
+    <BreadcrumbClient
+      breadcrumbList={breadcrumbList}
+      initialSettings={initialSettings}
+    />
+  );
+}
+
+// Re-export client components for direct use
+export { default as BreadcrumbClient } from './breadcrumb-client';
+export {
+  default as BreadcrumbRegistrar,
+  useBreadcrumb
+} from './breadcrumb-registrar';

package/app-template/src/views/breadcrumb.tsx

@@ -1,38 +1,13 @@
-'use client';
-
-import { Fragment } from 'react';
-import { Icon, Link } from '@theme/components';
-import { ROUTES } from '@theme/routes';
-import { useLocalization } from '@akinon/next/hooks';
-import { BreadcrumbResultType } from '@akinon/next/types';
-import { capitalize } from '@akinon/next/utils';
-
-export interface BreadcrumbProps {
-  breadcrumbList?: BreadcrumbResultType[];
-}
-
-export default function Breadcrumb(props: BreadcrumbProps) {
-  const { t, locale } = useLocalization();
-  const { breadcrumbList = [] } = props;
-
-  const list = [
-    { url: ROUTES.HOME, text: t('common.breadcrumb.homepage') },
-    ...breadcrumbList.map((breadcrumb) => ({
-      url: breadcrumb.url,
-      text: breadcrumb.label
-    }))
-  ];
-
-  return (
-    <div className="flex items-center gap-3 text-xs leading-4 text-gray-950">
-      {list.map((item, index) => (
-        <Fragment key={index}>
-          <Link href={item.url}>
-            {capitalize(item.text.toLocaleLowerCase(locale))}
-          </Link>
-          {index !== list.length - 1 && <Icon name="chevron-end" size={8} />}
-        </Fragment>
-      ))}
-    </div>
-  );
-}
+/**
+ * Breadcrumb Component
+ *
+ * Re-exports the Breadcrumb component from the breadcrumb folder.
+ * This file is kept for backwards compatibility with existing imports.
+ */
+export { default } from './breadcrumb/index';
+export type { BreadcrumbProps } from './breadcrumb/index';
+export {
+  BreadcrumbRegistrar,
+  useBreadcrumb,
+  BreadcrumbClient
+} from './breadcrumb/index';