@entake/particle 21.0.1 → 21.1.0

package/README.md

@@ -1,372 +1,372 @@
-# Particle for Angular by Entake
-
-This package offers a small selection of reusable components that are meant to replace usage of other Angular component libraries, like Angular Material and PrimeNG. If you're looking for a themeable alternative that gives you unprecedented control of your Angular components, give Particle a try! If you're interested in contributing or find any bugs, feel free to catch us on GitHub.
-
-## ParticleColorPickerModule
-### ColorPickerComponent
-The color picker component is a simple way to choose/input a color in hexadecimal format. It offers a text input that allows for free entry in hexadecimal format along with a color picker for supported browsers. If the browser does not support the HTML5 color picker, it is replaced with a simple color swatch that acts as a preview of the contents of the text input.
-#### Usage
-The color picker accepts a hexadecimal color string (either in short or full form, leading `#` optional, case is ignored) through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the color picker, you can listen for its `ngModelChange` event (if using `ngModel`) or its `colorSelected` event. The value emitted from the component is a full hexadecimal color string (ex: `#0a50d3`). Model updates on every color picker input, every valid text input entry and when the contents of the text input are deleted by the user.
-#### Selector: particle-color-picker
-#### Inputs
-- `value` setter for the internal value of the component
-- `disabled` whether the component should be disabled
-- `ariaLabel` the aria label to set for the color picker/text input
-- `classList` CSS class list to apply to the text input
-#### Outputs
-- `input` event emitted on text input, emits the current value of the component
-- `colorSelected` event emitted on color picker close or on valid hexadecimal string input from the text input, emits the selected color as a hexadecimal string
-
-## ParticleDatePickerModule
-### DatePickerComponent
-The date picker component allows the user to enter a date via a text input (in the form of month/day/year) or through a calendar widget.
-#### Usage
-The date picker accepts a Date object through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the date picker, you can listen for its `ngModelChange` event (if using `ngModel`) or its `dateSelected` event. The value emitted from the component is a Date object representing the user's typed/selected date. Model updates on every calendar widget selection, every valid text input entry and when the contents of the text input are deleted by the user.
-#### Selector: particle-date-picker
-#### Inputs
-- `value` setter for the internal value of the component
-- `disabled` whether the component should be disabled
-- `dateRange` object in the form of `{ minDate: Date, maxDate: Date}` that acts as the valid selection range for the input/calendar widget. Min date must be less than max date. If min date is not provided, the min date is set to January 1st, {currentYear - 100}. If max date is not provided, the max date is set to December 31st, {current year + 50}.
-- `inputId` the ID to assign to the text input
-- `ariaLabel` the aria label to assign to the text input
-- `inputClassList` CSS class list to apply to the text input
-- `calendarButtonClassList` CSS class list to apply to the calendar widget button
-#### Outputs
-- `input` event emitted on text input
-- `dateSelected` event emitted on valid date input/widget date selection, emits the selected date
-### CalendarComponent
-The calendar component displays a calendar widget with accessibility features such as arrow key navigation of calendar dates.
-#### Usage
-The calendar accepts a Date object through its `value` input. To read in the value of the calendar, you can listen for its `selected` event. The value emitted from the component is a Date object representing the user's selection.
-#### Selector: particle-calendar
-#### Inputs
-- `value` setter for the internal value of the component
-- `dateRange` object in the form of { minDate: Date, maxDate: Date} that acts as the valid selection range for the calendar. Min date must be less than max date. If min date is not provided, the min date is set to January 1st, {currentYear - 100}. If max date is not provided, the max date is set to December 31st, {current year + 50}.
-#### Outputs
-- `selected` event emitted on calendar date selection, emits the selected date
-- `closed` event emitted when the user clicks outside the widget, triggers a keyup.escape event or clicks the done button. It is the parent component's responsibility to hide the calendar, the event is merely a signal that action should be taken.
-
-## ParticleDialogModule
-### DialogComponent
-The dialog component displays dynamic content within a dialog and supports nested dialogs within that dynamic content.
-#### Usage
-The dialog component essentially wraps an `ng-content` block. It is the responsibility of the parent component to show/hide the dialog based on its `object` input and `closed` event. The dialog listens for `keyup.escape` events (if enabled) to trigger a dialog close. If you have components in the dynamic dialog content that also rely on escape events to close, those components must listen for keyups on its own focusable elements (as opposed to listening for `window.keyup`) and either stop immediate propagation, or those focusable elements must have the `data-dialog-close-override` attribute on them, or else the escape event will close both the child component and the parent dialog.
-#### Selector: particle-dialog
-#### Inputs
-- `object` an input of type `any` where that input becoming truthy will show the dialog and falsy will hide
-- `title` the title of the dialog. Note: always use the Angular input syntax (`[title]="'Title'"`) to avoid IE11 triggering a native tooltip of the dialog title
-- `titleClass` CSS class to apply to the title section of the dialog
-- `bodyClass` CSS class to apply to the body section of the dialog
-- `showTitle` whether to show the title section of the dialog (default `true`)
-- `allowClose` whether to show the dialog close button and enable escape to close (default `true`)
-- `height` the height of dialog (can be any valid CSS measurement)
-- `width` the width of dialog (can be any valid CSS measurement)
-#### Outputs
-- `opened` event emitted on dialog open
-- `closed` event emitted on dialog close
-
-## ParticleDropdownModule
-### DropdownComponent
-The dropdown component acts as an enhanced HTML select. It supports both regular dropdown options (only the label being displayed) and templated options (options for which you can supply a ng-template to act as a template for each dropdown option). The dropdown is fully accessible as well, and supports all the accessibility options that a native select would (such as arrow key controls for option selection).
-#### Usage
-The dropdown accepts a string or number through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the dropdown, you can listen for its `ngModelChange` event (if using `ngModel`) or its `change` event. The value emitted from the component is a string or number representing the value of the user's selected option. Model updates on every option change, whether it be triggered by clicking on an option or using arrow key controls.
-#### Using Dropdown Options
-The dropdown supports both flat options or option groups, and the options for a single dropdown can be a mix of the two. A dropdown option has a value (string or number), a label, disabled indicator, and an optional data context object (the data context object is not needed if you're not planning to use templating). Whether data context is passed in or not for an option, each option internally will have a data context object which will minimally contain the option's label (inserted into the `$implicit` property if not already taken, or the `label` property if `$implicit` is already present in the object). Dropdown option groups contain a group label, and an array of dropdown options.
-#### Using Dropdown Option Templating
-Dropdown option templating relies on Angular's `ng-template` syntax. To provide an option template to the dropdown, you simply define a `ng-template` as the content of the dropdown. If you do not wish to use templating, pass nothing into the content between the dropdown tags. To display data from an option's data context within the option template, you use Angular's `ng-template` `let-var` syntax. This allows you to define variables within the option template that will then be filled by the corresponding property in an option's data context. As mentioned in the previous section, the option's label is automatically added to each option's data context, so to display the label in the template, you can just define a variable without a value, and it will be filled by the `$implicit` entry. Here's an example of how a typical use case of the dropdown with templating would look:
-
-```html
-  <particle-dropdown [options]="[
-                    { value: 'red', label: 'Red', dataContext: { 'colorClass': 'bg_red' } },
-                    { value: 'green', label: 'Green', disabled: true, dataContext: { 'colorClass': 'bg_green' } },
-                    { value: 'blue', label: 'Blue', dataContext: { 'colorClass': 'bg_blue' } },
-                    { groupLabel: 'Purple Values', options: [
-                        { value: 'darkPurple', label: 'Dark Purple', dataContext: { 'colorClass': 'bg_purple_dark_4' } },
-                        { value: 'purple', label: 'Purple', dataContext: { 'colorClass': 'bg_purple' } },
-                        { value: 'lightPurple', label: 'Light Purple', dataContext: { 'colorClass': 'bg_purple_light_4' } }
-                    ]}
-                 ]">
-    <ng-template let-colorClass="colorClass" let-label>
-      <div class="circle_14px mar_right5"
-           [ngClass]="colorClass">
-      </div> {{label}}
-    </ng-template>
-  </particle-dropdown>
-```
-Notice how, in the `ng-template`, the variable definition value (in quotes) for `colorClass` matches up with the property of the same name in the data context objects for each option. Also notice how the variable definition for `label` has no value assigned, that's because the dropdown component will automatically put an option's label into the `$implicit` property, which Angular uses to fill in the value for any referenced variables that do not have a specified value. You can of course choose to explicitly add the label to the option's data context and use that value in the label variable assignment as well.
-#### Selector: particle-dropdown
-#### Inputs
-- `value` string or number representing the value of the selected option
-- `options` array of `DropdownOption | DropdownOptionGroup` acting as the options to populate the dropdown
-- `disabled` whether the dropdown should be disabled or not
-- `placeholder` placeholder text to show in the dropdown when no option is selected
-- `ariaLabel` aria label to assign to the dropdown
-- `classList` CSS class list to apply to the dropdown
-#### Outputs
-- change: event emitted on dropdown option selection if selection has changed from the previous value, emits the selected value
-
-## ParticleEndpointStateModule
-### EndpointStateComponent
-The endpoint state component serves as a catch-all for displaying endpoint states (loading, not found and error).
-#### Usage
-The endpoint state component is split into four different possible states: loading, loadingOverlay, empty and error. You specify which state the component should be in by passing in `true` to the desired state as an input. Note: only one state should be active at a time.
-#### Inputs
-- `loading` whether the component should be in the loading state
-- `loadingIcon` an icon class to display in the loading state
-- `loadingText` main text to display in the loading state
-- `loadingSubtext` subtext to display in the loading state
-- `loadingOverlay` whether the component should be in the loading overlay state (whole-screen overlay)
-- `loadingOverlayIcon` an icon class to display in the loading overlay state
-- `loadingOverlayText` main text to display in the loading overlay state
-- `loadingOverlaySubtext` subtext to display in the loading overlay state
-- `empty` whether the component should be in the empty (not found) state
-- `emptyIcon` an icon class to display in the empty state
-- `emptyText` main text to display in the empty state
-- `emptySubtext` subtext to display in the empty state
-- `error` whether the component should be in the error state
-- `errorIcon` an icon class to display in the error state
-- `errorText` main text to display in the error state
-- `errorSubtext` subtext to display in the error state
-
-## ParticleIconsModule
-### IconSelectComponent
-The icon select component allows a user to search for and select either a Fontawesome or Particle (custom) icon.
-### Usage
-The icon select accepts an icon class through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the icon select, you can listen for its `ngModelChange` event (if using `ngModel`) or its `selected` event. The value emitted from the component is the selected icon class. Model updates on confirm button click.
-### Inputs
-- `value` setter for the internal value of the component
-- `disabled` whether the component is disabled
-- `buttonColorClass` CSS class to apply to the icon dialog show button
-- `buttonSizing` the size (width/height) of the icon dialog show button in pixels
-#### Outputs
-- `opened` event emitted on icon dialog open
-- `selected` event emitted on icon dialog confirmation, emits the selected icon in the form of `{ value: string }`
-- `closed` event emitted on icon dialog close
-
-## ParticleKeyfilterModule
-### KeyfilterDirective
-Directive to apply to HTML input elements to filter out certain input.
-#### Usage
-Supported filter types are `alpha` (English alphabet only), `numeric` (digits only) and `alphanumeric` (English alphabet and digits).
-#### Selector: particleKeyfilter
-#### Inputs
-- `particleKeyfilter` the filter type to apply to the host input
-- `allowSpaces` whether to allow spaces in input (default `false`)
-
-## ParticleMultiSelectModule
-### MultiSelectComponent
-The multi-select component acts as an enhanced HTML select that allows multiple selections. It supports both regular multi-select options (only the label being displayed) and templated options (options for which you can supply a ng-template to act as a template for each multi-select option). The multi-select is fully accessible as well, and supports all the accessibility options that a multi-select should (such as arrow key controls for option selection).
-#### Usage
-The multi-select accepts an array of strings or numbers through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the multi-select, you can listen for its `ngModelChange` event (if using `ngModel`) or its `change` event. The value emitted from the component is an array of strings or numbers representing the values of the user's selected options. Model updates on every option select/de-select, whether it be triggered by clicking on an option or using arrow key controls.
-#### Using Dropdown Options
-The multi-select supports both flat options or option groups, and the options for a single multi-select can be a mix of the two. A multi-select option has a value (string or number), a label, disabled indicator, and an optional data context object (the data context object is not needed if you're not planning to use templating). Whether data context is passed in or not for an option, each option internally will have a data context object which will minimally contain the option's label (inserted into the `$implicit` property if not already taken, or the `label` property if `$implicit` is already present in the object). Multi-select option groups contain a group label, and an array of multi-select options.
-#### Using Dropdown Option Templating
-Multi-select option templating relies on Angular's `ng-template` syntax. To provide an option template to the multi-select, you simply define a `ng-template` as the content of the multi-select. If you do not wish to use templating, pass nothing into the content between the multi-select tags. To display data from an option's data context within the option template, you use Angular's `ng-template` `let-var` syntax. This allows you to define variables within the option template that will then be filled by the corresponding property in an option's data context. As mentioned in the previous section, the option's label is automatically added to each option's data context, so to display the label in the template, you can just define a variable without a value, and it will be filled by the `$implicit` entry. Here's an example of how a typical use case of the multi-select with templating would look:
-
-```html
-  <particle-multi-select [options]="[
-                    { value: 'red', label: 'Red', dataContext: { 'colorClass': 'bg_red' } },
-                    { value: 'green', label: 'Green', disabled: true, dataContext: { 'colorClass': 'bg_green' } },
-                    { value: 'blue', label: 'Blue', dataContext: { 'colorClass': 'bg_blue' } },
-                    { groupLabel: 'Purple Values', options: [
-                        { value: 'darkPurple', label: 'Dark Purple', dataContext: { 'colorClass': 'bg_purple_dark_4' } },
-                        { value: 'purple', label: 'Purple', dataContext: { 'colorClass': 'bg_purple' } },
-                        { value: 'lightPurple', label: 'Light Purple', dataContext: { 'colorClass': 'bg_purple_light_4' } }
-                    ]}
-                 ]">
-    <ng-template let-colorClass="colorClass" let-label>
-      <div class="circle_14px mar_right5"
-           [ngClass]="colorClass">
-      </div> {{label}}
-    </ng-template>
-  </particle-multi-select>
-```
-Notice how, in the `ng-template`, the variable definition value (in quotes) for `colorClass` matches up with the property of the same name in the data context objects for each option. Also notice how the variable definition for `label` has no value assigned, that's because the multi-select component will automatically put an option's label into the `$implicit` property, which Angular uses to fill in the value for any referenced variables that do not have a specified value. You can of course choose to explicitly add the label to the option's data context and use that value in the label variable assignment as well.
-#### Selector: particle-multi-select
-#### Inputs
-- `value` array of strings or numbers representing the value of the selected options
-- `options` array of `MultiSelectOption | MultiSelectOptionGroup` acting as the options to populate the multi-select
-- `disabled` whether the multi-select should be disabled or not
-- `placeholder` placeholder text to show in the multi-select when no options are selected
-- `ariaLabel` aria label to assign to the multi-select
-- `classList` CSS class list to apply to the multi-select
-#### Outputs
-- `change` event emitted on multi-select option selection if selection has changed from the previous value, emits the selected values
-
-## ParticleNotificationModule
-### Notifications
-A notification is a simple way to provide feedback to a user in respect to some action (successful resource save, some error occurred, etc).
-Notifications have an ID (system generated), severity (`'success' | 'info' | 'warn' | 'error'`), summary and detail message (optional).
-### NotificationComponent
-The notification component allows for the display of notifications in an application.
-#### Usage
-The notification component should be dropped into the app root so that the display of notifications is available throughout the entire application. Once the component has been placed, no further action is needed. It's up to other components/services to add notifications for display in the notification component.
-### NotificationService
-The notification service is a root `Injectable` that allows components/services throughout an application to add notifications to the notification pool for display.
-#### Usage
-The notification service can be injected into components/services to add a notification through its `add` method, which accepts a notification object, adds it and then removes it after the configured notification life has passed. Notification life (the time before a notification is automatically removed from the view) can also be configured via the service's `setNotificationLife` method.
-#### Methods
-- `add` accepts a notification object and adds it to the current notifications array
-- `deleteNotification` accepts a notification ID and deletes the corresponding notification (if it exists)
-- `getNotifications` get an array of the current notifications as an RxJS Observable
-- `setNotificationLife` set the notification life for new notifications
-
-## ParticleOrdinalNumberPipeModule
-### OrdinalNumberPipe
-The ordinal number pipe transforms a number into an ordinal number (1 => 1st, 2 => 2nd, 3 => 3rd, etc).
-#### Usage
-The ordinal number pipe accepts a number or a numeric string and transforms it into ordinal format.
-#### Name: ordinalNumber
-
-## ParticlePaginatorModule
-### PaginatorComponent
-The paginator component is a widget that provides controls for paginating a list.
-#### Usage
-The paginator component accepts an array of page size options, the current page size, and the total size of the paginated list without pagination applied, and from those inputs calculates the page number display and enables/disables the next/previous pagination buttons. Pagination control interactions emit a `PaginationEvent`, it is up to the parent component to react to that event and update the pagination as a result.
-#### Selector: particle-paginator
-#### Inputs
-- `version` which version of the paginator to user (1-4 available)
-- `pageSizeOptions` an array of numbers representing the available page size options
-- `pageSize` a number representing the currently selected page size
-- `totalLength` the total length of the unpaginated list
-#### Outputs
-- `pagination` event emitted on pagination control interactions, emits a `PaginationEvent` (`{ activePage: number, pageSize: number, totalLength: number }`)
-
-## ParticlePopoverModule
-### PopoverComponent
-The popover component displays a popover with dynamic content around a given target.
-#### Usage
-The popover component is a wrapper around an `ng-content` block and has no content itself. The popover is positioned via its `toggle` method, which accepts an `Event` and positions itself off of the `EventTarget`. If the toggle method is called with an event, and the popover is currently closed, the popover opens and aligns to the event target. If the toggle method is called, and the popover is open or no event is passed in, the popover will close.
-#### Selector: particle-popover
-#### Inputs
-- `offset` the number of pixels to offset the popover from its target
-- `width` the width of the popover (any valid CSS measurement, default `auto`)
-- `height` the height of the popover (any valid CSS measurement, default `auto`)
-#### Outputs
-- `opened` event emitted on popover open
-- `closed` event emitted on popover close
-
-## ParticleProfilePicModule
-### ProfilePicComponent
-The profile pic component displays a round image with a tooltip description to act as a profile picture.
-#### Usage
-The profile pic component accepts an image URL and displays it.
-#### Selector: particle-profile-pic
-#### Inputs
-- `size` the size of the picture
-- `margin` the CSS margin
-- `width` the width of the picture
-- `height` the height of the picture
-- `toolTip` text to pass as the content of the image tooltip
-
-## ParticlePushContainerModule
-### PushContainerComponent
-The push container component serves as a side menu (left or right) which display dynamic content
-#### Usage
-The push container component accepts dynamic content in between its tags and displays it.
-#### Selector: particle-push-container
-#### Inputs
-- `width` the number of pixels wide
-- `showSidePanel` whether to be open on page load (default `false`)
-- `mainContentId` the ID of the main content that will be pushed when the component opens
-- `side` open from the left or right
-- `topOffset` top offset to account for a nav bar
-- `closeOnResize` whether to close the component on window resize (default `false`)
-- `backgroundColorClass` the CSS class to apply to the background of the component
-- `breakpoint` the breakpoint passed which the push container will fill the entire view
-- `hideCloseButton` whether to hide the push container close button (default `false`)
-- `alwaysShowClose` whether to show the close button in desktop view (default `false`)
-#### Outputs
-- `opened` event emitted on push container open
-- `closed` event emitted on push container close
-
-## ParticleRichTextModule
-### RichTextComponent
-The rich text component is an Angular wrapper around a Quill rich text editor.
-#### Usage
-The rich text component accepts an HTML paragraph as a string through either its value input or through one/two-way data-binding via `ngModel`. To read in the value of the editor, you can listen for its `ngModelChange` event (if using `ngModel`) or its `textChanged` event. The value emitted from the component is stringified HTML representing the value of the user's input. Model updates on editor input.
-#### Selector: particle-rich-text
-#### Inputs
-- `value` setter for the internal value of the component
-- `doHideShow` whether to show the rich text controls
-- `height` the height of the editor
-- `readonly` whether the editor is readonly
-- `placeholder` the placeholder to display in the editor if no input
-- `toolbarClassList` CSS class list to apply to the editor toolbar
-- `editorClassList` CSS class list to apply to the editor
-#### Outputs
-- `textChanged` event emitted on text change, emits an object in the following format: `{ htmlValue: string, textValue: string, delta: any, source: any }`
-- `selectionChange` event emitted on editor selection change
-- `init` event emitted on editor init
-
-## ParticleSliderModule
-### SliderComponent
-The slider component allows for the user to select a number from a range using an HTML5 range input or through an HTML5 number input.
-#### Usage
-The slider component accepts a number through either its value input or through one/two-way data-binding via `ngModel`. To read in the value of the component, you can listen for its `ngModelChange` event (if using `ngModel`) or its `input` event. The value emitted from the component is the number selected/input by the user. Model updates on range or number input's `input` event or on the number input's `blur` event.
-#### Selector: particle-slider
-#### Inputs
-- `value` setter for the internal value of the component
-- `min` setter for the minimum value of the selectable range (default 0)
-- `max` setter for the maximum value of the selectable range (default 100)
-- `step` setter for the step size of the number range (default 1)
-- `unit` setter for the unit represented by the component value (purely for display purposes)
-- `disabled` whether the component is disabled
-- `ariaLabel` a string to append to the aria-label for the range/number input
-- `inputClassList` class-list to assign to the number input
-#### Outputs
-- `input` event emitted on range/number input's `input` event, emits the current value of the component
-
-## ParticleTooltipModule
-### TooltipDirective
-The tooltip directive allows for a tooltip to be displayed around an HTML element.
-#### Usage
-The tooltip directive accepts text to display and sets up mouse listeners to show the tooltip on host mouse enter hide on host mouse leave.
-#### Selector: particleTooltip
-#### Inputs
-- `particleTooltip` the tooltip text
-- `tooltipPosition` `'left' | 'right' | 'top' | 'bottom'`
-- `tooltipDisabled` whether the tooltip is disabled
-
-## ParticleWeekPickerModule
-### WeekPickerComponent
-The week picker component allows for a user to select a week of the year via a calendar widget.
-#### Usage
-The week picker accepts input through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the week picker, you can listen for its `ngModelChange` event (if using `ngModel`) or its `weekSelected` event. The value emitted from the component is an object in the form of `{ start: Date, end: Date }` (representing the interval of the selected week). Model updates on week select.
-#### Selector: particle-week-select
-#### Inputs
-- `value` setter for the internal value of the component
-- `disabled` whether the component is disabled
-- `dateRange` object in the form of `{ start: Date, end: Date }` that represents the valid date selection range for the calendar widget
-- `inputClassList` CSS class list to apply to the week display input
-- `calendarButtonClassList` CSS class list to apply to the calendar widget button
-- `ariaLabel` aria label to apply to the component
-- `dateFormat` the Angular date pipe format to apply to the selected week preview
-#### Outputs
-- `weekSelected` event emitted on week select, emits the selected week in the following format: `{ start: Date, end: Date }`
-
-
-## ParticleAccordionModule
-### AccordionComponent
-The accordion component allows for a user to add content within tabs which can expand/collapse the window which contains the content.
-#### Usage
-The accordion component accepts any a text header for each accordion tab with children that contains the content of each accordion tab.
-#### Selector: particle-accordion
-This selector is a parent wrapper of the following selector which contains each item
-#### Inputs
-- `multiple` a boolean attribute that allows the user to change the mode of accordion tabs to either display multiple tabs at once or only display one tab at a time.
-
-#### Selector: particle-accordion-item
-#### Inputs
-- `header` contains the header text value of each accordion tab
-- `particleAccordionContent` value goes under ng-template that associates its children to be the content of the accordion item
-- `disabled` whether the accordion item is disabled
-
-## Usage
-`npm install @entake/particle`
-
-Component listing and usage coming soon.
-
-## Further Help
-
-For more help, please reach out to `nick@entake.io`.
+# Particle for Angular by Entake
+
+This package offers a small selection of reusable components that are meant to replace usage of other Angular component libraries, like Angular Material and PrimeNG. If you're looking for a themeable alternative that gives you unprecedented control of your Angular components, give Particle a try! If you're interested in contributing or find any bugs, feel free to catch us on GitHub.
+
+## ParticleColorPickerModule
+### ColorPickerComponent
+The color picker component is a simple way to choose/input a color in hexadecimal format. It offers a text input that allows for free entry in hexadecimal format along with a color picker for supported browsers. If the browser does not support the HTML5 color picker, it is replaced with a simple color swatch that acts as a preview of the contents of the text input.
+#### Usage
+The color picker accepts a hexadecimal color string (either in short or full form, leading `#` optional, case is ignored) through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the color picker, you can listen for its `ngModelChange` event (if using `ngModel`) or its `colorSelected` event. The value emitted from the component is a full hexadecimal color string (ex: `#0a50d3`). Model updates on every color picker input, every valid text input entry and when the contents of the text input are deleted by the user.
+#### Selector: particle-color-picker
+#### Inputs
+- `value` setter for the internal value of the component
+- `disabled` whether the component should be disabled
+- `ariaLabel` the aria label to set for the color picker/text input
+- `classList` CSS class list to apply to the text input
+#### Outputs
+- `input` event emitted on text input, emits the current value of the component
+- `colorSelected` event emitted on color picker close or on valid hexadecimal string input from the text input, emits the selected color as a hexadecimal string
+
+## ParticleDatePickerModule
+### DatePickerComponent
+The date picker component allows the user to enter a date via a text input (in the form of month/day/year) or through a calendar widget.
+#### Usage
+The date picker accepts a Date object through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the date picker, you can listen for its `ngModelChange` event (if using `ngModel`) or its `dateSelected` event. The value emitted from the component is a Date object representing the user's typed/selected date. Model updates on every calendar widget selection, every valid text input entry and when the contents of the text input are deleted by the user.
+#### Selector: particle-date-picker
+#### Inputs
+- `value` setter for the internal value of the component
+- `disabled` whether the component should be disabled
+- `dateRange` object in the form of `{ minDate: Date, maxDate: Date}` that acts as the valid selection range for the input/calendar widget. Min date must be less than max date. If min date is not provided, the min date is set to January 1st, {currentYear - 100}. If max date is not provided, the max date is set to December 31st, {current year + 50}.
+- `inputId` the ID to assign to the text input
+- `ariaLabel` the aria label to assign to the text input
+- `inputClassList` CSS class list to apply to the text input
+- `calendarButtonClassList` CSS class list to apply to the calendar widget button
+#### Outputs
+- `input` event emitted on text input
+- `dateSelected` event emitted on valid date input/widget date selection, emits the selected date
+### CalendarComponent
+The calendar component displays a calendar widget with accessibility features such as arrow key navigation of calendar dates.
+#### Usage
+The calendar accepts a Date object through its `value` input. To read in the value of the calendar, you can listen for its `selected` event. The value emitted from the component is a Date object representing the user's selection.
+#### Selector: particle-calendar
+#### Inputs
+- `value` setter for the internal value of the component
+- `dateRange` object in the form of { minDate: Date, maxDate: Date} that acts as the valid selection range for the calendar. Min date must be less than max date. If min date is not provided, the min date is set to January 1st, {currentYear - 100}. If max date is not provided, the max date is set to December 31st, {current year + 50}.
+#### Outputs
+- `selected` event emitted on calendar date selection, emits the selected date
+- `closed` event emitted when the user clicks outside the widget, triggers a keyup.escape event or clicks the done button. It is the parent component's responsibility to hide the calendar, the event is merely a signal that action should be taken.
+
+## ParticleDialogModule
+### DialogComponent
+The dialog component displays dynamic content within a dialog and supports nested dialogs within that dynamic content.
+#### Usage
+The dialog component essentially wraps an `ng-content` block. It is the responsibility of the parent component to show/hide the dialog based on its `object` input and `closed` event. The dialog listens for `keyup.escape` events (if enabled) to trigger a dialog close. If you have components in the dynamic dialog content that also rely on escape events to close, those components must listen for keyups on its own focusable elements (as opposed to listening for `window.keyup`) and either stop immediate propagation, or those focusable elements must have the `data-dialog-close-override` attribute on them, or else the escape event will close both the child component and the parent dialog.
+#### Selector: particle-dialog
+#### Inputs
+- `object` an input of type `any` where that input becoming truthy will show the dialog and falsy will hide
+- `title` the title of the dialog. Note: always use the Angular input syntax (`[title]="'Title'"`) to avoid IE11 triggering a native tooltip of the dialog title
+- `titleClass` CSS class to apply to the title section of the dialog
+- `bodyClass` CSS class to apply to the body section of the dialog
+- `showTitle` whether to show the title section of the dialog (default `true`)
+- `allowClose` whether to show the dialog close button and enable escape to close (default `true`)
+- `height` the height of dialog (can be any valid CSS measurement)
+- `width` the width of dialog (can be any valid CSS measurement)
+#### Outputs
+- `opened` event emitted on dialog open
+- `closed` event emitted on dialog close
+
+## ParticleDropdownModule
+### DropdownComponent
+The dropdown component acts as an enhanced HTML select. It supports both regular dropdown options (only the label being displayed) and templated options (options for which you can supply a ng-template to act as a template for each dropdown option). The dropdown is fully accessible as well, and supports all the accessibility options that a native select would (such as arrow key controls for option selection).
+#### Usage
+The dropdown accepts a string or number through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the dropdown, you can listen for its `ngModelChange` event (if using `ngModel`) or its `change` event. The value emitted from the component is a string or number representing the value of the user's selected option. Model updates on every option change, whether it be triggered by clicking on an option or using arrow key controls.
+#### Using Dropdown Options
+The dropdown supports both flat options or option groups, and the options for a single dropdown can be a mix of the two. A dropdown option has a value (string or number), a label, disabled indicator, and an optional data context object (the data context object is not needed if you're not planning to use templating). Whether data context is passed in or not for an option, each option internally will have a data context object which will minimally contain the option's label (inserted into the `$implicit` property if not already taken, or the `label` property if `$implicit` is already present in the object). Dropdown option groups contain a group label, and an array of dropdown options.
+#### Using Dropdown Option Templating
+Dropdown option templating relies on Angular's `ng-template` syntax. To provide an option template to the dropdown, you simply define a `ng-template` as the content of the dropdown. If you do not wish to use templating, pass nothing into the content between the dropdown tags. To display data from an option's data context within the option template, you use Angular's `ng-template` `let-var` syntax. This allows you to define variables within the option template that will then be filled by the corresponding property in an option's data context. As mentioned in the previous section, the option's label is automatically added to each option's data context, so to display the label in the template, you can just define a variable without a value, and it will be filled by the `$implicit` entry. Here's an example of how a typical use case of the dropdown with templating would look:
+
+```html
+  <particle-dropdown [options]="[
+                    { value: 'red', label: 'Red', dataContext: { 'colorClass': 'bg_red' } },
+                    { value: 'green', label: 'Green', disabled: true, dataContext: { 'colorClass': 'bg_green' } },
+                    { value: 'blue', label: 'Blue', dataContext: { 'colorClass': 'bg_blue' } },
+                    { groupLabel: 'Purple Values', options: [
+                        { value: 'darkPurple', label: 'Dark Purple', dataContext: { 'colorClass': 'bg_purple_dark_4' } },
+                        { value: 'purple', label: 'Purple', dataContext: { 'colorClass': 'bg_purple' } },
+                        { value: 'lightPurple', label: 'Light Purple', dataContext: { 'colorClass': 'bg_purple_light_4' } }
+                    ]}
+                 ]">
+    <ng-template let-colorClass="colorClass" let-label>
+      <div class="circle_14px mar_right5"
+           [ngClass]="colorClass">
+      </div> {{label}}
+    </ng-template>
+  </particle-dropdown>
+```
+Notice how, in the `ng-template`, the variable definition value (in quotes) for `colorClass` matches up with the property of the same name in the data context objects for each option. Also notice how the variable definition for `label` has no value assigned, that's because the dropdown component will automatically put an option's label into the `$implicit` property, which Angular uses to fill in the value for any referenced variables that do not have a specified value. You can of course choose to explicitly add the label to the option's data context and use that value in the label variable assignment as well.
+#### Selector: particle-dropdown
+#### Inputs
+- `value` string or number representing the value of the selected option
+- `options` array of `DropdownOption | DropdownOptionGroup` acting as the options to populate the dropdown
+- `disabled` whether the dropdown should be disabled or not
+- `placeholder` placeholder text to show in the dropdown when no option is selected
+- `ariaLabel` aria label to assign to the dropdown
+- `classList` CSS class list to apply to the dropdown
+#### Outputs
+- change: event emitted on dropdown option selection if selection has changed from the previous value, emits the selected value
+
+## ParticleEndpointStateModule
+### EndpointStateComponent
+The endpoint state component serves as a catch-all for displaying endpoint states (loading, not found and error).
+#### Usage
+The endpoint state component is split into four different possible states: loading, loadingOverlay, empty and error. You specify which state the component should be in by passing in `true` to the desired state as an input. Note: only one state should be active at a time.
+#### Inputs
+- `loading` whether the component should be in the loading state
+- `loadingIcon` an icon class to display in the loading state
+- `loadingText` main text to display in the loading state
+- `loadingSubtext` subtext to display in the loading state
+- `loadingOverlay` whether the component should be in the loading overlay state (whole-screen overlay)
+- `loadingOverlayIcon` an icon class to display in the loading overlay state
+- `loadingOverlayText` main text to display in the loading overlay state
+- `loadingOverlaySubtext` subtext to display in the loading overlay state
+- `empty` whether the component should be in the empty (not found) state
+- `emptyIcon` an icon class to display in the empty state
+- `emptyText` main text to display in the empty state
+- `emptySubtext` subtext to display in the empty state
+- `error` whether the component should be in the error state
+- `errorIcon` an icon class to display in the error state
+- `errorText` main text to display in the error state
+- `errorSubtext` subtext to display in the error state
+
+## ParticleIconsModule
+### IconSelectComponent
+The icon select component allows a user to search for and select either a Fontawesome or Particle (custom) icon.
+### Usage
+The icon select accepts an icon class through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the icon select, you can listen for its `ngModelChange` event (if using `ngModel`) or its `selected` event. The value emitted from the component is the selected icon class. Model updates on confirm button click.
+### Inputs
+- `value` setter for the internal value of the component
+- `disabled` whether the component is disabled
+- `buttonColorClass` CSS class to apply to the icon dialog show button
+- `buttonSizing` the size (width/height) of the icon dialog show button in pixels
+#### Outputs
+- `opened` event emitted on icon dialog open
+- `selected` event emitted on icon dialog confirmation, emits the selected icon in the form of `{ value: string }`
+- `closed` event emitted on icon dialog close
+
+## ParticleKeyfilterModule
+### KeyfilterDirective
+Directive to apply to HTML input elements to filter out certain input.
+#### Usage
+Supported filter types are `alpha` (English alphabet only), `numeric` (digits only) and `alphanumeric` (English alphabet and digits).
+#### Selector: particleKeyfilter
+#### Inputs
+- `particleKeyfilter` the filter type to apply to the host input
+- `allowSpaces` whether to allow spaces in input (default `false`)
+
+## ParticleMultiSelectModule
+### MultiSelectComponent
+The multi-select component acts as an enhanced HTML select that allows multiple selections. It supports both regular multi-select options (only the label being displayed) and templated options (options for which you can supply a ng-template to act as a template for each multi-select option). The multi-select is fully accessible as well, and supports all the accessibility options that a multi-select should (such as arrow key controls for option selection).
+#### Usage
+The multi-select accepts an array of strings or numbers through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the multi-select, you can listen for its `ngModelChange` event (if using `ngModel`) or its `change` event. The value emitted from the component is an array of strings or numbers representing the values of the user's selected options. Model updates on every option select/de-select, whether it be triggered by clicking on an option or using arrow key controls.
+#### Using Dropdown Options
+The multi-select supports both flat options or option groups, and the options for a single multi-select can be a mix of the two. A multi-select option has a value (string or number), a label, disabled indicator, and an optional data context object (the data context object is not needed if you're not planning to use templating). Whether data context is passed in or not for an option, each option internally will have a data context object which will minimally contain the option's label (inserted into the `$implicit` property if not already taken, or the `label` property if `$implicit` is already present in the object). Multi-select option groups contain a group label, and an array of multi-select options.
+#### Using Dropdown Option Templating
+Multi-select option templating relies on Angular's `ng-template` syntax. To provide an option template to the multi-select, you simply define a `ng-template` as the content of the multi-select. If you do not wish to use templating, pass nothing into the content between the multi-select tags. To display data from an option's data context within the option template, you use Angular's `ng-template` `let-var` syntax. This allows you to define variables within the option template that will then be filled by the corresponding property in an option's data context. As mentioned in the previous section, the option's label is automatically added to each option's data context, so to display the label in the template, you can just define a variable without a value, and it will be filled by the `$implicit` entry. Here's an example of how a typical use case of the multi-select with templating would look:
+
+```html
+  <particle-multi-select [options]="[
+                    { value: 'red', label: 'Red', dataContext: { 'colorClass': 'bg_red' } },
+                    { value: 'green', label: 'Green', disabled: true, dataContext: { 'colorClass': 'bg_green' } },
+                    { value: 'blue', label: 'Blue', dataContext: { 'colorClass': 'bg_blue' } },
+                    { groupLabel: 'Purple Values', options: [
+                        { value: 'darkPurple', label: 'Dark Purple', dataContext: { 'colorClass': 'bg_purple_dark_4' } },
+                        { value: 'purple', label: 'Purple', dataContext: { 'colorClass': 'bg_purple' } },
+                        { value: 'lightPurple', label: 'Light Purple', dataContext: { 'colorClass': 'bg_purple_light_4' } }
+                    ]}
+                 ]">
+    <ng-template let-colorClass="colorClass" let-label>
+      <div class="circle_14px mar_right5"
+           [ngClass]="colorClass">
+      </div> {{label}}
+    </ng-template>
+  </particle-multi-select>
+```
+Notice how, in the `ng-template`, the variable definition value (in quotes) for `colorClass` matches up with the property of the same name in the data context objects for each option. Also notice how the variable definition for `label` has no value assigned, that's because the multi-select component will automatically put an option's label into the `$implicit` property, which Angular uses to fill in the value for any referenced variables that do not have a specified value. You can of course choose to explicitly add the label to the option's data context and use that value in the label variable assignment as well.
+#### Selector: particle-multi-select
+#### Inputs
+- `value` array of strings or numbers representing the value of the selected options
+- `options` array of `MultiSelectOption | MultiSelectOptionGroup` acting as the options to populate the multi-select
+- `disabled` whether the multi-select should be disabled or not
+- `placeholder` placeholder text to show in the multi-select when no options are selected
+- `ariaLabel` aria label to assign to the multi-select
+- `classList` CSS class list to apply to the multi-select
+#### Outputs
+- `change` event emitted on multi-select option selection if selection has changed from the previous value, emits the selected values
+
+## ParticleNotificationModule
+### Notifications
+A notification is a simple way to provide feedback to a user in respect to some action (successful resource save, some error occurred, etc).
+Notifications have an ID (system generated), severity (`'success' | 'info' | 'warn' | 'error'`), summary and detail message (optional).
+### NotificationComponent
+The notification component allows for the display of notifications in an application.
+#### Usage
+The notification component should be dropped into the app root so that the display of notifications is available throughout the entire application. Once the component has been placed, no further action is needed. It's up to other components/services to add notifications for display in the notification component.
+### NotificationService
+The notification service is a root `Injectable` that allows components/services throughout an application to add notifications to the notification pool for display.
+#### Usage
+The notification service can be injected into components/services to add a notification through its `add` method, which accepts a notification object, adds it and then removes it after the configured notification life has passed. Notification life (the time before a notification is automatically removed from the view) can also be configured via the service's `setNotificationLife` method.
+#### Methods
+- `add` accepts a notification object and adds it to the current notifications array
+- `deleteNotification` accepts a notification ID and deletes the corresponding notification (if it exists)
+- `getNotifications` get an array of the current notifications as an RxJS Observable
+- `setNotificationLife` set the notification life for new notifications
+
+## ParticleOrdinalNumberPipeModule
+### OrdinalNumberPipe
+The ordinal number pipe transforms a number into an ordinal number (1 => 1st, 2 => 2nd, 3 => 3rd, etc).
+#### Usage
+The ordinal number pipe accepts a number or a numeric string and transforms it into ordinal format.
+#### Name: ordinalNumber
+
+## ParticlePaginatorModule
+### PaginatorComponent
+The paginator component is a widget that provides controls for paginating a list.
+#### Usage
+The paginator component accepts an array of page size options, the current page size, and the total size of the paginated list without pagination applied, and from those inputs calculates the page number display and enables/disables the next/previous pagination buttons. Pagination control interactions emit a `PaginationEvent`, it is up to the parent component to react to that event and update the pagination as a result.
+#### Selector: particle-paginator
+#### Inputs
+- `version` which version of the paginator to user (1-4 available)
+- `pageSizeOptions` an array of numbers representing the available page size options
+- `pageSize` a number representing the currently selected page size
+- `totalLength` the total length of the unpaginated list
+#### Outputs
+- `pagination` event emitted on pagination control interactions, emits a `PaginationEvent` (`{ activePage: number, pageSize: number, totalLength: number }`)
+
+## ParticlePopoverModule
+### PopoverComponent
+The popover component displays a popover with dynamic content around a given target.
+#### Usage
+The popover component is a wrapper around an `ng-content` block and has no content itself. The popover is positioned via its `toggle` method, which accepts an `Event` and positions itself off of the `EventTarget`. If the toggle method is called with an event, and the popover is currently closed, the popover opens and aligns to the event target. If the toggle method is called, and the popover is open or no event is passed in, the popover will close.
+#### Selector: particle-popover
+#### Inputs
+- `offset` the number of pixels to offset the popover from its target
+- `width` the width of the popover (any valid CSS measurement, default `auto`)
+- `height` the height of the popover (any valid CSS measurement, default `auto`)
+#### Outputs
+- `opened` event emitted on popover open
+- `closed` event emitted on popover close
+
+## ParticleProfilePicModule
+### ProfilePicComponent
+The profile pic component displays a round image with a tooltip description to act as a profile picture.
+#### Usage
+The profile pic component accepts an image URL and displays it.
+#### Selector: particle-profile-pic
+#### Inputs
+- `size` the size of the picture
+- `margin` the CSS margin
+- `width` the width of the picture
+- `height` the height of the picture
+- `toolTip` text to pass as the content of the image tooltip
+
+## ParticlePushContainerModule
+### PushContainerComponent
+The push container component serves as a side menu (left or right) which display dynamic content
+#### Usage
+The push container component accepts dynamic content in between its tags and displays it.
+#### Selector: particle-push-container
+#### Inputs
+- `width` the number of pixels wide
+- `showSidePanel` whether to be open on page load (default `false`)
+- `mainContentId` the ID of the main content that will be pushed when the component opens
+- `side` open from the left or right
+- `topOffset` top offset to account for a nav bar
+- `closeOnResize` whether to close the component on window resize (default `false`)
+- `backgroundColorClass` the CSS class to apply to the background of the component
+- `breakpoint` the breakpoint passed which the push container will fill the entire view
+- `hideCloseButton` whether to hide the push container close button (default `false`)
+- `alwaysShowClose` whether to show the close button in desktop view (default `false`)
+#### Outputs
+- `opened` event emitted on push container open
+- `closed` event emitted on push container close
+
+## ParticleRichTextModule
+### RichTextComponent
+The rich text component is an Angular wrapper around a Quill rich text editor.
+#### Usage
+The rich text component accepts an HTML paragraph as a string through either its value input or through one/two-way data-binding via `ngModel`. To read in the value of the editor, you can listen for its `ngModelChange` event (if using `ngModel`) or its `textChanged` event. The value emitted from the component is stringified HTML representing the value of the user's input. Model updates on editor input.
+#### Selector: particle-rich-text
+#### Inputs
+- `value` setter for the internal value of the component
+- `doHideShow` whether to show the rich text controls
+- `height` the height of the editor
+- `readonly` whether the editor is readonly
+- `placeholder` the placeholder to display in the editor if no input
+- `toolbarClassList` CSS class list to apply to the editor toolbar
+- `editorClassList` CSS class list to apply to the editor
+#### Outputs
+- `textChanged` event emitted on text change, emits an object in the following format: `{ htmlValue: string, textValue: string, delta: any, source: any }`
+- `selectionChange` event emitted on editor selection change
+- `init` event emitted on editor init
+
+## ParticleSliderModule
+### SliderComponent
+The slider component allows for the user to select a number from a range using an HTML5 range input or through an HTML5 number input.
+#### Usage
+The slider component accepts a number through either its value input or through one/two-way data-binding via `ngModel`. To read in the value of the component, you can listen for its `ngModelChange` event (if using `ngModel`) or its `input` event. The value emitted from the component is the number selected/input by the user. Model updates on range or number input's `input` event or on the number input's `blur` event.
+#### Selector: particle-slider
+#### Inputs
+- `value` setter for the internal value of the component
+- `min` setter for the minimum value of the selectable range (default 0)
+- `max` setter for the maximum value of the selectable range (default 100)
+- `step` setter for the step size of the number range (default 1)
+- `unit` setter for the unit represented by the component value (purely for display purposes)
+- `disabled` whether the component is disabled
+- `ariaLabel` a string to append to the aria-label for the range/number input
+- `inputClassList` class-list to assign to the number input
+#### Outputs
+- `input` event emitted on range/number input's `input` event, emits the current value of the component
+
+## ParticleTooltipModule
+### TooltipDirective
+The tooltip directive allows for a tooltip to be displayed around an HTML element.
+#### Usage
+The tooltip directive accepts text to display and sets up mouse listeners to show the tooltip on host mouse enter hide on host mouse leave.
+#### Selector: particleTooltip
+#### Inputs
+- `particleTooltip` the tooltip text
+- `tooltipPosition` `'left' | 'right' | 'top' | 'bottom'`
+- `tooltipDisabled` whether the tooltip is disabled
+
+## ParticleWeekPickerModule
+### WeekPickerComponent
+The week picker component allows for a user to select a week of the year via a calendar widget.
+#### Usage
+The week picker accepts input through either its `value` input or through one/two-way data-binding via `ngModel`. To read in the value of the week picker, you can listen for its `ngModelChange` event (if using `ngModel`) or its `weekSelected` event. The value emitted from the component is an object in the form of `{ start: Date, end: Date }` (representing the interval of the selected week). Model updates on week select.
+#### Selector: particle-week-select
+#### Inputs
+- `value` setter for the internal value of the component
+- `disabled` whether the component is disabled
+- `dateRange` object in the form of `{ start: Date, end: Date }` that represents the valid date selection range for the calendar widget
+- `inputClassList` CSS class list to apply to the week display input
+- `calendarButtonClassList` CSS class list to apply to the calendar widget button
+- `ariaLabel` aria label to apply to the component
+- `dateFormat` the Angular date pipe format to apply to the selected week preview
+#### Outputs
+- `weekSelected` event emitted on week select, emits the selected week in the following format: `{ start: Date, end: Date }`
+
+
+## ParticleAccordionModule
+### AccordionComponent
+The accordion component allows for a user to add content within tabs which can expand/collapse the window which contains the content.
+#### Usage
+The accordion component accepts any a text header for each accordion tab with children that contains the content of each accordion tab.
+#### Selector: particle-accordion
+This selector is a parent wrapper of the following selector which contains each item
+#### Inputs
+- `multiple` a boolean attribute that allows the user to change the mode of accordion tabs to either display multiple tabs at once or only display one tab at a time.
+
+#### Selector: particle-accordion-item
+#### Inputs
+- `header` contains the header text value of each accordion tab
+- `particleAccordionContent` value goes under ng-template that associates its children to be the content of the accordion item
+- `disabled` whether the accordion item is disabled
+
+## Usage
+`npm install @entake/particle`
+
+Component listing and usage coming soon.
+
+## Further Help
+
+For more help, please reach out to `nick@entake.io`.