@withl5e/l5e 0.1.0-alpha.0

package/src/seo/mergeMetadata.ts

@@ -0,0 +1,200 @@
+import type { Metadata } from './types';
+
+/**
+ * Merges parent and child metadata objects
+ * Follows Next.js shallow merge pattern with deep merge for nested objects
+ *
+ * @param parent - Parent metadata (from layout/global loader)
+ * @param child - Child metadata (from page/view loader)
+ * @returns Merged metadata object
+ */
+export function mergeMetadata(
+  parent: Metadata | null | undefined,
+  child: Metadata | null | undefined,
+): Metadata {
+  // If no parent, return child (or empty object)
+  if (!parent) {
+    return child || {};
+  }
+
+  // If no child, return parent
+  if (!child) {
+    return parent;
+  }
+
+  // Shallow merge base properties (child overrides parent)
+  const merged: Metadata = {
+    ...parent,
+    ...child,
+  };
+
+  // Deep merge for nested objects
+  // OpenGraph: merge nested properties
+  if (child.openGraph || parent.openGraph) {
+    if (child.openGraph && parent.openGraph) {
+      merged.openGraph = {
+        ...parent.openGraph,
+        ...child.openGraph,
+        // Deep merge for nested arrays/objects in openGraph
+        images: child.openGraph.images ?? parent.openGraph.images,
+        videos: child.openGraph.videos ?? parent.openGraph.videos,
+        audio: child.openGraph.audio ?? parent.openGraph.audio,
+        alternateLocale: child.openGraph.alternateLocale ?? parent.openGraph.alternateLocale,
+        authors: child.openGraph.authors ?? parent.openGraph.authors,
+        tags: child.openGraph.tags ?? parent.openGraph.tags,
+      };
+    } else {
+      merged.openGraph = child.openGraph || parent.openGraph;
+    }
+  }
+
+  // Twitter: merge nested properties
+  if (child.twitter || parent.twitter) {
+    if (child.twitter && parent.twitter) {
+      merged.twitter = {
+        ...parent.twitter,
+        ...child.twitter,
+        // Deep merge for nested objects
+        images: child.twitter.images ?? parent.twitter.images,
+        app: child.twitter.app
+          ? {
+              ...parent.twitter.app,
+              ...child.twitter.app,
+              id: {
+                ...parent.twitter.app?.id,
+                ...child.twitter.app.id,
+              },
+              url: {
+                ...parent.twitter.app?.url,
+                ...child.twitter.app.url,
+              },
+            }
+          : parent.twitter.app,
+      };
+    } else {
+      merged.twitter = child.twitter || parent.twitter;
+    }
+  }
+
+  // Icons: merge nested properties
+  if (child.icons || parent.icons) {
+    if (child.icons && parent.icons) {
+      merged.icons = {
+        icon: child.icons.icon ?? parent.icons.icon,
+        shortcut: child.icons.shortcut ?? parent.icons.shortcut,
+        apple: child.icons.apple ?? parent.icons.apple,
+        other: child.icons.other ?? parent.icons.other,
+      };
+    } else {
+      merged.icons = child.icons || parent.icons;
+    }
+  }
+
+  // Verification: merge nested properties
+  if (child.verification || parent.verification) {
+    if (child.verification && parent.verification) {
+      merged.verification = {
+        ...parent.verification,
+        ...child.verification,
+        // Deep merge for other verification tags
+        other: child.verification.other
+          ? {
+              ...parent.verification.other,
+              ...child.verification.other,
+            }
+          : parent.verification.other,
+        me: child.verification.me ?? parent.verification.me,
+      };
+    } else {
+      merged.verification = child.verification || parent.verification;
+    }
+  }
+
+  // AppLinks: merge nested properties
+  if (child.appLinks || parent.appLinks) {
+    if (child.appLinks && parent.appLinks) {
+      merged.appLinks = {
+        ios: child.appLinks.ios
+          ? {
+              ...parent.appLinks.ios,
+              ...child.appLinks.ios,
+            }
+          : parent.appLinks.ios,
+        android: child.appLinks.android
+          ? {
+              ...parent.appLinks.android,
+              ...child.appLinks.android,
+            }
+          : parent.appLinks.android,
+        web: child.appLinks.web
+          ? {
+              ...parent.appLinks.web,
+              ...child.appLinks.web,
+            }
+          : parent.appLinks.web,
+      };
+    } else {
+      merged.appLinks = child.appLinks || parent.appLinks;
+    }
+  }
+
+  // FormatDetection: merge nested properties
+  if (child.formatDetection || parent.formatDetection) {
+    if (child.formatDetection && parent.formatDetection) {
+      merged.formatDetection = {
+        ...parent.formatDetection,
+        ...child.formatDetection,
+      };
+    } else {
+      merged.formatDetection = child.formatDetection || parent.formatDetection;
+    }
+  }
+
+  // Viewport: merge if both are objects
+  if (child.viewport && parent.viewport) {
+    if (typeof child.viewport === 'object' && typeof parent.viewport === 'object') {
+      merged.viewport = {
+        ...parent.viewport,
+        ...child.viewport,
+      } as Metadata['viewport'];
+    } else {
+      // If either is string, child overrides
+      merged.viewport = child.viewport;
+    }
+  }
+
+  // Robots: merge if both are objects
+  if (child.robots && parent.robots) {
+    if (typeof child.robots === 'object' && typeof parent.robots === 'object') {
+      merged.robots = {
+        ...parent.robots,
+        ...child.robots,
+      } as Metadata['robots'];
+    } else {
+      // If either is string, child overrides
+      merged.robots = child.robots;
+    }
+  }
+
+  // Array fields: child overrides parent (shallow merge behavior)
+  // These are already handled by spread operator above
+  // But we explicitly handle them for clarity:
+  merged.keywords = child.keywords ?? parent.keywords;
+  merged.themeColor = child.themeColor ?? parent.themeColor;
+  merged.archives = child.archives ?? parent.archives;
+  merged.assets = child.assets ?? parent.assets;
+
+  // Other: merge objects
+  if (child.other || parent.other) {
+    if (child.other && parent.other) {
+      merged.other = {
+        ...parent.other,
+        ...child.other,
+      };
+    } else {
+      merged.other = child.other || parent.other;
+    }
+  }
+
+  return merged;
+}

