|
1 | | -# Svelte Starter |
| 1 | +# FormulaCode Website |
2 | 2 |
|
3 | | -This [starter template](https://github.com/the-pudding/svelte-starter) aims to quickly scaffold a [SvelteKit](https://kit.svelte.dev/) project, designed around data-driven, visual stories at [The Pudding](https://pudding.cool). |
4 | | - |
5 | | -### Notes |
6 | | -* _Do not use or reproduce The Pudding logos or fonts without written permission._ |
7 | | -* _Prettier Formatting: Disable any text editor Prettier extensions to take advantage of the built-in rules._ |
8 | | - |
9 | | -### Features |
10 | | - |
11 | | -- [Lucide Icons](https://lucide.dev/) for simple/easy svg icons |
12 | | -- [ArchieML](http://archieml.org/) for micro-CMS powered by Google Docs and Sheets |
13 | | -- [Style Dictionary](https://amzn.github.io/style-dictionary/) for CSS/JS style parity |
14 | | -- CSV, JSON, and SVG imports |
15 | | -- SSR static-hosted builds by default |
16 | | - |
17 | | -## Quickstart |
18 | | -#### From Scratch |
19 | | -* Click the green `Use this template` button above. |
20 | | -* Alternatively: `npx degit the-pudding/svelte-starter my-project` |
21 | | - |
22 | | -#### Pre-existing Project |
23 | | -* clone the repo |
24 | | - |
25 | | -#### Installation |
26 | | -* In your local repo run `pnpm install` or `npm install` |
| 3 | +FormulaCode's website is based on the [starter template](https://github.com/the-pudding/svelte-starter) from [The Pudding](https://pudding.cool). |
27 | 4 |
|
28 | 5 | ## Development |
29 | 6 |
|
30 | 7 | ```bash |
31 | | -npm run dev |
32 | | -``` |
33 | | - |
34 | | -Change the script in `package.json` to `"dev": "svelte-kit dev --host"` to test on your local network on a different device. |
35 | | - |
36 | | -## Deploy |
37 | | -```bash |
38 | | -npm run build |
39 | | -``` |
40 | | - |
41 | | -This generates a directory called `build` with the statically rendered app. |
42 | | - |
43 | | -A shortcut for github pages: |
44 | | -```bash |
45 | | -make github |
46 | | -``` |
47 | | - |
48 | | -Deploying to Pudding AWS: |
49 | | -```bash |
50 | | -make pudding |
51 | | -``` |
52 | | - |
53 | | -## Style |
54 | | - |
55 | | -There are a few stylesheets included by default in `src/styles`. Refer to them in `app.css`, the place for applying global styles. |
56 | | - |
57 | | -For variable parity in both CSS and JS, modify files in the `properties` folder using the [Style Dictionary](https://amzn.github.io/style-dictionary/) API. |
58 | | - |
59 | | -Run `npm run style` to regenerate the style dictionary. |
60 | | - |
61 | | -#### Some css utility classes in reset.css |
62 | | -* `.sr-only`: makes content invisible available for screen reader |
63 | | -* `.text-outline`: adds a psuedo stroke to text element |
64 | | - |
65 | | -### Custom Fonts |
66 | | -For locally hosted fonts, simply add the font to the `static/assets` folder and include a reference in `src/styles/font.css`, making sure the url starts with `"assets/..."`. |
67 | | - |
68 | | -## Google Docs and Sheets |
69 | | - |
70 | | -* Create a Google Doc or Sheet |
71 | | -* Click `Share` -> `Advanced` -> `Change...` -> `Anyone with this link` |
72 | | -* In the address bar, grab the ID - eg. "...com/document/d/**1IiA5a5iCjbjOYvZVgPcjGzMy5PyfCzpPF-LnQdCdFI0**/edit" |
73 | | -* paste in the ID above into `google.config.js`, and set the filepath to where you want the file saved |
74 | | -* If you want to do a Google Sheet, be sure to include the `gid` value in the url as well |
75 | | - |
76 | | -Running `npm run gdoc` at any point (even in new tab while server is running) will fetch the latest from all Docs and Sheets. |
77 | | - |
78 | | -## Structural Overview |
79 | | - |
80 | | -### Pages |
81 | | -The `src/routes` directory contains pages for your app. For a single-page app (most cases) you don't have to modify anything in here. `+page.svelte` represents the root page, think of it as the `index.html` file. It is prepopulated with a few things like metadata and font preloading. It also includes a reference to a blank slate component `src/components/Index.svelte`. This is the file you want to really start in for your app. |
| 8 | +# install npm: |
| 9 | +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash |
| 10 | +nvm install --lts |
| 11 | +nvm use --lts |
82 | 12 |
|
83 | | -### Embedding Data |
84 | | -For smaller datasets, it is often great to embed the data into the HTML file. If you want to use data as-is, you can use normal import syntax (e.g., `import data from "$data/file.csv"`). If you are working with data but you want to preserve the original or clean/parse just what you need to use in the browser to optimize the front-end payload, you can load it via `+page.server.js`, do some work on it, and return just what you need. This is passed automatically to `+page.svelte` and accessible in any component with `getContext("data")`. |
85 | | - |
86 | | - |
87 | | -## Pre-loaded helpers |
88 | | - |
89 | | -### Components |
90 | | - |
91 | | -Located in `src/components`. |
92 | | - |
93 | | -```js |
94 | | -// Usage |
95 | | -import Example from "$components/Example.svelte"; |
96 | | -``` |
97 | | - |
98 | | -* `Footer.svelte`: Pudding recirculation and social links. |
99 | | -* `Header.svelte`: Pudding masthead. |
100 | | - |
101 | | -### Helper Components |
102 | | - |
103 | | -Located in `src/components/helpers`. |
104 | | - |
105 | | -```js |
106 | | -// Usage |
107 | | -import Example from "$components/helpers/Example.svelte"; |
108 | | -``` |
109 | | - |
110 | | -* `ButtonSet.svelte`: Accessible button group inputs. |
111 | | -* `Chunk.svelte`: Split text into smaller dom element chunks. |
112 | | -* `Countdown.svelte`: Countdown timer text. |
113 | | -* `Figure.svelte`: A barebones chart figure component to handle slots. |
114 | | -* `MotionToggle.svelte`: A toggle button to enable/disable front-end user motion preference. |
115 | | -* `Range.svelte`: Customizable range slider. |
116 | | -* `Scrolly.svelte`: Scrollytelling. |
117 | | -* `SortTable.svelte`: Sortable semantic table with customizable props. |
118 | | -* `Slider.svelte (and Slider.Slide.svelte)`: A slider widget, especially useful for swipe/slide stories. |
119 | | -* `Tap.svelte`: Edge-of-screen tapping library, designed to integrate with slider. |
120 | | -* `Tip.svelte`: Button that links to Strip payment link. |
121 | | -* `Toggle.svelte`: Accessible toggle inputs. |
122 | | -* `WIP.svelte`: A sticky banner saying this project is a WIP. |
123 | | - |
124 | | -### Layercake Chart Components |
125 | | - |
126 | | -Starter templates for various chart types to be used with [LayerCake](https://layercake.graphics/). Located in `src/components/layercake`. |
127 | | - |
128 | | -```js |
129 | | -// Usage |
130 | | -import Example from "$components/layercake/Example.svelte"; |
131 | | -``` |
132 | | - |
133 | | -### Actions |
134 | | - |
135 | | -Located in `src/actions`. |
136 | | - |
137 | | -```js |
138 | | -// Usage |
139 | | -import example from "$actions/action.js"; |
140 | | -``` |
141 | | - |
142 | | -* `canTab.js`: enable/disable tabbing on child elements. |
143 | | -* `checkOverlap.js`: Label overlapping detection. Loops through selection of nodes and adds a class to the ones that are overlapping. Once one is hidden it ignores it. |
144 | | -* `focusTrap.js`: Enable a keyboard focus trap for modals and menus. |
145 | | -* `keepWithinBox.js`: Offsets and element left/right to stay within parent. |
146 | | -* `inView.js`: detect when an element enters or exits the viewport. |
147 | | -* `resize.js`: detect when an element is resized. |
148 | | - |
149 | | -### Stores |
150 | | - |
151 | | -These are located in `src/stores`. You can put custom ones in `src/stores/misc.js` or create unique files for more complex ones. |
152 | | - |
153 | | -```js |
154 | | -// Usage |
155 | | -import example from "$stores/example.js"; |
156 | | -import { example } from "$stores/misc.js"; |
157 | | -``` |
158 | | - |
159 | | -* `mq`: returns an object of media queries booleans if they are enabled or not. You can modify them in the js file. |
160 | | -* `previous`: returns the previous value of another store. |
161 | | -* `reducedMotion`: returns a boolean of front-end user event to enable/disable motion preference. |
162 | | -* `scrollY`: returns a number of window vertical scroll position. It is throttled using rAF for performance. |
163 | | -* `timer`: returns an object `{ timer, elapsed }`. `timer` has 5 methods (start, stop, toggle, set, reset) and `elapsed` is a store that is the number of ms. |
164 | | -* `viewport`: returns an object `{ width, height }` of the viewport dimensions. It is debounced for performance. |
165 | | - |
166 | | -### Utils |
167 | | - |
168 | | -Located in `src/utils/`. |
| 13 | +# Run the test server: |
| 14 | +npm run dev |
169 | 15 |
|
170 | | -```js |
171 | | -// Usage |
172 | | -import example from "$utils/example.js"; |
| 16 | +# Pull the latest text changes in the google doc: |
| 17 | +npm run gdoc |
173 | 18 | ``` |
174 | | -* `checkScrollDir.js`: Gets the user's scroll direction ("up" or "down") |
175 | | -* `csvDownload.js`: Converts a flat array of data to CSV content ready to be used as an `href` value for download. |
176 | | -* `generateId.js`: Generate an alphanumeric id. |
177 | | -* `loadCsv.js`: Loads and parses a CSV file. |
178 | | -* `loadImage.js`: Loads an image. |
179 | | -* `loadJson.js`: Loads and parses a JSON file. |
180 | | -* `loadPixels.js`: Loads the pixel data of an image via an offscreen canvas. |
181 | | -* `localStorage.js`: Read and write to local storage. |
182 | | -* `mapToArray.js`: Convenience function to convert a map to an array. |
183 | | -* `move.js`: transform translate function shorthand. |
184 | | -* `previous.js`: keep track of the previous value of a store. |
185 | | -* `transformSvg.js`: Custom transition lets you apply an svg transform property with the in/out svelte transition. Parameters (with defaults): |
186 | | -* `translate.js`: Convenience function for transform translate css. |
187 | | -* `urlParams.js`: Get and set url parameters. |
188 | | - |
0 commit comments