Add Initial documentation and usage instructions

README.md

@@ -1,51 +1,20 @@
 # NEXT JS w. VEDA UI
 
-This is a test NEXT JS instance to understand the requirement for [VEDA-UI](https://github.com/nasa-IMPACT/veda-ui) to be used with a NEXT JS instance.
+Next.js instance that uses the [VEDA-UI components library](https://github.com/nasa-IMPACT/veda-ui) and [USWDS](https://designsystem.digital.gov/), to build applications for geospatial data visualization, storytelling and analysis.
 
-This repo is based on Portfolio Blog starter from NEXT JS: <https://portfolio-blog-starter.vercel.app>
+## Getting Started
 
-## Installation and Usage
+To set up and run this project locally, refer to the [Development guide](./docs/DEVELOPMENT.md).
 
-### Install Project Dependencies
+## Documentation
 
-Ensure the following are installed on your system:
+Documentation for this project can be found in the [`docs`](./docs) directory. Below is a quick summary of available resources:
 
-- [Node.js](http://nodejs.org/) (version is specified in the [.nvmrc](.nvmrc) file)
-- [Yarn](https://yarnpkg.com/)
-
-If you’re using [`nvm`](https://github.com/creationix/nvm), activate the required Node.js version by running:
-
-```sh
-nvm install
-```
-
-### Register the VEDA-UI Package
-
-The `VEDA-UI` package is hosted on a Verdaccio instance during its experimental phase. To successfully install it, you must scope `@developmentseed/veda-ui` to the Verdaccio instance.
-
-Run the following command before installing other dependencies:
-
-```sh
-yarn config set @developmentseed:veda-ui http://verdaccio.ds.io:4873/
-```
-
-### Install Dependencies
-
-Install the project dependencies by running:
-
-```sh
-yarn install
-```
-
-### Start the Development Server
-
-To start the development server, run:
-
-```sh
-yarn dev
-```
-
-The website will then be accessible at <http://localhost:3000>.
+1. [How to Run / Development](./docs/DEVELOPMENT.md)
+2. [Overview of Architecture](./docs/ARCHITECTURE_OVERVIEW.md)
+3. [Configuration](./docs/CONFIGURATION.md)
+4. [Veda-UI Components](./docs/VEDA_UI_COMPONENTS.md)
+5. [STYLING / USWDS](./docs/STYLING.md)
 
 ## License
 

docs/ARCHITECTURE_OVERVIEW.md

@@ -0,0 +1,36 @@
+# Overview of architecture
+
+This document provides a high-level overview of the architecture for the Next.js instance integrated with VEDA-UI.
+
+## Core structure
+
+The project follows the modern Next.js file structure as documented in the [Next.js documentation](https://nextjs.org/docs/app/building-your-application). Key directories include:
+
+### `app/`
+- Contains the application’s core pages, layouts, and routes
+- **Structure**: Each folder under `app/` corresponds to a route in the application
+  Example: `app/about/page.tsx` maps to `/about`
+
+### `components/`
+- Stores reusable React components for the app
+
+### `content/`
+- Holds structured content, such as datasets, stories, or other resources used by the app
+
+### `lib/`
+- Serves as a centralized module for importing and exporting components, hooks, and utilities from `@developmentseed/veda-ui` that are used across the application
+
+### `store/`
+- **Purpose**: Manages application-level state using React context providers
+
+### `styles/`
+- Includes global styles and theme configurations.
+    - **Global styles**: `styles/index.scss` applies general app-wide styles
+    - **Theme styles**: `_uswds-theme.scss` is the configuration for the U.S. Web Design System (USWDS) specific for this app
+
+For details on how USWDS components and styles are used in the project, refer to the [Styling guide](./STYLING.md).
+
+### `utilities/hooks/`
+- Custom React hooks to enhance reusability and abstraction of logic
+
+For detailed instructions on setting up and running the project, refer to the [Development guide](./DEVELOPMENT.md).

docs/CONFIGURATION.md

@@ -0,0 +1,56 @@
+This document provides details on how to configure the application, manage environment variables, and use the VEDA UI configuration provider.
+
+## Environment variables
+
+The application uses `.env` and `.env.local` files to manage environment variables. Below is a breakdown of the variables used in the application:
+
+### `.env` variables
+
+The following variables are used to configure the API endpoints for the application:
+
+- **`NEXT_PUBLIC_API_STAC_ENDPOINT`**
+    Defines the endpoint for accessing the STAC API
+
+    Example:
+    ```env
+    NEXT_PUBLIC_API_STAC_ENDPOINT='https://openveda.cloud/api/stac'
+    NEXT_PUBLIC_API_RASTER_ENDPOINT='https://openveda.cloud/api/raster'
+    ```
+
+These variables are committed to the repository as they are not sensitive and are used for public API access.
+
+### `.env variables`
+
+These variables are used for local development and are specific to each developer’s environment. These variables are not committed to version control.
+
+The repository includes a sample `.env.local.sample` file to guide developers in setting these up. Please copy this file, rename it to .env.local and fill it with the required credentials and tokens.
+
+### Using environment variables in code
+
+The `VedaUIProvider` is part of the `@developmentseed/veda-ui` library and is used to pass environment variables to VEDA-UI components. This is needed so that VEDA components relying on configurations like API endpoints and Mapbox tokens can access these values.
+
+#### Where to place it
+
+The `VedaUIProvider` should wrap your application at a high level, such as in the `RootLayout` or a similar layout component, so that all VEDA-UI components within the application have access to the provided configurations.
+
+#### Example usage
+
+Below is an example of how to configure the `VedaUIProvider` with environment variables:
+
+```tsx
+import { VedaUIProvider } from '@developmentseed/veda-ui';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <VedaUIProvider
+      config={{
+        envMapboxToken: process.env.NEXT_PUBLIC_MAPBOX_TOKEN ?? '',
+        envApiStacEndpoint: process.env.NEXT_PUBLIC_API_STAC_ENDPOINT ?? '',
+        envApiRasterEndpoint: process.env.NEXT_PUBLIC_API_RASTER_ENDPOINT ?? '',
+      }}
+    >
+      {children}
+    </VedaUIProvider>
+  );
+}
+```

docs/DEVELOPMENT.md

@@ -0,0 +1,68 @@
+This guide provides instructions for setting up and running the Next.js instance locally, as well as an overview of the development workflow.
+
+## Prerequisites
+
+Before you begin, ensure the following are installed on your system:
+
+- [Node.js](https://nodejs.org/) (version specified in the [.nvmrc](../.nvmrc) file)
+- [Yarn](https://yarnpkg.com/)
+
+If you're using [`nvm`](https://github.com/nvm-sh/nvm), you can activate the required Node.js version by running:
+
+```bash
+nvm install
+```
+
+## Setting up the project
+
+1. **Clone the repository**
+    Clone the repository to your local machine:
+
+    ```bash
+    git clone https://github.com/your-org/your-repo.git
+    cd your-repo
+    ```
+
+2. **Register the VEDA-UI package**
+    The VEDA-UI package is hosted on a Verdaccio instance during its experimental phase. To install it, configure Yarn to use the Verdaccio instance:
+
+    ```sh
+    yarn config set @developmentseed:veda-ui http://verdaccio.ds.io:4873/
+    ```
+
+3. **Install dependencies**
+
+    Install the project dependencies by running:
+
+    ```sh
+    yarn install
+    ```
+
+4. **Configure environment variables**
+
+    Create a `.env.local` file in the root directory and add the necessary environment variables. Refer to the [Configuration guide](./CONFIGURATION.md) for details on required variables.
+
+### Start the development server
+
+To start the development server, run:
+
+```sh
+yarn dev
+```
+
+The website will then be accessible at <http://localhost:3000>.
+
+### Building for production
+
+To build the project for production:
+
+```bash
+yarn build
+```
+
+The output will be generated in the `.next` directory.
+
+### Deployment
+
+The app can be deployed to any platform supporting Node.js. Refer to your deployment platform's documentation for further instructions.
+

docs/STYLING.md

@@ -0,0 +1,79 @@
+# Styling and theming
+
+This guide explains how to set up and customize styles for the application which uses the U.S. Web Design System (USWDS) as a foundation. The application can integrate with `veda-ui` for core feature components styled with USWDS or use `react-uswds` for standalone UI elements like buttons, inputs, modals, etc.
+
+The application is designed to support the USWDS styling framework for consistent and accessible design.
+
+## Setup requirements
+
+To use USWDS-based styles:
+
+1. **Install Required Dependencies**
+
+    Make sure `@uswds/uswds` and `sass` are installed:
+
+    ```bash
+    npm install @uswds/uswds@^3.8.1 sass
+    # or
+    yarn add @uswds/uswds@^3.8.1 sass
+    ```
+
+2. **Configure SASS**
+
+   Update your `sassOptions` in the `next.config.js` file to include the necessary USWDS paths. This allows SASS to resolve and process the USWDS styles correctly:
+
+   ```js
+   module.exports = {
+     sassOptions: {
+       includePaths: [
+         'node_modules/@uswds/uswds',
+         'node_modules/@uswds/uswds/dist',
+         'node_modules/@uswds/uswds/packages',
+       ],
+     },
+   };
+   ```
+
+3. **Import and customize styles**
+
+    Create a custom theme configuration file (e.g., `app/styles/_uswds-theme.scss`) to define your application's tokens such as colors, typography, and asset paths. This file allows you to adapt USWDS to your application's branding and design needs.
+
+    Example `_uswds-theme.scss`:
+
+    ```scss
+    @use 'uswds-core' with (
+        $theme-image-path: '/img',
+        $theme-font-path: '/fonts',
+        $theme-show-notifications: false,
+        $utilities-use-important: true,
+        $theme-font-weight-semibold: '600',
+        $theme-type-scale-md: 8,
+        $theme-color-primary: 'blue-50',
+        $theme-color-secondary: 'gold-30'
+    );
+    ```
+
+    Import your theme and other USWDS styles into a main SCSS file (e.g., `app/styles/index.scss`) to be used in your application.
+
+    ```scss
+    @forward 'uswds-theme';
+    @forward 'uswds';
+
+    @use 'uswds-core' as *;
+    ```
+
+4. **Include styles in the application**
+
+    Import the SCSS file into the root of your application to apply the styles globally:
+
+    ```tsx
+    import './styles/index.scss';
+    import '@developmentseed/veda-ui/lib/main.css';
+    ```
+
+
+
+
+
+
+

docs/VEDA_UI_COMPONENTS.md

@@ -0,0 +1,31 @@
+# VEDA-UI components
+
+This document provides guidance on how to use and integrate VEDA-UI components into your application.
+
+VEDA-UI offers a collection of components, hooks, and state management tools to support geospatial visualization, storytelling, and analysis. These are designed to be both reusable and customizable.
+
+## Available components and features
+
+The most up-to-date list of components, hooks, and types offered by VEDA-UI can be found in the [VEDA-UI `index.ts` file](https://github.com/NASA-IMPACT/veda-ui/blob/main/app/scripts/index.ts). This file serves as the single source of truth for all available features and their respective imports.
+
+## Example usage
+
+To use a VEDA-UI component, import it from the library and include it in your application. For example:
+
+```tsx
+import { PageHero, CatalogView } from '@developmentseed/veda-ui';
+
+export default function ExamplePage() {
+  return (
+    <div>
+      <PageHero title="Explore Datasets" subtitle="Discover insights from geospatial data." />
+      <CatalogView datasets={[...]} />
+    </div>
+  );
+}
+```
+
+# Customization and styling
+
+All components follow USWDS-based theming and can be customized through SCSS or by overriding default styles. For detailed styling guidance, refer to the [Styling guide](./STYLING.md).
+