Sep 5, 2023 · Sep 5, 2023 · Sep 5, 2023 · Sep 5, 2023
diff --git a/pgml-apps/cargo-pgml-components/README.md b/pgml-apps/cargo-pgml-components/README.md
 # pgml-components

 `pgml-components` is a CLI for working with Rust web apps written with Rocket, Sailfish and SQLx, our toolkit of choice. It's currently a work in progress and only used internally by us, but the long term goal is to make it into a comprehensive framework for building web apps in Rust.

 ## Installation

 `pgml-components` is available on crates.io and can be installed with `cargo install cargo-pgml-components`.

 ## Usage

 To get a list of available commands:

 ```bash
 cargo pgml-components --help
 ```

 The CLI operates on a project directory, which is a directory containing a `Cargo.toml` file. You can specify the project directory with the `--project-path` flag, or you can run the CLI from the project directory itself.

 ### Commands

 #### `bundle`

 ```bash
 cargo pgml-components bundle
 ```

 This command will read all the JavaScript and Sass files in the project and bundle them into a JS bundle and a CSS bundle accordingly. The JS bundle is created with [Rollup](https://rollupjs.org/) and the CSS bundle is created with the [Sass compiler](https://sass-lang.com/install/).

 The `bundle` command should be ran after making any changes to JavaScript or Sass files. In our app, we added it to `build.rs` and run it on every change to the `src/` directory, but another way of running it without having to rebuild the app can be with `watch`:

 ```bash
 cargo watch \
 --exec 'pgml-components bundle' \
 --watch src/ \
 --watch static/ \
 --ignore bundle.*.*
 ```

 The bundles are placed in `static/css/style.css` and `static/js/bundle.js`. Both bundles are also copied into files with a short hash of their contents appended to their names, e.g. `static/css/style.6c1a4abc.css`. The bundles with the hash in their names are used in production, while the bundles without the hash are used in development. The hash is used to bust our caching of assets.

 #### `add`

 This command is used to add elements to the project. Currently, only frontend components are supported. Support for SQLx models and Rocket controllers is on the roadmap.

 ##### `add component`

 ```bash
 cargo pgml-components add component <path>
 ```

 This command will create a new frontend component in the specified path. The name of the component will be the absolute name of the Rust module. For example, if the path of the component is `dropdown`, then the component will be added to `src/components/dropdown` and it's name will be `crate::components::Dropdown`. If the component path is `controls/button/primary`, then component name will be `crate::components::controls::button::Primary` and the component will be placed into the `src/components/controls/button/primary` directory.

 Frontend components use Sailfish templates, Hotwired Stimulus for JavaScript, and Sass stylesheets. The command creates all of these automatically and links both the JS and the Sass into the bundles produced by the `bundle` command.

 For example, if creating the `dropdown` component, you'll get the following files:

 ```
 # Sailfish template
 src/components/dropdown/template.html

 # Stimulus controller
 src/components/dropdown/dropdown_controller.js

 # Sass stylesheet
 src/components/dropdown/dropdown.sass

 # Rust module
 src/components/dropdown/mod.rs
 ```

 Initially, the component will be very barebones, but it will have all the necessary dependencies connected automatically.

 ###### `template.html`

 The HTML template will just have a `<div>` that's connected to the Stimulus controller.

 ```html
 <div data-controller="dropdown">
 </div>
 ```

 ###### `dropdown_controller.js`

 The Stimulus controller is connected to the `<div>` in the template above, and can be used immediately.

 ```javascript
 import { Controller } from '@hotwired/stimulus'

 export default class extends Controller {
 initiliaze() {
 console.log('Initialized dropdown controller')
 }
 }
 ```

 ###### `dropdown.sass`

 The Sass stylesheet doesn't have much, but you can start adding styles into it immediately. We don't have to use `data-controller` CSS selectors, the typical class selectors are fine. The command just generates something that will immediately work without any further configuration.

 ```css
 div[data-controller="dropdown"] {
 width: 100%;
 height: 100px;

 background: red;
 }
 ```

 ###### `mod.rs`

 Everything is linked together ultimately with Rust. This file defines a struct that implements `sailfish::TemplateOnce`.

 ```rust
 use sailfish::TemplateOnce;

 #[derive(TemplateOnce)]
 #[template(path = "dropdown/template.html")]
 pub struct Dropdown {
 pub value: String,
 }
 ```

 Once the component is created, it can be used in any Sailfish template:

 ```html
 <% use crate::components::Dropdown; %>

 <div class="row">
 <div class="col-6">
 <%+ Dropdown::new() %>
 </div>
 </div>
 ```

 Components can be placed into any directory under `src/components`. They have to be in their own folder, so to have components organized neatly, you'd need to have folders that only contain other components and not be a component by itself.

 For example, all buttons can be placed in `controls/buttons`, e.g. `controls/buttons/primary`, `controls/buttons/secondary`, but there cannot be a component in `controls/buttons`. There is no inherent limitation in our framework, but it's good to keep things tidy.

 `pgml-components` does all of this automatically and makes sure that you don't accidently add components into a directory that already has one.

 ##### Deleting a component

 There is no command for deleting a component yet, but you can do so by just deleting its directory and all the files in it, and bundling.

 For example, to delete the `dropdown` component, you'd run:

 ```bash
 rm -r src/components/dropdown
 cargo pgml-components bundle
 ```

 ## Philosophy

 `pgml-components` is an opinionated framework for building web apps in Rust based on our experience of using Rocket, SQLx, and Sailfish (and other template engines). That being said, its philosophy is to generate code based on its own templates, and doesn't force its user to use any specific parts of it. Therefore, all elements generated by `pgml-components` are optional. When creating a new component, you can remove the Stimulus controller or the Sass stylesheet. If removed, they won't be added into the bundle.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,154 @@
		# pgml-components

		`pgml-components` is a CLI for working with Rust web apps written with Rocket, Sailfish and SQLx, our toolkit of choice. It's currently a work in progress and only used internally by us, but the long term goal is to make it into a comprehensive framework for building web apps in Rust.

		## Installation

		`pgml-components` is available on crates.io and can be installed with `cargo install cargo-pgml-components`.

		## Usage

		To get a list of available commands:

		```bash
		cargo pgml-components --help
		```

		The CLI operates on a project directory, which is a directory containing a `Cargo.toml` file. You can specify the project directory with the `--project-path` flag, or you can run the CLI from the project directory itself.

		### Commands

		#### `bundle`

		```bash
		cargo pgml-components bundle
		```

		This command will read all the JavaScript and Sass files in the project and bundle them into a JS bundle and a CSS bundle accordingly. The JS bundle is created with [Rollup](https://rollupjs.org/) and the CSS bundle is created with the [Sass compiler](https://sass-lang.com/install/).

		The `bundle` command should be ran after making any changes to JavaScript or Sass files. In our app, we added it to `build.rs` and run it on every change to the `src/` directory, but another way of running it without having to rebuild the app can be with `watch`:

		```bash
		cargo watch \
		--exec 'pgml-components bundle' \
		--watch src/ \
		--watch static/ \
		--ignore bundle..
		```

		The bundles are placed in `static/css/style.css` and `static/js/bundle.js`. Both bundles are also copied into files with a short hash of their contents appended to their names, e.g. `static/css/style.6c1a4abc.css`. The bundles with the hash in their names are used in production, while the bundles without the hash are used in development. The hash is used to bust our caching of assets.

		#### `add`

		This command is used to add elements to the project. Currently, only frontend components are supported. Support for SQLx models and Rocket controllers is on the roadmap.

		##### `add component`

		```bash
		cargo pgml-components add component <path>
		```

		This command will create a new frontend component in the specified path. The name of the component will be the absolute name of the Rust module. For example, if the path of the component is `dropdown`, then the component will be added to `src/components/dropdown` and it's name will be `crate::components::Dropdown`. If the component path is `controls/button/primary`, then component name will be `crate::components::controls::button::Primary` and the component will be placed into the `src/components/controls/button/primary` directory.

		Frontend components use Sailfish templates, Hotwired Stimulus for JavaScript, and Sass stylesheets. The command creates all of these automatically and links both the JS and the Sass into the bundles produced by the `bundle` command.

		For example, if creating the `dropdown` component, you'll get the following files:

		```
		# Sailfish template
		src/components/dropdown/template.html

		# Stimulus controller
		src/components/dropdown/dropdown_controller.js

		# Sass stylesheet
		src/components/dropdown/dropdown.sass

		# Rust module
		src/components/dropdown/mod.rs
		```

		Initially, the component will be very barebones, but it will have all the necessary dependencies connected automatically.

		###### `template.html`

		The HTML template will just have a `<div>` that's connected to the Stimulus controller.

		```html
		<div data-controller="dropdown">
		</div>
		```

		###### `dropdown_controller.js`

		The Stimulus controller is connected to the `<div>` in the template above, and can be used immediately.

		```javascript
		import { Controller } from '@hotwired/stimulus'

		export default class extends Controller {
		initiliaze() {
		console.log('Initialized dropdown controller')
		}
		}
		```

		###### `dropdown.sass`

		The Sass stylesheet doesn't have much, but you can start adding styles into it immediately. We don't have to use `data-controller` CSS selectors, the typical class selectors are fine. The command just generates something that will immediately work without any further configuration.

		```css
		div[data-controller="dropdown"] {
		width: 100%;
		height: 100px;

		background: red;
		}
		```

		###### `mod.rs`

		Everything is linked together ultimately with Rust. This file defines a struct that implements `sailfish::TemplateOnce`.

		```rust
		use sailfish::TemplateOnce;

		#[derive(TemplateOnce)]
		#[template(path = "dropdown/template.html")]
		pub struct Dropdown {
		pub value: String,
		}
		```

		Once the component is created, it can be used in any Sailfish template:

		```html
		<% use crate::components::Dropdown; %>

		<div class="row">
		<div class="col-6">
		<%+ Dropdown::new() %>
		</div>
		</div>
		```

		Components can be placed into any directory under `src/components`. They have to be in their own folder, so to have components organized neatly, you'd need to have folders that only contain other components and not be a component by itself.

		For example, all buttons can be placed in `controls/buttons`, e.g. `controls/buttons/primary`, `controls/buttons/secondary`, but there cannot be a component in `controls/buttons`. There is no inherent limitation in our framework, but it's good to keep things tidy.

		`pgml-components` does all of this automatically and makes sure that you don't accidently add components into a directory that already has one.

		##### Deleting a component

		There is no command for deleting a component yet, but you can do so by just deleting its directory and all the files in it, and bundling.

		For example, to delete the `dropdown` component, you'd run:

		```bash
		rm -r src/components/dropdown
		cargo pgml-components bundle
		```

		## Philosophy

		`pgml-components` is an opinionated framework for building web apps in Rust based on our experience of using Rocket, SQLx, and Sailfish (and other template engines). That being said, its philosophy is to generate code based on its own templates, and doesn't force its user to use any specific parts of it. Therefore, all elements generated by `pgml-components` are optional. When creating a new component, you can remove the Stimulus controller or the Sass stylesheet. If removed, they won't be added into the bundle.