Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: grammar and style corrections #3354

Merged
merged 11 commits into from
Jun 23, 2020
Next Next commit
docs: grammar fixes in fast-components and fast-element
Rob Eisenberg committed Jun 22, 2020
commit 835d60dfe614b55b8602fa0932943e813b133921
Original file line number Diff line number Diff line change
@@ -57,7 +57,7 @@ provider.accentPalette = palette;
```

### Background color
This is the contextual color that the recipe uses to determine what color it is rendering on. The foreground, outline, and divider recipes will use this color to ensure that the color created is accessible and meets contrast requirements. In fill recipes it is sometimes used as the starting location in the appropriate palette to begin resolution.
This is the contextual color that the recipe uses to determine what color it is rendering on. The foreground, outline, and divider recipes will use this color to ensure that the color created is accessible and meets contrast requirements. In fill recipes, it is sometimes used as the starting location in the appropriate palette to begin resolution.

See [backgroundColor](api/fast-components.fastdesignsystemprovider.backgroundcolor.md) for more details.

Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# Acknowledgements

There are many great open source projects that have inspired us and enabled us to build the FAST. Below are a few that stand out.
There are many great open source projects that have inspired us and enabled us to build FAST. Below are a few that stand out.

* [Aurelia 1 and Aurelia 2](https://aurelia.io/) - Various details of Aurelia 2's decorator and metadata model inspired us in the design of `fast-element`. Additionally, Aurelia 1's mechanisms for array observation, binding, and template compilation also guided us in our work.
* [faastjs](https://github.com/faastjs) - A project with a similar name but a very different purpose. Their API documentation approach leveraging [api-extractor](https://api-extractor.com/) was a huge help to us.
* [Knockout](https://knockoutjs.com/) - One of the first JavaScript libraries (if not the first) to implement an observer system. The original techniques for observables and computed observables have influenced many libraries over the years. Re-interpreting these ideas in terms of modern JavaScript and DOM has helped us to build a powerful and robust system.
* [lit-html](https://lit-html.polymer-project.org/) - One of the first libraries to leverage standard JavaScript tagged template literals for HTML templates. We were inspired by this technique and wanted to explore whether it could be combined with our idea of arrow function binding expressions.
* [Polymer](https://www.polymer-project.org/) - One of the first libraries (if not the first) to embrace Web Components.
* [Vue](https://vuejs.org/) - We liked the terseness of the `:` and `@` syntax in templates, so we adapted it with some modifications in our own templates.
* [Vue](https://vuejs.org/) - We liked the terseness of the `:` and `@` syntax in templates, so we adapted it along with some modifications in our templates.
Original file line number Diff line number Diff line change
@@ -52,7 +52,7 @@ We've seen how arrow functions can be used to declare dynamic parts of templates

### Content

To bind the content of an element, simply provide the expression within the start and end tags of the element. It can be the sole content of the element, or interwoven with other elements and text.
To bind the content of an element, simply provide the expression within the start and end tags of the element. It can be the sole content of the element or interwoven with other elements and text.

**Example: Basic Text Content**

@@ -81,7 +81,7 @@ Dynamic content is set via the `textContent` HTML property for security reasons.

### Attributes

You can also use an expression to set an attribute value on an HTML Element. Simply place the expression where the value of the HTML attribute would go. The template engine will then use your expression to set the value using `setAttribute(...)`, whenever it needs to be updated. Additionally, some attributes are known as [boolean attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#Boolean_Attributes) (e.g. required, readonly, disabled). These attributes behave differently from normal attributes, and need special value handling. The templating engine will handle this for you if you prepend the attribute name with a `?`.
You can also use an expression to set an attribute value on an HTML Element. Simply place the expression where the value of the HTML attribute would go. The template engine will then use your expression to set the value using `setAttribute(...)`, whenever it needs to be updated. Additionally, some attributes are known as [boolean attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes#Boolean_Attributes) (e.g. required, readonly, disabled). These attributes behave differently from normal attributes and need special value handling. The templating engine will handle this for you if you prepend the attribute name with a `?`.

**Example: Basic Attribute Values**

@@ -104,7 +104,7 @@ You can also use an expression to set an attribute value on an HTML Element. Sim
```

