@page-speed/lightbox 0.0.1

package/README.md

@@ -0,0 +1,244 @@
+# @page-speed/lightbox
+
+High‑performance, media‑rich lightbox for React, designed for the DashTrack / OpenSite ecosystem and the Semantic Site Builder engine.
+
+## Overview
+
+`@page-speed/lightbox` renders images, videos, PDFs, and custom React components inside a responsive, keyboard‑friendly lightbox. It is built to be:
+
+- **Fast** – small, tree‑shakable bundles with lazy loading for heavy dependencies (like the PDF viewer).
+- **Composable** – separate layers for core hooks, components, and renderers.
+- **Semantic‑engine ready** – easy to integrate into the Semantic Site Builder / Chai payload flow.
+
+You can use it both inside the DashTrack platform and in standalone React apps.
+
+## Key Features
+
+- **Multiple media types**: `image`, `video`, `pdf`, and `component` (custom React content).
+- **Responsive layouts**: chooses `fullscreen`, `vertical-split`, or `horizontal` layout based on viewport (overridable via props).
+- **Keyboard & accessibility**: arrow‑key navigation, Escape to close, and ARIA‑friendly dialog structure.
+- **Tree‑shakable exports**: granular subpaths for `core`, `hooks`, `components`, and `renderers`.
+- **PDF support**: built‑in PDF rendering via `@page-speed/pdf-viewer`, lazily loaded only when needed.
+
+## Installation
+
+The library has **React 18+** as a peer dependency and ships TypeScript typings out of the box.
+
+### With pnpm (DashTrack default)
+
+```bash
+pnpm add @page-speed/lightbox
+```
+
+### With npm
+
+```bash
+npm install @page-speed/lightbox
+```
+
+### With yarn
+
+```bash
+yarn add @page-speed/lightbox
+```
+
+## Basic Usage (Controlled by Parent)
+
+The `Lightbox` component is intentionally **controlled by mount/unmount**. You decide when it is shown by conditionally rendering it in your component.
+
+```tsx
+import { useState } from "react";
+import { Lightbox, type LightboxItem } from "@page-speed/lightbox";
+
+const items: LightboxItem[] = [
+  { id: "1", type: "image", src: "/images/hero.jpg", alt: "Hero" },
+  { id: "2", type: "video", src: "/videos/demo.mp4", title: "Demo" },
+];
+
+export function Gallery() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [initialIndex, setInitialIndex] = useState(0);
+
+  return (
+    <>
+      <button
+        onClick={() => {
+          setInitialIndex(0);
+          setIsOpen(true);
+        }}
+      >
+        Open gallery
+      </button>
+
+      {isOpen && (
+        <Lightbox
+          items={items}
+          initialIndex={initialIndex}
+          onClose={() => setIsOpen(false)}
+        />
+      )}
+    </>
+  );
+}
+```
+
+**How it works:**
+
+- Clicking the button sets `isOpen` to `true`, which mounts the `<Lightbox />`.
+- When the lightbox is mounted, it locks body scroll and calls `onOpen` (if provided).
+- When you close the lightbox (via close button, overlay, or Escape), it calls `onClose`, and the parent should unmount it by toggling `isOpen`.
+
+## Defining Lightbox Items
+
+Items are strongly typed via `LightboxItem` and support different media strategies:
+
+```ts
+import type { LightboxItem } from "@page-speed/lightbox";
+
+const items: LightboxItem[] = [
+  { id: "img-1", type: "image", src: "/images/hero.jpg", alt: "Hero" },
+  { id: "pdf-1", type: "pdf", src: "/docs/brochure.pdf", title: "Brochure" },
+  {
+    id: "component-1",
+    type: "component",
+    component: MyCustomSlide,
+    data: { heading: "Custom slide" },
+  },
+];
+```
+
+Key fields:
+
+- `id: string` – unique per item.
+- `type: "image" | "video" | "pdf" | "component"` – controls which renderer is used.
+- `src?: string` – URL for image/video/PDF.
+- `alt?: string` – alt text for images.
+- `title?` / `caption?` – shown in the chrome/caption area when enabled.
+- `component?: React.ComponentType<any>` – for `type: "component"`, your own React slide.
+- `download?` / `share?` – optional download/share configuration.
+
+## Lightbox Props (High‑Level)
+
+The full `LightboxProps` type lives in `src/types.ts` and is exported from the package. The most commonly used props are:
+
+- `items: LightboxItem[]` – **required** list of slides.
+- `initialIndex?: number` – index of the item to show first.
+- `layout?: "horizontal" | "vertical-split" | "custom-slide" | "fullscreen" | "inline"` – override automatic layout.
+- `controls?: Partial<LightboxControls>` – enable/disable UI features.
+- `height?: string | number` – e.g. `"80vh"`.
+- `maxWidth?: string | number` – e.g. `"1200px"`.
+- `className?`, `style?` – for wrapping container.
+- `onOpen?`, `onClose?` – lifecycle callbacks.
+- `onSelect?(index: number)` – called when the current index changes.
+- `onNext?`, `onPrev?` – called on navigation.
+- `enableKeyboardShortcuts?: boolean` – default `true`.
+- `disableScroll?: boolean` – default `true` (locks body scroll while open).
+- `closeOnBackdropClick?: boolean` – default `true`.
+
+Example configuring layout and controls:
+
+```tsx
+<Lightbox
+  items={items}
+  layout="horizontal"
+  controls={{ navigation: true, keyboard: true, captions: true }}
+  onSelect={(index) => console.log("Selected index", index)}
+/>
+```
+
+## Hooks and Core API
+
+For more advanced usage (especially inside the Semantic Site Builder), you can work directly with the hooks and core exports.
+
+### `useLightbox` (core)
+
+`useLightbox` composes gallery navigation and open/close state into a single hook. It is exported from both `@page-speed/lightbox` and `@page-speed/lightbox/core`.
+
+```ts
+import { useLightbox } from "@page-speed/lightbox/core";
+
+const lb = useLightbox({ items, onSelect: (i) => console.log(i) });
+
+// lb: { isOpen, open, close, currentIndex, currentItem, next, prev, canNext, canPrev, goTo, items }
+```
+
+You can build your own UI around this hook if you need something different from the default `<Lightbox />` shell.
+
+### Hooks Subpath
+
+The `hooks` subpath provides granular imports for tree‑shaking:
+
+```ts
+import { useGalleryState, useResponsiveness } from "@page-speed/lightbox/hooks";
+```
+
+Available hooks:
+
+- `useGalleryState` – navigation state for a list of `LightboxItem`s.
+- `useLightboxState` – open/close + scroll locking.
+- `useLightbox` – composed lightbox controller.
+- `useKeyboardShortcuts` – attach keyboard handlers.
+- `useResponsiveness` – responsive breakpoint info.
+
+## Components and Renderers
+
+You can import the building blocks individually when constructing custom UIs or integrating into block registries.
+
+### Components
+
+```ts
+import {
+  Lightbox,
+  LightboxOverlay,
+  LightboxContent,
+  LightboxChrome,
+  HorizontalLayout,
+} from "@page-speed/lightbox/components";
+```
+
+### Renderers
+
+```ts
+import {
+  ImageRenderer,
+  VideoRenderer,
+  PDFRenderer,
+  ComponentRenderer,
+} from "@page-speed/lightbox/renderers";
+```
+
+These renderers are what `LightboxContent` uses under the hood for each `LightboxItem.type`.
+
+## Integration Notes for Semantic Site Builder
+
+- Treat `items: LightboxItem[]` as the **projection of your Chai/semantic payload** for a gallery block.
+- Use the **controlled mounting pattern**: the builder decides when to show a lightbox by mounting `<Lightbox />` with the appropriate `items` and `initialIndex`.
+- For full control or custom block shells, prefer `useLightbox` from `@page-speed/lightbox/core` and wire it into your block registry.
+
+See `dev-docs/lightbox-implementation-guide.md` and `dev-docs/SEMANTIC_SITE_BUILDER.md` in this repo for deeper, platform‑specific details.
+
+## Performance Notes
+
+- Heavy dependencies like the PDF viewer are **lazy‑loaded**, so including support for PDFs does not impact the initial bundle significantly.
+- The module exports are **tree‑shakable**, especially when using the subpaths (`/core`, `/hooks`, `/components`, `/renderers`).
+- The lightbox locks body scroll while open to reduce layout shift and improve perceived stability.
+
+For broader ecosystem performance guidelines, see `dev-docs/ECOSYSTEM_GUIDELINES.md`.
+
+## Contributing
+
+Contributions are welcome. Please open issues or pull requests on the GitHub repo:
+
+- Repository: <https://github.com/opensite-ai/page-speed-lightbox>
+
+Follow the existing code style, add tests for new behavior, and ensure `pnpm test`, `pnpm run type-check`, and `pnpm run build` all pass before submitting.
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.
+
+## Related Projects
+
+- [@page-speed/pdf-viewer](https://github.com/opensite-ai/page-speed-pdf-viewer) – PDF viewer used internally by the lightbox.
+- [Page Speed Hooks](https://github.com/opensite-ai/page-speed-hooks) – hooks for optimizing page load behavior.
+- [OpenSite AI](https://opensite.ai) – more about the platform and ecosystem.

package/dist/__mocks__/styleMock.d.ts

@@ -0,0 +1,4 @@
+declare const styles: {
+    [key: string]: string;
+};
+export default styles;

package/dist/components/Layouts/HorizontalLayout.d.ts

@@ -0,0 +1,16 @@
+import React from "react";
+interface HorizontalLayoutProps {
+    content: React.ReactNode;
+    chrome: React.ReactNode;
+    height?: string | number;
+    maxWidth?: string | number;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/**
+ * Default desktop layout: primary content area with chrome and optional
+ * thumbnails below. For v1 we only implement the main content + chrome
+ * region; thumbnails can be added later as a non-breaking enhancement.
+ */
+export declare function HorizontalLayout({ content, chrome, height, maxWidth, className, style, }: HorizontalLayoutProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Lightbox.d.ts

@@ -0,0 +1,10 @@
+import { LightboxProps } from "../types";
+/**
+ * Main Lightbox component.
+ *
+ * This component is intentionally controlled from the outside: it renders
+ * whenever it is mounted, and callers decide when to mount/unmount it.
+ * That keeps it easy to integrate into the Semantic Site Builder while
+ * still providing strong defaults for keyboard and scroll handling.
+ */
+export declare function Lightbox(props: LightboxProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/LightboxChrome.d.ts

@@ -0,0 +1,21 @@
+import { LightboxControls, LightboxItem } from "../types";
+interface LightboxChromeProps {
+    currentIndex: number;
+    totalItems: number;
+    currentItem: LightboxItem | null;
+    canNext: boolean;
+    canPrev: boolean;
+    controls?: Partial<LightboxControls>;
+    onNext: () => void;
+    onPrev: () => void;
+    onClose?: () => void;
+}
+/**
+ * Toolbar / chrome shown above or below the main content.
+ *
+ * For v1 this focuses on navigation, close button, basic captions, and
+ * counter. More advanced controls (share, download, fullscreen) can be
+ * layered in later without breaking the API.
+ */
+export declare function LightboxChrome({ currentIndex, totalItems, currentItem, canNext, canPrev, controls, onNext, onPrev, onClose, }: LightboxChromeProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/LightboxContent.d.ts

@@ -0,0 +1,13 @@
+import { LightboxItem, LightboxLayoutType } from "../types";
+interface LightboxContentProps {
+    item: LightboxItem | null;
+    layout: LightboxLayoutType;
+}
+/**
+ * Dispatches to the appropriate renderer based on the LightboxItem type.
+ *
+ * This component stays very small so individual renderers can be
+ * tree-shaken and swapped out by the Semantic UI engine if needed.
+ */
+export declare function LightboxContent({ item, layout }: LightboxContentProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/components/LightboxOverlay.d.ts

@@ -0,0 +1,12 @@
+interface LightboxOverlayProps {
+    onClose?: () => void;
+    closeOnBackdropClick?: boolean;
+}
+/**
+ * Full-screen dark overlay that sits behind the lightbox content.
+ *
+ * Kept intentionally minimal so it works well with the Semantic Site
+ * Builder and external layout containers.
+ */
+export declare function LightboxOverlay({ onClose, closeOnBackdropClick, }: LightboxOverlayProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/index.css

@@ -0,0 +1,99 @@
+/* src/styles/Lightbox.module.css */
+.Lightbox_lightboxPortal3 {
+  position: fixed;
+  inset: 0;
+  z-index: 1000;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.Lightbox_overlay3 {
+  position: fixed;
+  inset: 0;
+  background: var(--lightbox-overlay, rgba(0, 0, 0, 0.85));
+}
+.Lightbox_horizontalLayoutRoot3 {
+  position: relative;
+  max-width: var(--lightbox-max-width, 90vw);
+  width: 100%;
+  padding: var(--lightbox-padding, 24px);
+  box-sizing: border-box;
+}
+.Lightbox_horizontalLayoutContainer3 {
+  position: relative;
+  background: var(--lightbox-modal-bg, #111);
+  color: var(--lightbox-text, #fff);
+  border-radius: var(--lightbox-radius, 12px);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+.Lightbox_mainContent3 {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--lightbox-content-bg, #000);
+}
+.Lightbox_toolbar3 {
+  border-top: 1px solid var(--lightbox-border, rgba(255, 255, 255, 0.1));
+}
+.Lightbox_media3 {
+  max-width: 100%;
+  max-height: 80vh;
+  object-fit: contain;
+}
+.Lightbox_chrome3 {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 8px 12px;
+  background: var(--lightbox-toolbar, rgba(0, 0, 0, 0.5));
+}
+.Lightbox_chromeSection3 {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.Lightbox_navButton3,
+.Lightbox_closeButton3 {
+  border: none;
+  border-radius: 999px;
+  padding: 6px 10px;
+  background: rgba(255, 255, 255, 0.08);
+  color: inherit;
+  cursor: pointer;
+}
+.Lightbox_navButton3:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+.Lightbox_counter3 {
+  font-size: 12px;
+  opacity: 0.85;
+}
+.Lightbox_captionContainer3 {
+  display: flex;
+  flex-direction: column;
+}
+.Lightbox_captionTitle3 {
+  font-size: 14px;
+  font-weight: 600;
+}
+.Lightbox_captionText3 {
+  font-size: 12px;
+  opacity: 0.85;
+}
+.Lightbox_pdfContainer3 {
+  width: 100%;
+  height: 80vh;
+  background: #111;
+}
+.Lightbox_pdfFallback3 {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  color: var(--lightbox-text-muted, rgba(255, 255, 255, 0.7));
+}

package/dist/components/index.d.ts

@@ -0,0 +1,5 @@
+export { Lightbox } from "./Lightbox";
+export { LightboxOverlay } from "./LightboxOverlay";
+export { LightboxContent } from "./LightboxContent";
+export { LightboxChrome } from "./LightboxChrome";
+export { HorizontalLayout } from "./Layouts/HorizontalLayout";