diff --git a/docs/index.md b/docs/index.md index d3d807d..9c0918b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,6 +28,10 @@ Information about the parts of the WROLPi interface. * [Docs](modules/docs/index.md) * [Map](modules/map/index.md) * [Zim](modules/zim/index.md) +* [Inventory](modules/inventory/index.md) + * [Summary](modules/inventory/summary.md) + * [Ration](modules/inventory/ration.md) + * [Export](modules/inventory/export.md) ## Guiding Principals diff --git a/docs/modules/inventory/count-by-weight.png b/docs/modules/inventory/count-by-weight.png new file mode 100644 index 0000000..941450e Binary files /dev/null and b/docs/modules/inventory/count-by-weight.png differ diff --git a/docs/modules/inventory/export.md b/docs/modules/inventory/export.md new file mode 100644 index 0000000..515ed6e --- /dev/null +++ b/docs/modules/inventory/export.md @@ -0,0 +1,11 @@ +# Export + +The **Export** tab produces a copy of the [inventory](index.md) you can use elsewhere. + +![inventory-export.png](inventory-export.png) + +* **CSV** — a comma-separated spreadsheet of every item and field, openable in Excel, Numbers, or Google Sheets. + It is generated entirely on your device. +* **PDF** — a printable table of the whole inventory followed by a summary grouped by the field you choose. This + opens your browser's print dialog; choose "Save as PDF" as the destination to get a PDF file, or print it on + paper. diff --git a/docs/modules/inventory/field-schema-editor.png b/docs/modules/inventory/field-schema-editor.png new file mode 100644 index 0000000..ec0f6f2 Binary files /dev/null and b/docs/modules/inventory/field-schema-editor.png differ diff --git a/docs/modules/inventory/food-catalog.png b/docs/modules/inventory/food-catalog.png new file mode 100644 index 0000000..9c4b4f0 Binary files /dev/null and b/docs/modules/inventory/food-catalog.png differ diff --git a/docs/modules/inventory/index.md b/docs/modules/inventory/index.md new file mode 100644 index 0000000..024da46 --- /dev/null +++ b/docs/modules/inventory/index.md @@ -0,0 +1,126 @@ +# Inventory + +## Overview + +The Inventory module helps you track physical supplies — food storage, fuel, tools, or anything else you want to +count and organize. The main page (`/inventory`) is a spreadsheet-style table where each row is an item and each +column is a field you control. + +You can keep as many separate inventories as you like (for example, a "Food Storage" inventory and a "Fasteners" +inventory), each with its own set of fields. Inventories are stored as plain configuration files, so they survive +reboots and can be backed up, edited, or restored like any other WROLPi config (see +[Where Data Is Stored](#where-data-is-stored)). + +![inventory-page.png](inventory-page.png) + +A new WROLPi comes with a starter **Food Storage** inventory pre-filled with a recommended one-adult, one-year +supply, so you have an example to explore right away. + +Each inventory has four tabs: **Items** (covered on this page), **[Summary](summary.md)**, +**[Ration](ration.md)**, and **[Export](export.md)**. + +## Inventory Types + +When you create an inventory you pick a **type**. The type seeds a starting set of fields — you can add, remove, +rename, reorder, or retype them afterward, so the type is only a convenient starting point. + +* **Food Storage** — Brand, Name, Category, Subcategory, Size, Count, kcal per unit, and Expires. +* **Fuel** — Name, Fuel Type, Container, Size, Count, Purchased, and Location. +* **Tools** — Name, Brand, Category, Count, Condition, Location, and Notes. + +To create an inventory, click the **+** button, enter a name, choose a type, and click **Create**. + +![new-inventory-modal.png](new-inventory-modal.png) + +Use the dropdown at the top of the page to switch between inventories. The buttons beside it let you rename the +current inventory (the pencil), customize its [Fields](#customizing-fields), open the +[Food Catalog](#food-catalog), or delete the inventory (the red trash button). + +## Adding Items + +The **Items** tab holds a persistent empty row at the bottom of the table for entering new items. Entry is +keyboard-first: + +* **Tab** moves between the fields of the new row. +* **Enter** saves the item, clears the row, and returns focus to the first field — ready for the next item. + +This lets you add many items in a row without reaching for the mouse. + +### Editing and Deleting Items + +* **Click any cell** in an existing row to edit it. The cell's current contents are selected so you can type over + them immediately. +* **Bulk delete** — select the checkboxes on the rows you want to remove, then click the delete button. + +### Searching + +A search box at the top of the **Items** tab filters the rows by any field. The filter only applies to the Items +tab — the [Summary](summary.md), [Ration](ration.md), and [Export](export.md) tabs always use the whole inventory, +so the filter never silently hides data from your totals. + +### Arithmetic in Number Fields + +Any numeric field (a number, a quantity's magnitude, or calories) accepts a calculation. For example, to record a +box of nails that weighs 400 g including a 20 g box, type `400 - 20` and press **Tab** or **Enter** — WROLPi +evaluates it and stores `380`. Only basic arithmetic (`+ - * / ( )`) is supported; a plain number is left +untouched. + +## Customizing Fields + +Click the **Fields** button to open the field editor, where you control the columns of the current inventory. + +![field-schema-editor.png](field-schema-editor.png) + +For each field you can set its **Label**, **Type**, reorder it with the up/down arrows, toggle whether it appears +in the [mobile view](#mobile-view), or remove it. Use **Add Field** for a blank field. + +### Field Types + +* **Text** — free-form text. +* **Number** — a number (accepts [arithmetic](#arithmetic-in-number-fields)). +* **Quantity** — a number plus a unit chosen from a dropdown (mass, volume, or length). The + [Summary](summary.md) can sum and convert compatible quantities (for example, ounces and pounds together). +* **Date** — a calendar date. Items with a date in the past are flagged as expired. +* **Select** — a dropdown of options you define (enter them comma-separated, e.g. `screws,nails,bolts`). +* **Location** — a text field with autocomplete suggestions pooled from every inventory (basement, attic, …). +* **Calories** — calories per unit; detected by the [Ration](ration.md) estimate and the [Summary](summary.md). + +### Count by Weight + +Counting many small, identical items (screws, nails, rounds of ammunition) one by one is tedious. The **Count by +Weight** button adds three linked fields: + +* **Unit Weight** — the weight of a single item (weigh one, or weigh four and enter `÷ 4` as + [arithmetic](#arithmetic-in-number-fields)). +* **Total Weight** — the weight of the whole lot. +* **Count** — automatically calculated as Total Weight ÷ Unit Weight, rounded to a whole number. + +Enter the two weights and the **Count** fills in for you. If the weights use different units (e.g. a total in +kilograms and a unit weight in grams), WROLPi converts before dividing. + +![count-by-weight.png](count-by-weight.png) + +## Food Catalog + +The **Catalog** button opens a shared list of known food items used to speed up data entry. Each catalog entry +records a name, category, subcategory, package size, and the total calories for one package of that size. + +![food-catalog.png](food-catalog.png) + +When you type a **Name** in a food inventory that matches a catalog entry, WROLPi pre-fills the matching fields +(category, size, calories, …) for you. The catalog is shared across all of your inventories. + +## Mobile View + +On a phone held in portrait orientation, the Items tab shows a condensed, read-only list of your items. Rotate to +landscape (or use a tablet or desktop) for the full spreadsheet editor. You choose which fields appear in the +mobile view with the **Mobile** toggle in the [Fields](#customizing-fields) editor. + +![inventory-mobile.png](inventory-mobile.png) + +## Where Data Is Stored + +Each inventory is stored as its own configuration file at `config/inventory/.yaml` in your media directory. +These configs are the source of truth: WROLPi loads them on startup and keeps them up to date as you make changes. +You can back them up, copy them between WROLPi systems, or edit them by hand — your changes are applied the next +time WROLPi reads the file. diff --git a/docs/modules/inventory/inventory-export.png b/docs/modules/inventory/inventory-export.png new file mode 100644 index 0000000..1fb33a8 Binary files /dev/null and b/docs/modules/inventory/inventory-export.png differ diff --git a/docs/modules/inventory/inventory-mobile.png b/docs/modules/inventory/inventory-mobile.png new file mode 100644 index 0000000..c0083b8 Binary files /dev/null and b/docs/modules/inventory/inventory-mobile.png differ diff --git a/docs/modules/inventory/inventory-page.png b/docs/modules/inventory/inventory-page.png new file mode 100644 index 0000000..da7ce5d Binary files /dev/null and b/docs/modules/inventory/inventory-page.png differ diff --git a/docs/modules/inventory/inventory-summary.png b/docs/modules/inventory/inventory-summary.png new file mode 100644 index 0000000..2b01b2c Binary files /dev/null and b/docs/modules/inventory/inventory-summary.png differ diff --git a/docs/modules/inventory/new-inventory-modal.png b/docs/modules/inventory/new-inventory-modal.png new file mode 100644 index 0000000..0f82c4a Binary files /dev/null and b/docs/modules/inventory/new-inventory-modal.png differ diff --git a/docs/modules/inventory/ration-estimate.png b/docs/modules/inventory/ration-estimate.png new file mode 100644 index 0000000..e76b9af Binary files /dev/null and b/docs/modules/inventory/ration-estimate.png differ diff --git a/docs/modules/inventory/ration.md b/docs/modules/inventory/ration.md new file mode 100644 index 0000000..61c0cd4 --- /dev/null +++ b/docs/modules/inventory/ration.md @@ -0,0 +1,25 @@ +# Ration Estimate + +When an [inventory](index.md) has a [calories field](index.md#field-types), a **Ration** tab appears. It estimates +how long your stored food will last a household. + +![ration-estimate.png](ration-estimate.png) + +* **People** — enter how many men, women, and children are in the household. +* **Daily Calories** — pick an activity level preset (Sedentary, Moderately Active, Active, or Survival), or edit + the per-person daily calorie figures directly. The defaults come from the Dietary Guidelines for Americans + 2020-2025. + +WROLPi then shows your **Total Stored Calories**, the household's **Daily Demand**, and how long the food +**Lasts**. + +## Plan More Supply + +Below the estimate, drag the slider to a target duration longer than your current supply to generate a shopping +list. WROLPi scales the whole inventory up proportionally — every item grows by the same factor so the mix stays +balanced — and rounds any split package up to a whole one. The result is a sortable table of how many additional +packages of each item to buy to reach the target. + +![supply-plan.png](supply-plan.png) + +The shopping list can be downloaded as a CSV or printed/saved as a PDF. diff --git a/docs/modules/inventory/summary.md b/docs/modules/inventory/summary.md new file mode 100644 index 0000000..30862c1 --- /dev/null +++ b/docs/modules/inventory/summary.md @@ -0,0 +1,12 @@ +# Summary + +The **Summary** tab aggregates the [inventory](index.md) entirely on your device. Choose a field to **Group by** +(such as Category) and a field to **Sum** (such as Size or Count). Quantities are summed with unit conversion and +compacted to a sensible unit (for example, 16 oz + 1 lb is shown as 2 lb). If the inventory has a +[calories field](index.md#field-types), a **Calories** column shows the stored calories per group. Click any column +header to sort. + +![inventory-summary.png](inventory-summary.png) + +Unlike the [Items](index.md#searching) tab's search, the Summary always uses the whole inventory, so the totals +here are never narrowed by a filter. diff --git a/docs/modules/inventory/supply-plan.png b/docs/modules/inventory/supply-plan.png new file mode 100644 index 0000000..064317e Binary files /dev/null and b/docs/modules/inventory/supply-plan.png differ diff --git a/docs/modules/map/index.md b/docs/modules/map/index.md index f0b7e3f..70f601c 100644 --- a/docs/modules/map/index.md +++ b/docs/modules/map/index.md @@ -38,6 +38,26 @@ https://your-wrolpi/map?lat=45.5231&lon=-122.6765&z=12 Share this URL to link someone directly to a specific location and zoom level. +### Search + +Type in the search box at the top center of the map to find places by name. + +- **Place search** — Type a city, town, park, or region name. Results appear in a dropdown + showing the place name, administrative region (e.g., "Oregon"), and population. +- **Coordinate search** — Type coordinates like `45.5, -122.6` to navigate directly to + that location. +- **Proximity bias** — Results are sorted by proximity to your current map view, so nearby + places appear first. +- **Prefix matching** — Typing partial names works (e.g., "Port" finds "Portland"). +- **Fuzzy fallback** — If no exact match is found, a broader substring search is attempted. + +Click a result to fly to that location with a marker and popup. Press Escape to close the +dropdown. + +> Search data is extracted from the same PMTiles map files you already have. No additional +> downloads are needed. When search indexes include Wikidata enrichment, results show +> administrative regions (state/province) to help distinguish places with the same name. + ## Pins Tab Map pins let you mark and name important locations. Pins are stored in `map_pins.yaml` @@ -64,7 +84,17 @@ The Manage tab has two sections: ### Map Files Lists all `.pmtiles` files in your media directory under `/map`. Shows the file name, size, -and modification time. Files can be deleted from here. +search index status, and a delete button. Files can be deleted from here. + +The **Search** column shows whether a search index exists for each file: + +- **Built** (green) — A search index exists. Place search is available for this file. +- **Build** (button) — No search index yet. Click to generate one using `tippecanoe-decode`. + If WROL Mode is not active, the index will also be enriched with region names from Wikidata. + +> Search indexes are small SQLite databases (typically 1-4 MB per region) stored alongside +> the PMTiles file with a `.search.db` extension. They are created automatically when you +> download a region via subscriptions, or you can build them manually with the Build button. ### Map Subscriptions @@ -90,6 +120,8 @@ When you subscribe to a region: is authentic and untampered 5. The file is placed in your map directory with a versioned filename (e.g., `us-west-20260329.pmtiles`) +6. A pre-built search index (`.search.db`) is downloaded from the CDN, also with + GPG-signed hash verification. This provides instant place search with region names. > Downloads are integrity-verified at multiple levels: the manifest is GPG-signed, > each file's SHA-256 hash is GPG-signed in its meta4 file, and aria2c verifies @@ -169,3 +201,12 @@ Once a terrain file is detected, two additional layer groups appear in the Layer > Terrain layers are hidden by default to keep the map clean. Enable them in the Layer Control > when you need elevation information. + +## Global Search + +Map places also appear in WROLPi's global search. When you search from the navigation bar: + +- The **Map** tab shows the number of matching map places alongside Files, Zims, and Other +- Clicking the Map tab displays results as cards with mini map previews showing each location +- Click a card to navigate to that location on the map page +- Results are paginated (12 per page) with the same region and population information