@degallery/next 0.0.0-stage → 0.6.0

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @degallery/next
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Next.js integration for DeGallery. It provides a `next/image` renderer for the
+React gallery views and server helpers for loading gallery data during server
+rendering.
+
+## Install
+
+```sh
+pnpm add @degallery/next @degallery/react @degallery/sdk @tanstack/react-query
+```
+
+Use compatible versions of Next.js 15 or 16 and React 19.
+
+## Add the provider
+
+Place `GalleryProvider` in a Client Component and use it from the root layout.
+The provider uses `next/image` for gallery images; private and expiring image
+URLs bypass the Next.js image optimizer so authenticated delivery continues to
+work.
+
+```tsx
+// app/gallery-provider.tsx
+'use client';
+
+import { GalleryProvider } from '@degallery/next';
+
+export function AppGalleryProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <GalleryProvider
+      apiUrl={process.env.NEXT_PUBLIC_DEGALLERY_API_URL!}
+      mediaUrl={process.env.NEXT_PUBLIC_DEGALLERY_MEDIA_URL}
+      publishableKey={process.env.NEXT_PUBLIC_DEGALLERY_PUBLISHABLE_KEY}
+    >
+      {children}
+    </GalleryProvider>
+  );
+}
+```
+
+Add the provider to `app/layout.tsx`:
+
+```tsx
+import { AppGalleryProvider } from './gallery-provider';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body><AppGalleryProvider>{children}</AppGalleryProvider></body>
+    </html>
+  );
+}
+```
+
+## Server-render a gallery
+
+Use the server-only subpath from a Server Component. The initial gallery page
+is fetched on the server and rendered into the HTML, then the client view can
+continue loading pages and provide its interactive lightbox.
+
+```tsx
+import { ServerGallery } from '@degallery/next/server';
+
+export default async function GalleryPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  return (
+    <ServerGallery
+      apiUrl={process.env.NEXT_PUBLIC_DEGALLERY_API_URL!}
+      mediaUrl={process.env.NEXT_PUBLIC_DEGALLERY_MEDIA_URL}
+      galleryIdOrSlug={slug}
+      limit={24}
+    />
+  );
+}
+```
+
+For private galleries, pass a short-lived read token from a Server Component or
+server action. Never expose a private API key to a Client Component. `getGallery`
+is also exported for applications that need to render their own markup:
+
+```tsx
+import { getGallery } from '@degallery/next/server';
+
+const gallery = await getGallery({ apiUrl, galleryIdOrSlug: 'my-gallery' });
+```
+
+The default server fetch uses `cache: 'no-store'` because delivery URLs can be
+private or expire. A custom `fetch` implementation may provide application
+caching when that is appropriate.
+
+## Next.js image configuration
+
+If your app uses Next.js image optimization for externally hosted public
+images, allow the hosts used by your galleries in `next.config`:
+
+```ts
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  images: {
+    remotePatterns: [
+      { protocol: 'https', hostname: 'images.unsplash.com' },
+      { protocol: 'https', hostname: 'media.degallery.dev' },
+      { protocol: 'https', hostname: 'res.cloudinary.com' },
+    ],
+  },
+};
+
+export default nextConfig;
+```
+
+Use the actual media and Cloudinary hostnames configured for your deployment.
+The gallery renderer supplies responsive sizing and image dimensions when
+available. Set the surrounding layout dimensions with CSS as usual.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { Asset, Gallery, GalleryProvider } from './lib/next';
+export type { AssetProps, GalleryProviderProps } from './lib/next';
+export type { GalleryProps, GalleryViewData } from '@degallery/react';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7D,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,204 @@
+"use client";
+import e from "next/image";
+import { forwardRef as t } from "react";
+import { Asset as n, Gallery as r, GalleryProvider as i } from "@degallery/react";
+//#region \0rolldown/runtime.js
+var a = (e, t) => () => (t || (e((t = { exports: {} }).exports, t, t.exports), e = null), t.exports), o = /* @__PURE__ */ ((e) => typeof require < "u" ? require : typeof Proxy < "u" ? new Proxy(e, { get: (e, t) => (typeof require < "u" ? require : e)[t] }) : e)(function(e) {
+	if (typeof require < "u") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + e + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+}), s = /* @__PURE__ */ a(((e) => {
+	e.Fragment = Symbol.for("react.fragment"), e.jsxDEV = void 0;
+})), c = /* @__PURE__ */ a(((e) => {
+	process.env.NODE_ENV !== "production" && (function() {
+		function t(e) {
+			if (e == null) return null;
+			if (typeof e == "function") return e.$$typeof === A ? null : e.displayName || e.name || null;
+			if (typeof e == "string") return e;
+			switch (e) {
+				case v: return "Fragment";
+				case b: return "Profiler";
+				case y: return "StrictMode";
+				case w: return "Suspense";
+				case T: return "SuspenseList";
+				case O: return "Activity";
+				case k: return "ViewTransition";
+			}
+			if (typeof e == "object") switch (typeof e.tag == "number" && console.error("Received an unexpected object in getComponentNameFromType(). This is likely a bug in React. Please file an issue."), e.$$typeof) {
+				case _: return "Portal";
+				case S: return e.displayName || "Context";
+				case x: return (e._context.displayName || "Context") + ".Consumer";
+				case C:
+					var n = e.render;
+					return e = e.displayName, e ||= (e = n.displayName || n.name || "", e === "" ? "ForwardRef" : "ForwardRef(" + e + ")"), e;
+				case E: return n = e.displayName || null, n === null ? t(e.type) || "Memo" : n;
+				case D:
+					n = e._payload, e = e._init;
+					try {
+						return t(e(n));
+					} catch {}
+			}
+			return null;
+		}
+		function n(e) {
+			return "" + e;
+		}
+		function r(e) {
+			try {
+				n(e);
+				var t = !1;
+			} catch {
+				t = !0;
+			}
+			if (t) {
+				t = console;
+				var r = t.error, i = typeof Symbol == "function" && Symbol.toStringTag && e[Symbol.toStringTag] || e.constructor.name || "Object";
+				return r.call(t, "The provided key is an unsupported type %s. This value must be coerced to a string before using it here.", i), n(e);
+			}
+		}
+		function i(e) {
+			if (e === v) return "<>";
+			if (typeof e == "object" && e && e.$$typeof === D) return "<...>";
+			try {
+				var n = t(e);
+				return n ? "<" + n + ">" : "<...>";
+			} catch {
+				return "<...>";
+			}
+		}
+		function a() {
+			var e = j.A;
+			return e === null ? null : e.getOwner();
+		}
+		function s() {
+			return Error("react-stack-top-frame");
+		}
+		function c(e) {
+			if (M.call(e, "key")) {
+				var t = Object.getOwnPropertyDescriptor(e, "key").get;
+				if (t && t.isReactWarning) return !1;
+			}
+			return e.key !== void 0;
+		}
+		function l(e, t) {
+			function n() {
+				F || (F = !0, console.error("%s: `key` is not a prop. Trying to access it will result in `undefined` being returned. If you need to access the same value within the child component, you should pass it as a different prop. (https://react.dev/link/special-props)", t));
+			}
+			n.isReactWarning = !0, Object.defineProperty(e, "key", {
+				get: n,
+				configurable: !0
+			});
+		}
+		function u() {
+			var e = t(this.type);
+			return I[e] || (I[e] = !0, console.error("Accessing element.ref was removed in React 19. ref is now a regular prop. It will be removed from the JSX Element type in a future release.")), e = this.props.ref, e === void 0 ? null : e;
+		}
+		function d(e, t, n, r, i, a) {
+			var o = n.ref;
+			return e = {
+				$$typeof: g,
+				type: e,
+				key: t,
+				props: n,
+				_owner: r
+			}, (o === void 0 ? null : o) === null ? Object.defineProperty(e, "ref", {
+				enumerable: !1,
+				value: null
+			}) : Object.defineProperty(e, "ref", {
+				enumerable: !1,
+				get: u
+			}), e._store = {}, Object.defineProperty(e._store, "validated", {
+				configurable: !1,
+				enumerable: !1,
+				writable: !0,
+				value: 0
+			}), Object.defineProperty(e, "_debugInfo", {
+				configurable: !1,
+				enumerable: !1,
+				writable: !0,
+				value: null
+			}), Object.defineProperty(e, "_debugStack", {
+				configurable: !1,
+				enumerable: !1,
+				writable: !0,
+				value: i
+			}), Object.defineProperty(e, "_debugTask", {
+				configurable: !1,
+				enumerable: !1,
+				writable: !0,
+				value: a
+			}), Object.freeze && (Object.freeze(e.props), Object.freeze(e)), e;
+		}
+		function f(e, n, i, o, s, u) {
+			var f = n.children;
+			if (f !== void 0) {
+				if (o) {
+					if (N(f)) {
+						for (o = 0; o < f.length; o++) p(f[o]);
+						Object.freeze && Object.freeze(f);
+					} else console.error("React.jsx: Static children should always be an array. You are likely explicitly calling React.jsxs or React.jsxDEV. Use the Babel transform instead.");
+				} else p(f);
+			}
+			if (M.call(n, "key")) {
+				f = t(e);
+				var m = Object.keys(n).filter(function(e) {
+					return e !== "key";
+				});
+				o = 0 < m.length ? "{key: someKey, " + m.join(": ..., ") + ": ...}" : "{key: someKey}", z[f + o] || (m = 0 < m.length ? "{" + m.join(": ..., ") + ": ...}" : "{}", console.error("A props object containing a \"key\" prop is being spread into JSX:\n  let props = %s;\n  <%s {...props} />\nReact keys must be passed directly to JSX without using spread:\n  let props = %s;\n  <%s key={someKey} {...props} />", o, f, m, f), z[f + o] = !0);
+			}
+			if (f = null, i !== void 0 && (r(i), f = "" + i), c(n) && (r(n.key), f = "" + n.key), "key" in n) for (var h in i = {}, n) h !== "key" && (i[h] = n[h]);
+			else i = n;
+			return f && l(i, typeof e == "function" ? e.displayName || e.name || "Unknown" : e), d(e, f, i, a(), s, u);
+		}
+		function p(e) {
+			m(e) ? e._store && (e._store.validated = 1) : typeof e == "object" && e && e.$$typeof === D && (e._payload.status === "fulfilled" ? m(e._payload.value) && e._payload.value._store && (e._payload.value._store.validated = 1) : e._store && (e._store.validated = 1));
+		}
+		function m(e) {
+			return typeof e == "object" && !!e && e.$$typeof === g;
+		}
+		var h = o("react"), g = Symbol.for("react.transitional.element"), _ = Symbol.for("react.portal"), v = Symbol.for("react.fragment"), y = Symbol.for("react.strict_mode"), b = Symbol.for("react.profiler"), x = Symbol.for("react.consumer"), S = Symbol.for("react.context"), C = Symbol.for("react.forward_ref"), w = Symbol.for("react.suspense"), T = Symbol.for("react.suspense_list"), E = Symbol.for("react.memo"), D = Symbol.for("react.lazy"), O = Symbol.for("react.activity"), k = Symbol.for("react.view_transition"), A = Symbol.for("react.client.reference"), j = h.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE, M = Object.prototype.hasOwnProperty, N = Array.isArray, P = console.createTask ? console.createTask : function() {
+			return null;
+		};
+		h = { react_stack_bottom_frame: function(e) {
+			return e();
+		} };
+		var F, I = {}, L = h.react_stack_bottom_frame.bind(h, s)(), R = P(i(s)), z = {};
+		e.Fragment = v, e.jsxDEV = function(e, t, n, r) {
+			var a = 1e4 > j.recentlyCreatedOwnerStacks++;
+			if (a) {
+				var o = Error.stackTraceLimit;
+				Error.stackTraceLimit = 10;
+				var s = Error("react-stack-top-frame");
+				Error.stackTraceLimit = o;
+			} else s = L;
+			return f(e, t, n, r, s, a ? P(i(e)) : R);
+		};
+	})();
+})), l = (/* @__PURE__ */ a(((e, t) => {
+	t.exports = process.env.NODE_ENV === "production" ? s() : c();
+})))(), u = "/Users/ManelisiM/Documents/my-projects/monorepo/thegallery/packages/next/src/lib/next.tsx", d = t(function({ src: t, srcSet: n, unoptimized: r, ...i }, a) {
+	return typeof t != "string" || !t ? null : /* @__PURE__ */ (0, l.jsxDEV)(e, {
+		...i,
+		ref: a,
+		src: t,
+		alt: i.alt ?? "",
+		width: typeof i.width == "number" ? i.width : 1600,
+		height: typeof i.height == "number" ? i.height : 1e3,
+		unoptimized: r
+	}, void 0, !1, {
+		fileName: u,
+		lineNumber: 23,
+		columnNumber: 5
+	}, this);
+});
+function f(e) {
+	return /* @__PURE__ */ (0, l.jsxDEV)(i, {
+		...e,
+		imageComponent: d
+	}, void 0, !1, {
+		fileName: u,
+		lineNumber: 41,
+		columnNumber: 10
+	}, this);
+}
+//#endregion
+export { n as Asset, r as Gallery, f as GalleryProvider };

