ALTADENA COLLECTIVE - MAP PACKAGE

DON'T TOUCH ANYTHING!

I'm halfway kidding ->
For real though...

CORE FILES

There are four key folders that this package consists of:
- /scripts/init => installation file to get the right folders / files into the right spot in main app.
- /src => vite/react frontend - contains UI / components / logic for displaying the map.
- /map => core map logic for processing and structuring map related data
- /seed => contains original geojson data from local government - used to build initial Altadena Map Files

OUT OF ALL THESE FILES YOU GENERALLY SHOULD NOT BE CHANGING ANY OF THEM EXCEPT FOR THE /map/map.js FILE! A more detailed README.md can be found in /map to express specific notes for that specific folder / set of files. Otherwise, the descriptions below give a little more detail so that you can figure out where you need to accomplish a task. IT IS HIGHLY LIKELY ANY CHANGES YOU NEED WILL BE IN /map/map.js

/SCRIPTS/INIT.JS

The init.js file's job is to transform raw, government, GeoJSON data related to the Altadena and Palisades Fire Events into a set of json files that will allow us to display that data in a mapbox map so that users can manipulate and view the layers in a beneficial way. Once this package is added to the main project and then pushed to the server, this INIT.JS file will need to be run ONCE - ON THE SERVER - to get the system started / working properly.

This process will:
1. Load the original GeoJSON Datasets
2. Extract the detailed parcel information.
3. Generate appropriate datasets (base-source, master-source, master-index, rejectedParcels, history.jsonl, 1st history-entry).
4. Generate layers and bins in base / master sources for displaying the in the mapbox map.

YOU DO NOT RUN INIT.JS AGAIN AFTER THE FIRST TIME
YOU MUST RUN THIS INIT FILE ONCE ON THE SERVER, AFTER UPLOADING THE PACKAGE TO THE SERVER!

/src

This folder houses all of the components, hooks, functions necessary to display the layers and data from our geojson data files. Outside of altering CSS (GO FOR IT!) - you should not be altering any of the files, functions otherwise. The only file of note is the /src/App/mapbox-functions.js. This file houses all logic related to mapbox and getting the data loaded / displayed.

/map/map.js

This file is the brains of the map system. The Classes and built-in methods in this file represent the entire operation. The way the information is stored, structured, and processed so that data sources, layers and their properties / bins can show up on the map.

It is the only file that needs to change if you want to add / change layers / data that is displayed to a user or a non-user. (A person with or w/o an account). The README.md file in the /map folder will explain which items can be altered and multiple places say what to stay away from!

/map/update.js

This file's purpose is to update the datasets(3) related to the map. This file should be called within the main project's update function for adding a BuildNote or making any update to information about a specific property. The function accepts an array of updates and will handle all of the rest of the work. Do not touch this file.

The update pipeline is setup to only run through the process of updating data IF one of the following items has changed:
- layer changes - adding / removing a layer property in /map/map.js in one of the two FeatureCollection types.
- schema property changes - altering which properties are part of a FeatureCollection sub-class (base or master) in /map/map.js.
- parcel changes - updates to data related to a user's 'parcel' (the 'property / land' they own) if it exists in the dataset.

This means that even if the updates array being passed into the function is empty -> updates = []... the system will still check for internal changes to see if any update needs to be made. If no changes, data is left alone. This is the only way in which updates are triggered currently. If you need to trigger it intentionally - just call the update function. If there are changes - it will do its job!

INSTALLATION:

This package's installation is extremely simple. For this package to work properly all that needs to be done is to install the package, run the init file, import and use the map component to display the data.

STEP BY STEP

The init file (/scripts/init.js) is a pipeline that checks and accomplishes:
- ENSURES react is installed in main application and has the appropriate folders needed for the map
- GENERATES a /src/map folder (in react, if it does not exist)... to store map related assets
- RUNS the initial seed function and creates all necessary files in project /src/map && package /map folders.
- COPIES local /map to a newly created main application /map to include all necessary files.

1. Install: npm i altadena-map
2. Initialize: npx altadena-map
3. Display:
1. Import Data Sources
2. Import Map Component
3. Pass Data to Map Component: (data sources and user)

``js
// IMPORT DATA SOURCES && MAP COMPONENT
// init script should generate a "./src/map" folder -> point to this folder!
import { baseSource, masterSource } from './map';
import { AltadenaMap } from 'altadena-map';
const MAP_TOKEN = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN || "token info here" // this should be directly passed in as a copy/paste string from Patrick D's mapbox token..

// USE COMPONENT AND PASS DATA SOURCES AND USER:

// ^^^ YOU MUST PASS IN THOSE VARIABLE NAMES ^^^
// if you do not pass in a user it assumes a truthy value and will display everything!!
``