package/src/seo/types.ts

@@ -0,0 +1,316 @@
+// Basic metadata types
+export type Author = { name: string; url?: string };
+
+export interface Metadata {
+  // Basic meta tags
+  charset?: string;
+  title?: string | TemplateString;
+  description?: string;
+  keywords?: string | string[];
+  author?: string | Author | Author[];
+
+  // URL and canonical
+  canonical?: string;
+
+  // Robots and indexing
+  robots?:
+    | string
+    | {
+        index?: boolean;
+        follow?: boolean;
+        noarchive?: boolean;
+        nosnippet?: boolean;
+        noimageindex?: boolean;
+        nocache?: boolean;
+        allowQueryNames?: string | string[];
+      };
+
+  // Viewport
+  viewport?:
+    | string
+    | {
+        width?: string | number;
+        height?: string | number;
+        initialScale?: number;
+        maximumScale?: number;
+        minimumScale?: number;
+        userScalable?: boolean;
+      };
+
+  // Theme and colors
+  themeColor?: string | string[];
+  colorScheme?: 'light' | 'dark' | 'light dark' | 'dark light';
+
+  // Icons
+  icons?: {
+    icon?: string | string[];
+    shortcut?: string;
+    apple?: string | string[];
+    other?: Array<{
+      rel?: string;
+      url: string;
+      sizes?: string;
+      type?: string;
+    }>;
+  };
+
+  // Application specific
+  generator?: string;
+  creator?: string;
+  publisher?: string;
+  referrer?:
+    | 'no-referrer'
+    | 'origin'
+    | 'no-referrer-when-downgrade'
+    | 'origin-when-cross-origin'
+    | 'same-origin'
+    | 'strict-origin'
+    | 'strict-origin-when-cross-origin'
+    | 'unsafe-url';
+
+  // Pagination links
+  prev?: string;
+  next?: string;
+
+  // Format detection
+  formatDetection?: {
+    telephone?: boolean;
+    date?: boolean;
+    address?: boolean;
+    email?: boolean;
+  };
+
+  // Open Graph
+  openGraph?: {
+    type?:
+      | 'website'
+      | 'article'
+      | 'book'
+      | 'profile'
+      | 'music.song'
+      | 'music.album'
+      | 'music.playlist'
+      | 'music.radio_station'
+      | 'video.movie'
+      | 'video.episode'
+      | 'video.tv_show'
+      | 'video.other';
+    title?: string;
+    description?: string;
+    siteName?: string;
+    url?: string;
+    locale?: string;
+    alternateLocale?: string | string[];
+    images?: string | OpenGraphImage | Array<string | OpenGraphImage>;
+    videos?: string | OpenGraphVideo | Array<string | OpenGraphVideo>;
+    audio?: string | OpenGraphAudio | Array<string | OpenGraphAudio>;
+    determiner?: 'a' | 'an' | 'the' | 'auto' | '';
+
+    // Article specific
+    publishedTime?: string;
+    modifiedTime?: string;
+    expirationTime?: string;
+    authors?: string | string[];
+    section?: string;
+    tags?: string | string[];
+
+    // Book specific
+    isbn?: string;
+    releaseDate?: string;
+
+    // Profile specific
+    firstName?: string;
+    lastName?: string;
+    username?: string;
+    gender?: string;
+  };
+
+  // Twitter Card
+  twitter?: {
+    card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+    site?: string;
+    siteId?: string;
+    creator?: string;
+    creatorId?: string;
+    title?: string;
+    description?: string;
+    images?: string | TwitterImage | Array<string | TwitterImage>;
+    app?: {
+      id: {
+        iphone?: string;
+        ipad?: string;
+        googleplay?: string;
+      };
+      url?: {
+        iphone?: string;
+        ipad?: string;
+        googleplay?: string;
+      };
+      name?: string;
+    };
+  };
+
+  // Verification
+  verification?: {
+    google?: string;
+    yahoo?: string;
+    yandex?: string;
+    me?: string | string[];
+    other?: Record<string, string | string[]>;
+  };
+
+  // App Links
+  appLinks?: {
+    ios?: {
+      url?: string;
+      app_store_id?: string;
+      app_name?: string;
+    };
+    android?: {
+      package?: string;
+      app_name?: string;
+      url?: string;
+    };
+    web?: {
+      url?: string;
+      should_fallback?: boolean;
+    };
+  };
+
+  // Additional meta tags
+  other?: Record<string, string | number | string[]>;
+
+  // Archives (for blog posts, etc.)
+  archives?: string | string[];
+
+  // Assets and manifests
+  assets?: string | string[];
+  manifest?: string;
+
+  feed?: string;
+
+  // Category
+  category?: string;
+
+  // Classification
+  classification?: string;
+}
+
+export interface OpenGraphImage {
+  url: string;
+  secureUrl?: string;
+  alt?: string;
+  type?: string;
+  width?: string | number;
+  height?: string | number;
+}
+
+export interface OpenGraphVideo {
+  url: string;
+  secureUrl?: string;
+  type?: string;
+  width?: string | number;
+  height?: string | number;
+}
+
+export interface OpenGraphAudio {
+  url: string;
+  secureUrl?: string;
+  type?: string;
+}
+
+export interface TwitterImage {
+  url: string;
+  alt?: string;
+}
+
+export interface TemplateString {
+  default: string;
+  template?: string;
+  absolute?: boolean;
+}
+
+// For dynamic metadata generation
+export interface ResolvingMetadata extends Promise<Metadata> {}
+
+// Page props type for generateMetadata
+export interface MetadataProps<
+  Params = Record<string, string | string[]>,
+  SearchParams = Record<string, string | string[] | undefined>,
+> {
+  params?: Params;
+  searchParams?: SearchParams;
+}
+
+// Schema.org types for structured data
+export interface OrganizationSchema {
+  '@context': 'https://schema.org';
+  '@type': 'Organization';
+  name: string;
+  url: string;
+  logo?: string;
+  description?: string;
+  sameAs?: string[]; // Social media profiles
+  contactPoint?: {
+    '@type': 'ContactPoint';
+    email?: string;
+    contactType?: string;
+    availableLanguage?: string[];
+  };
+  address?: {
+    '@type': 'PostalAddress';
+    addressCountry?: string;
+    addressLocality?: string;
+  };
+}
+
+export interface WebSiteSchema {
+  '@context': 'https://schema.org';
+  '@type': 'WebSite';
+  name: string;
+  url: string;
+  description?: string;
+  inLanguage?: string;
+  potentialAction?: {
+    '@type': 'SearchAction';
+    target: {
+      '@type': 'EntryPoint';
+      urlTemplate: string;
+    };
+    'query-input': string;
+  };
+}
+
+export interface BreadcrumbSchema {
+  '@context': 'https://schema.org';
+  '@type': 'BreadcrumbList';
+  itemListElement: Array<{
+    '@type': 'ListItem';
+    position: number;
+    name: string;
+    item?: string;
+  }>;
+}
+
+export interface WebPageSchema {
+  '@context': 'https://schema.org';
+  '@type': 'WebPage';
+  name: string;
+  url: string;
+  description?: string;
+  inLanguage?: string;
+  isPartOf?: {
+    '@type': 'WebSite';
+    '@id': string;
+  };
+  about?: {
+    '@type': 'Thing';
+    name: string;
+  };
+  primaryImageOfPage?: {
+    '@type': 'ImageObject';
+    url: string;
+    width?: number;
+    height?: number;
+  };
+}