package/dist/lib/hello-server.d.ts

@@ -0,0 +1,2 @@
+export declare function HelloServer(): Promise<import("react").JSX.Element>;
+//# sourceMappingURL=hello-server.d.ts.map

package/dist/lib/hello-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hello-server.d.ts","sourceRoot":"","sources":["../../src/lib/hello-server.tsx"],"names":[],"mappings":"AACA,wBAAsB,WAAW,yCAEhC"}

package/dist/lib/next.d.ts

@@ -0,0 +1,6 @@
+import { Asset, Gallery, AssetProps, GalleryProviderProps as ReactGalleryProviderProps } from '@degallery/react';
+export type GalleryProviderProps = Omit<ReactGalleryProviderProps, 'imageComponent'>;
+export declare function GalleryProvider(props: GalleryProviderProps): import("react").JSX.Element;
+export { Asset, Gallery };
+export type { AssetProps };
+//# sourceMappingURL=next.d.ts.map

package/dist/lib/next.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.d.ts","sourceRoot":"","sources":["../../src/lib/next.tsx"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,EACL,OAAO,EAER,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EACV,UAAU,EAEV,oBAAoB,IAAI,yBAAyB,EAClD,MAAM,kBAAkB,CAAC;AAqB1B,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,yBAAyB,EACzB,gBAAgB,CACjB,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,+BAE1D;AAED,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,23 @@
+import { GalleryProps, GalleryViewData } from '@degallery/react';
+import { ClientOptions } from '@degallery/sdk';
+export type GetGalleryOptions = Pick<ClientOptions, 'apiUrl' | 'fetch' | 'mediaUrl' | 'publishableKey' | 'readToken'> & {
+    galleryIdOrSlug: string;
+    limit?: number;
+};
+/** Fetches the first page of gallery data for a Next.js Server Component. */
+export declare function getGallery({ apiUrl, fetch: fetchImplementation, galleryIdOrSlug, limit, mediaUrl, publishableKey, readToken, }: GetGalleryOptions): Promise<GalleryViewData>;
+export type ServerGalleryProps = GetGalleryOptions & Omit<GalleryProps, 'gallery' | 'galleryId' | 'slug' | 'limit'>;
+/** Loads gallery data on the server, then hydrates the interactive React view. */
+export declare function ServerGallery({ apiUrl, fetch: fetchImplementation, galleryIdOrSlug, limit, mediaUrl, publishableKey, readToken, ...galleryProps }: ServerGalleryProps): Promise<import('react').FunctionComponentElement<Readonly<{
+    gallery?: GalleryViewData;
+    galleryId?: string;
+    slug?: string;
+    className?: string;
+    layout?: import('@degallery/react').GalleryLayout;
+    limit?: number;
+    loadingFallback?: import('react').ReactNode;
+    errorFallback?: import('react').ReactNode;
+    emptyFallback?: import('react').ReactNode;
+    refreshPrivateItems?: (items: GalleryViewData["items"]) => Promise<GalleryViewData["items"]>;
+}>>>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAC;AAIrB,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,aAAa,EACb,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,gBAAgB,GAAG,WAAW,CACjE,GAAG;IACF,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,6EAA6E;AAC7E,wBAAsB,UAAU,CAAC,EAC/B,MAAM,EACN,KAAK,EAAE,mBAAmB,EAC1B,eAAe,EACf,KAAS,EACT,QAAQ,EACR,cAAc,EACd,SAAS,GACV,EAAE,iBAAiB,GAAG,OAAO,CAAC,eAAe,CAAC,CAa9C;AAED,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAChD,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEjE,kFAAkF;AAClF,wBAAsB,aAAa,CAAC,EAClC,MAAM,EACN,KAAK,EAAE,mBAAmB,EAC1B,eAAe,EACf,KAAS,EACT,QAAQ,EACR,cAAc,EACd,SAAS,EACT,GAAG,YAAY,EAChB,EAAE,kBAAkB;;;;;;;;;;;KAgBpB"}

