From 3660d31287b02f86472b85201914f6126fd8bc12 Mon Sep 17 00:00:00 2001 From: Juano Date: Tue, 23 Jan 2024 12:55:52 -0500 Subject: [PATCH] update README --- README.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4289453..a7de83c 100644 --- a/README.md +++ b/README.md @@ -14,18 +14,30 @@ Requires node 20 and npm 10. Outputs to `./dist`. +## Data + +The `data` directory contains GeoJSON data as well as the SEL/SS measurement data. The latter is mapped from CSV to JSON in a manner that best serves the application's features by Webpack's `csv-loader`; it is further sanitized by a simple ad-hoc loader, `webpack.transform-data-loader.js`, intended primarily to reduce the budle size by including only information that is actually used by the app. + +The bundle size could be further reduced by culling the GeoJSON data to include only those countries which are represented in the SEL/SS data. + ## Styling -Uses [picocss](https://picocss.com/). The complete stylesheet is injected both into the light dom as well as into the shadow doms of web components extended from `Provider`. +Uses [picocss](https://picocss.com/). We are using the SASS loader to customize Pico mainly to work with the shadow DOM. Crucially, Pico uses the `:root` selector where a fully encapsulated web component app would use `:host`. To add additional styling, do so in the relevant components by extending the static `styles` property. Be sure to include `Provider` styles via `Provider.styles` (or `super.styles`, see https://lit.dev/docs/components/styles/#inheriting-styles-from-a-superclass). To add a "global" style to the shadow dom, do so in `./src/components/styles/shadow-dom.css`. Similarly, add light dom global styles to `./src/components/styles/light-dom.css`. CSS variables related to pico are, for example, to be placed in the shadow dom styles, since the entirety of the app exists in the shadow dom. -There is currently no SASS or SCSS compiler. +As all styles are injected via js, will not update until the app is re-built: this happens automatically when developing locally, of course. -As all styles are injected via js, will not update until the app is re-built. +NB: The map web component does not use the Pico stylesheet. In fact, they interfere with each other to a certain extent, so it is useful that they can be segregated by use of the shadow DOM. + +NBB: Currently, light DOM styles are unused with the expectation that this web component will be embedded or included in a separate HTML document. ## App State -App state is defined in `./src/models/state.ts`. Uses mobx. Web components use Lit and Lit-Mobx, which means that everything re-renders when observable state changes. App state is provided to components extended from `Provider` via the `state` property. In reality, app state is injected into `Provider` by means of a Mobx observable box: this is a best practice which, for example, allows for mock data to be used for testing purposes. Examine `./src/app/index.ts` to see this in action. +App state is defined in `./src/models/state.ts`. Uses mobx. Web components use Lit and Lit-Mobx, which means that everything re-renders (very efficiently!) when observable state changes. App state is provided to components extended from `Provider` via the `state` property. In reality, app state is injected into `Provider` by means of a Mobx observable box: this is a best practice which, for example, allows for mock data to be used for testing purposes. Examine `./src/app/index.ts` to see this in action. + +## Accessibility + +An effort has been made to make the app conform to best practices with respect to keyboard navigability. To that end, the map interface has been supplemented with a dropdown menu of filtered country results which will only become visible if a keyboard user tabs into it.