:::tip
When binding to `class`, the underlying engine will not over-write classes added to the element via other mechanisms. It only adds and removes classes that result directly from the binding. This "safe by default" behavior does come at a slight performance cost. To opt out of this feature and squeeze out every ounce of performance by always overwriting all classes, use a property binding (see below) on the `className` property. e.g. `:className="list-item ${x => x.type}"`.
When binding to `class`, the underlying engine will not over-write classes added to the element via other mechanisms. It only adds and removes classes that result directly from the binding. This "safe by default" behavior does come at a slight performance cost. To opt-out of this feature and squeeze out every ounce of performance by always overwriting all classes, use a property binding (see below) on the `className` property. e.g. `:className="list-item ${x => x.type}"`.
:::

```html
@@ -187,7 +187,7 @@ Besides rendering content, attributes, and properties, you'll often want to add
```

:::important
In both examples above, after your event handler is executed, `preventDefault()` will be called on the event object by default. You can return `true` from your handler to opt out of this behavior.
In both examples above, after your event handler is executed, `preventDefault()` will be called on the event object by default. You can return `true` from your handler to opt-out of this behavior.
:::

The second example demonstrates an important characteristic of the templating engine: it only supports *unidirectional data flow* (model => view). It does not support *two-way data binding* (model <=> view). As shown above, pushing data from the view back to the model should be handled with explicit events that call into your model's API.
Original file line number Diff line number Diff line change
@@ -88,7 +88,7 @@ Here's how it works:
* When the property value changes, the converter's `fromView` method will also be called, ensuring that the type is correct. After this, the `mode` will be determined. If the mode is set to `reflect` then the converter's `toView` method will be called to allow the type to be formatted before writing to the attribute using `setAttribute`.

:::important
When the `mode` is set to `boolean`, a built-in `booleanConverter` is automatically used to ensure type correctness so that manual configuration of the converter is not needed in this common scenario.
When the `mode` is set to `boolean`, a built-in `booleanConverter` is automatically used to ensure type correctness so that the manual configuration of the converter is not needed in this common scenario.
:::

**Example: An Attribute in Reflect Mode with No Special Conversion**
@@ -158,7 +158,7 @@ export class NameTag extends FASTElement {
}
```

The full list of available lifecyle callbacks is:
The full list of available lifecycle callbacks is:

| Callback | Description |
| ------------- |-------------|
Original file line number Diff line number Diff line change
@@ -55,14 +55,14 @@ const styles = css`
letter-spacing: 4px;
font-size: 32px;
margin: 0;
padding: 0;
padding: 0;
}

h4 {
font-family: sans-serif;
font-size: 18px;
margin: 0;
padding: 0;
padding: 0;
}

.body {
@@ -161,7 +161,7 @@ const styles = css`
```

:::note
Both slotted and host styles can be overriden by the element user. Think of these as the *default* styles that you are providing, so that your elements look and function correctly out-of-the-box.
Both slotted and host styles can be overridden by the element user. Think of these as the *default* styles that you are providing, so that your elements look and function correctly out-of-the-box.
:::

## Hiding Undefined Elements
Original file line number Diff line number Diff line change
@@ -7,6 +7,6 @@ custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-

We've seen how to use `FASTElement` to declaratively build Web Components. In addition to the basics of element and attribute definition, `FASTElement` also provides a way to declare templates capable of high-performance rendering, and efficient, incremental batched updates. Finally, CSS can easily be associated with an element in a way that leverages core platform optimizations for performance and low memory allocation.

Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](../design/introduction). Finally, you'll want to take advantages of a modern toolset by installing [a powerful editor and plugins](../tools/vscode).
Now that you're familiar with the robust and powerful features of `FASTElement`, you're ready to build your own components and apps. But you don't have to start from scratch there either! If you haven't already explored them, check out our [FAST Components](../components/getting-started), which provide all the basic UI building-blocks you'd expect in a modern component library. You can also leverage the same adaptive design system that our own components use to enable robust theming throughout all you create. Read more on that in [Styling Components](../design/introduction). Finally, you'll want to take advantage of a modern toolset by installing [a powerful editor and plugins](../tools/vscode).

Happy componenting!
Original file line number Diff line number Diff line change
@@ -119,13 +119,13 @@ Similar to event handlers, within a `repeat` block you have access to a special