package/dist/server.js

@@ -0,0 +1,40 @@
+import { createElement as e } from "react";
+import { Gallery as t, toGalleryViewData as n } from "@degallery/react";
+import "server-only";
+import { GalleryClient as r } from "@degallery/sdk";
+//#region src/server.ts
+async function i({ apiUrl: e, fetch: t, galleryIdOrSlug: i, limit: a = 9, mediaUrl: s, publishableKey: c, readToken: l }) {
+	let { gallery: u } = await new r({
+		apiUrl: e,
+		fetch: t ?? o,
+		mediaUrl: s,
+		publishableKey: c,
+		readToken: l
+	}).galleries.retrievePage(i, {
+		includeAssets: !0,
+		limit: a
+	});
+	return n(u);
+}
+async function a({ apiUrl: n, fetch: r, galleryIdOrSlug: a, limit: o = 9, mediaUrl: s, publishableKey: c, readToken: l, ...u }) {
+	let d = await i({
+		apiUrl: n,
+		fetch: r,
+		galleryIdOrSlug: a,
+		limit: o,
+		mediaUrl: s,
+		publishableKey: c,
+		readToken: l
+	});
+	return e(t, {
+		...u,
+		gallery: d,
+		galleryId: d.id
+	});
+}
+var o = (e, t) => fetch(e, {
+	...t,
+	cache: "no-store"
+});
+//#endregion
+export { a as ServerGallery, i as getGallery };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@degallery/next",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "type": "module",
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@degallery/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "@degallery/source": "./src/server.ts",
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js",
+      "default": "./dist/server.js"
+    }
+  },
+  "dependencies": {
+    "@degallery/react": "0.6.0",
+    "@degallery/sdk": "0.6.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.102.8",
+    "next": ">=15 <17",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
 }