topographic-react 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yahya Bedirhan Pak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# topographic-react
 
-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.
+[![npm](https://img.shields.io/npm/v/topographic-react)](https://www.npmjs.com/package/topographic-react)
+
+Try it live in the [playground](https://yahyabedirhan.github.io/topographic/).
+
+React bindings for [`topographic`](https://www.npmjs.com/package/topographic), the JavaScript library for topographic backgrounds. It works with React 18 and 19 and is safe for server rendering.
+
+```sh
+npm install topographic topographic-react
+```
+
+```tsx
+import { TopographicBackground } from 'topographic-react';
+
+export function Hero() {
+  return (
+    <TopographicBackground styleName="granite" terrain={{ roughness: 0.3 }} style={{ height: '100vh' }}>
+      <h1>Hello</h1>
+    </TopographicBackground>
+  );
+}
+```
+
+For the 3D terrain, add `mode="3d"`, and optionally `elevation`, `extent`, `detail` and `camera`.
+
+To put the background on your own element, use `useTopographicBackground(settings)`, which returns a ref.
+
+- [Project README](https://github.com/yahyabedirhan/topographic#readme)
+- [Guide](https://github.com/yahyabedirhan/topographic/blob/main/docs/guide.md)
+
+MIT licence.

package/dist/TopographicBackground.d.ts

@@ -0,0 +1,33 @@
+import { type HTMLAttributes, type MutableRefObject } from 'react';
+import { type RendererOptions, type SettingsInput, type TopographicBackground as TopographicBackgroundInstance } from 'topographic';
+export interface TopographicBackgroundSettingsProps {
+    /** Style id, e.g. 'dunes'. Named styleName because `style` is React's inline style prop. */
+    styleName?: string;
+    seed?: number;
+    lines?: SettingsInput['lines'];
+    terrain?: SettingsInput['terrain'];
+    motion?: SettingsInput['motion'];
+    layout?: SettingsInput['layout'];
+    theme?: SettingsInput['theme'];
+    /** '2d' is the map. '3d' is the same map as a terrain. */
+    mode?: SettingsInput['mode'];
+    elevation?: number;
+    extent?: SettingsInput['extent'];
+    detail?: number;
+    camera?: SettingsInput['camera'];
+}
+export interface TopographicBackgroundRef<T extends HTMLElement = HTMLDivElement> extends MutableRefObject<T | null> {
+    /** The live instance while mounted (for snapshot, or imperative updates). */
+    topographic: TopographicBackgroundInstance | null;
+}
+/** Attaches a topographic to the element you put the returned ref on. */
+export declare function useTopographicBackground<T extends HTMLElement = HTMLDivElement>(settings?: TopographicBackgroundSettingsProps, options?: RendererOptions): TopographicBackgroundRef<T>;
+export interface TopographicBackgroundProps extends TopographicBackgroundSettingsProps, Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Renderer options (pixel budget, WebGL1). Changing them recreates the renderer. */
+    options?: RendererOptions;
+    /** Called with the instance after mount, and with null on unmount. */
+    onReady?: (topographic: TopographicBackgroundInstance | null) => void;
+    children?: React.ReactNode;
+}
+/** A <div> with a topographic background. Size it like any div; children render on top. */
+export declare const TopographicBackground: import("react").ForwardRefExoticComponent<TopographicBackgroundProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/TopographicBackground.js

@@ -0,0 +1,98 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { forwardRef, useEffect, useRef, useState } from "react";
+import { createTopographicBackground } from "topographic";
+const key = (v) => v === void 0 ? "" : JSON.stringify(v);
+function useByValue(value) {
+  const [kept, setKept] = useState(value);
+  if (key(kept) === key(value)) return kept;
+  setKept(value);
+  return value;
+}
+function useTopographicBackground(settings = {}, options) {
+  const [ref] = useState(() => ({ current: null, topographic: null }));
+  const latest = useRef(settings);
+  latest.current = settings;
+  const stableOptions = useByValue(options);
+  useEffect(() => {
+    if (!ref.current) return;
+    const { styleName: styleName2, ...rest } = latest.current;
+    const t = createTopographicBackground(ref.current, { ...rest, style: styleName2 }, stableOptions);
+    ref.topographic = t;
+    return () => {
+      t.destroy();
+      ref.topographic = null;
+    };
+  }, [ref, stableOptions]);
+  const { styleName, seed, mode, elevation, extent, detail } = settings;
+  const lines = useByValue(settings.lines);
+  const terrain = useByValue(settings.terrain);
+  const motion = useByValue(settings.motion);
+  const layout = useByValue(settings.layout);
+  const theme = useByValue(settings.theme);
+  const camera = useByValue(settings.camera);
+  useEffect(() => {
+    if (styleName !== void 0) ref.topographic?.update({ style: styleName });
+  }, [ref, styleName]);
+  useEffect(() => {
+    if (seed !== void 0) ref.topographic?.update({ seed });
+  }, [ref, seed]);
+  useEffect(() => {
+    if (lines) ref.topographic?.update({ lines });
+  }, [ref, lines]);
+  useEffect(() => {
+    if (terrain) ref.topographic?.update({ terrain });
+  }, [ref, terrain]);
+  useEffect(() => {
+    if (motion) ref.topographic?.update({ motion });
+  }, [ref, motion]);
+  useEffect(() => {
+    if (layout) ref.topographic?.update({ layout });
+  }, [ref, layout]);
+  useEffect(() => {
+    if (theme) ref.topographic?.update({ theme });
+  }, [ref, theme]);
+  useEffect(() => {
+    if (mode !== void 0) ref.topographic?.update({ mode });
+  }, [ref, mode]);
+  useEffect(() => {
+    if (elevation !== void 0) ref.topographic?.update({ elevation });
+  }, [ref, elevation]);
+  useEffect(() => {
+    if (extent !== void 0) ref.topographic?.update({ extent });
+  }, [ref, extent]);
+  useEffect(() => {
+    if (detail !== void 0) ref.topographic?.update({ detail });
+  }, [ref, detail]);
+  useEffect(() => {
+    if (camera) ref.topographic?.update({ camera });
+  }, [ref, camera]);
+  return ref;
+}
+const TopographicBackground = forwardRef(function TopographicBackground2({ styleName, seed, lines, terrain, motion, layout, theme, mode, elevation, extent, detail, camera, options, onReady, style, children, ...div }, forwarded) {
+  const ref = useTopographicBackground({ styleName, seed, lines, terrain, motion, layout, theme, mode, elevation, extent, detail, camera }, options);
+  const stableOptions = useByValue(options);
+  const ready = useRef(onReady);
+  ready.current = onReady;
+  useEffect(() => {
+    ready.current?.(ref.topographic);
+    return () => ready.current?.(null);
+  }, [ref, stableOptions]);
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      ...div,
+      style: { position: "relative", ...style },
+      ref: (node) => {
+        ref.current = node;
+        if (typeof forwarded === "function") forwarded(node);
+        else if (forwarded) forwarded.current = node;
+      },
+      children: children !== void 0 && /* @__PURE__ */ jsx("div", { style: { position: "absolute", inset: 0 }, children })
+    }
+  );
+});
+export {
+  TopographicBackground,
+  useTopographicBackground
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { TopographicBackground, useTopographicBackground, type TopographicBackgroundProps, type TopographicBackgroundSettingsProps, type TopographicBackgroundRef } from './TopographicBackground.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+import { TopographicBackground, useTopographicBackground } from "./TopographicBackground.js";
+export {
+  TopographicBackground,
+  useTopographicBackground
+};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "topographic-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "React component and hook for topographic backgrounds.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yahyabedirhan/topographic.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://yahyabedirhan.github.io/topographic/",
+  "bugs": {
+    "url": "https://github.com/yahyabedirhan/topographic/issues"
+  },
+  "keywords": [
+    "topography",
+    "topographic",
+    "contour",
+    "background",
+    "webgl",
+    "shader",
+    "animated-background",
+    "react"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "topographic": "^0.2.0"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}