* `event` - The event object when inside an event handler.
* `parent` - The parent scope when inside a `repeat` block.
* `index` - The index of the current item when inside a `repeat` block (opt in).
* `length` - The length of the array when inside a `repeat` block (opt in).
* `isEven` - True if the index of the current item is even when inside a `repeat` block (opt in).
* `isOdd` - True if the index of the current item is odd when inside a `repeat` block (opt in).
* `isFirst` - True if the current item is first in the array inside a `repeat` block (opt in).
* `isInMiddle` - True if the current item is somewhere in the middle of the the array inside a `repeat` block (opt in).
* `isLast` - True if the current item is last in the array inside a `repeat` block (opt in).
* `index` - The index of the current item when inside a `repeat` block (opt-in).
* `length` - The length of the array when inside a `repeat` block (opt-in).
* `isEven` - True if the index of the current item is even when inside a `repeat` block (opt-in).
* `isOdd` - True if the index of the current item is odd when inside a `repeat` block (opt-in).
* `isFirst` - True if the current item is first in the array inside a `repeat` block (opt-in).
* `isInMiddle` - True if the current item is somewhere in the middle of the array inside a `repeat` block (opt-in).
* `isLast` - True if the current item is last in the array inside a `repeat` block (opt-in).

Some context properties are opt-in because they are more costly to update. So, for performance reasons, they are not available by default. To opt into the positioning properties, pass options to the repeat directive, with the setting `positioning: true`. For example, here's how we would use the `index` in our friends template from above:

@@ -212,7 +212,7 @@ export class FriendList extends FASTElement {

In the above example, we create an independent `nameTemplate` and then use it in two different places. First inside of a `when` template and then later inside of a `repeat` template.

But content composition is actually more powerful than that, because you aren't limited to *static composition* of templates. You can also provide any expression that returns a template. As a result, when the `@observable` dependencies of the expression change, you can dynamically change which template is selected for rendering. If you don't want to render anything, you can also handle that by returning `null` or `undefined`. Here are a few examples of what you can do with content composition:
But content composition is actually more powerful than that because you aren't limited to *static composition* of templates. You can also provide any expression that returns a template. As a result, when the `@observable` dependencies of the expression change, you can dynamically change which template is selected for rendering. If you don't want to render anything, you can also handle that by returning `null` or `undefined`. Here are a few examples of what you can do with content composition:

**Example: Dynamic Composition**

@@ -402,7 +402,7 @@ Referential directives allow you to easily get references to DOM nodes in variou

### The Ref Directive

Sometimes you need a direct reference to a single DOM node from your template. This might be because you want to control playback of a `video` element, use the drawing context of a `canvas` element, or pass an element to a 3rd party library. Whatever the reason, you can get a reference to the DOM node by using the `ref` directive.
Sometimes you need a direct reference to a single DOM node from your template. This might be because you want to control the playback of a `video` element, use the drawing context of a `canvas` element, or pass an element to a 3rd party library. Whatever the reason, you can get a reference to the DOM node by using the `ref` directive.

**Example: Referencing an Element**

@@ -468,7 +468,7 @@ export class FriendList extends FASTElement {
}
```

In the example above, the `listItems` property will be populated with all child nodes of the `ul` element. If `listItems` is decorated with `@observable` then it will be updated dynamically as the child nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `children` directive to specify customized configuration for the underlying [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
In the example above, the `listItems` property will be populated with all child nodes of the `ul` element. If `listItems` is decorated with `@observable` then it will be updated dynamically as the child nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `children` directive to specify a customized configuration for the underlying [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).

:::important
Like `ref`, the child nodes are not available until the `connectedCallback` lifecycle event.
@@ -517,7 +517,7 @@ export class MyElement extends FASTElement {
}
```

Similar to the `children` directive, the `slotted` directive will populate the `slottedNodes` property with nodes assigned to the slot. If `slottedNodes` is decorated with `@observable` then it will be updated dynamically as the assigned nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `slotted` directive to specify customized configuration for the underlying [assignedNodes() API call](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes) or specify a `filter`.
Similar to the `children` directive, the `slotted` directive will populate the `slottedNodes` property with nodes assigned to the slot. If `slottedNodes` is decorated with `@observable` then it will be updated dynamically as the assigned nodes change. Like any observable, you can optionally implement a *propertyName*Changed method to be notified when the nodes change. Additionally, you can provide an `options` object to the `slotted` directive to specify a customized configuration for the underlying [assignedNodes() API call](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes) or specify a `filter`.

## Host Directives

Loading