package/src/swap/SwapResponse.tsx

@@ -0,0 +1,16 @@
+interface SwapResponseProps {
+  children: JSX.Element | JSX.Element[];
+  hasMore?: boolean;
+  meta?: Record<string, string>;
+}
+
+export function SwapResponse({ children, hasMore, meta }: SwapResponseProps) {
+  return (
+    <div
+      data-has-more={hasMore !== undefined ? String(hasMore) : undefined}
+      {...(meta && Object.fromEntries(Object.entries(meta).map(([k, v]) => [`data-${k}`, v])))}
+    >
+      {children}
+    </div>
+  );
+}

package/src/swap/create-swap.ts

@@ -0,0 +1,121 @@
+import { parseHTML } from './parse';
+import { swap } from './swap';
+import type { SwapOptions, SwapInstance, SwapMeta, SwapContext } from './types';
+
+const REQUEST_CLASS = 'l5e-request';
+
+function getNaturalEvent(el: Element): string {
+  const tag = el.tagName.toLowerCase();
+  if (tag === 'form') return 'submit';
+  if (tag === 'input' || tag === 'textarea' || tag === 'select') return 'change';
+  return 'click';
+}
+
+export function createSwap(opts: SwapOptions): SwapInstance {
+  let destroyed = false;
+  const swapMode = opts.swap ?? 'innerHTML';
+
+  const triggerEls = opts.trigger
+    ? Array.from(document.querySelectorAll<HTMLElement>(opts.trigger))
+    : [];
+
+  const targetEl = document.querySelector<HTMLElement>(opts.target);
+
+  const firstTrigger = triggerEls[0] ?? null;
+  const eventName = opts.event ?? (firstTrigger ? getNaturalEvent(firstTrigger) : 'click');
+  const shouldPreventDefault = eventName === 'submit';
+
+  const loadingCfg = opts.loading;
+  const loadingClass = loadingCfg?.class ?? REQUEST_CLASS;
+
+  function applyLoading(currentTrigger: HTMLElement | null): () => void {
+    if (!loadingCfg) return () => {};
+    const el = loadingCfg.target
+      ? document.querySelector<HTMLElement>(loadingCfg.target)
+      : currentTrigger;
+    if (!el) return () => {};
+
+    const shouldDisable = loadingCfg.disabled ?? el === currentTrigger;
+    const originalHtml = el.innerHTML;
+    const originalDisabled = (el as HTMLButtonElement).disabled ?? false;
+
+    el.classList.add(loadingClass);
+    if (loadingCfg.html) el.innerHTML = loadingCfg.html;
+    if (shouldDisable && 'disabled' in el) (el as any).disabled = true;
+
+    return () => {
+      el.classList.remove(loadingClass);
+      if (loadingCfg.html && el !== targetEl) el.innerHTML = originalHtml;
+      if (shouldDisable && 'disabled' in el) (el as any).disabled = originalDisabled;
+    };
+  }
+
+  async function exec(input?: HTMLElement | string): Promise<void> {
+    if (destroyed) return;
+
+    if (!targetEl) return;
+
+    const ctxEl = input instanceof HTMLElement ? input : firstTrigger;
+    const ctx: SwapContext = {
+      triggerElement: ctxEl,
+      triggerDataset: ctxEl?.dataset ?? ({} as DOMStringMap),
+    };
+    const htmlInput = typeof input === 'string' ? input : undefined;
+
+    if (opts.onBefore?.(ctx) === false) return;
+
+    const restoreLoading = applyLoading(ctxEl);
+
+    try {
+      let html: string;
+      let res: Response | undefined;
+      if (opts.action) {
+        res = await opts.action(ctx);
+        html = await res.text();
+      } else if (htmlInput !== undefined) {
+        html = htmlInput;
+      } else {
+        return;
+      }
+
+      let nodes: Node[];
+      if (opts.select) {
+        nodes = parseHTML(html, opts.select) as Node[];
+      } else {
+        nodes = Array.from(parseHTML(html).childNodes);
+      }
+
+      const root = parseHTML(html).firstElementChild as HTMLElement | null;
+      const meta: SwapMeta = { root, response: res };
+
+      if (opts.onNodes) {
+        const t = opts.onNodes(nodes, meta);
+        if (Array.isArray(t)) nodes = t;
+      }
+
+      const inserted = swap(targetEl, nodes, swapMode);
+
+      opts.onSwap?.(inserted, meta);
+      opts.onAfter?.(inserted, meta, ctx);
+    } catch (err: any) {
+      opts.onError?.(err, err.status);
+    } finally {
+      restoreLoading();
+    }
+  }
+
+  function handleTrigger(e: Event) {
+    if (shouldPreventDefault) e.preventDefault();
+    exec((e.currentTarget as HTMLElement) ?? undefined);
+  }
+
+  triggerEls.forEach((el) => el.addEventListener(eventName, handleTrigger));
+
+  return {
+    exec,
+    destroy() {
+      destroyed = true;
+      triggerEls.forEach((el) => el.removeEventListener(eventName, handleTrigger));
+    },
+  };
+}

package/src/swap/index.ts

@@ -0,0 +1,8 @@
+// Layer 1
+export { parseHTML } from './parse';
+export { swap } from './swap';
+export { debounce } from './utils';
+
+// Layer 2
+export { createSwap } from './create-swap';
+export type { SwapOptions, SwapInstance, SwapMeta, SwapMode, SwapContext } from './types';

package/src/swap/parse.ts

@@ -0,0 +1,12 @@
+export function parseHTML(html: string): DocumentFragment;
+export function parseHTML(html: string, selector: string): Element[];
+export function parseHTML(html: string, selector?: string): DocumentFragment | Element[] {
+  const tpl = document.createElement('template');
+  tpl.innerHTML = html;
+  const fragment = tpl.content;
+
+  if (selector) {
+    return Array.from(fragment.querySelectorAll(selector));
+  }
+  return fragment;
+}

package/src/swap/server.ts

@@ -0,0 +1 @@
+export { SwapResponse } from './SwapResponse';