Merge 1e3039a into 8dd558b

docs/content/docs/alert/api.um

@@ -0,0 +1,2 @@
+@api Alert
+  @inline api/*.um

docs/content/docs/alert/api/auto.um

@@ -0,0 +1,119 @@
+@prototype Alert
+  @added nextReleaseVersion
+
+  @description
+    The constructor for the alerts used by @code[hx.alert] and @code[hx.message]
+
+  @method close
+    @description
+      Closes this alert
+
+@prototype hx.AlertManager
+  @added nextReleaseVersion
+  @description
+    The constructor for creating a custom alert manager. The @code[alert] and @code[message] methods use the default alert manager that creates a container within @code[body]
+
+  @constructor
+    @arg selector [String/Selection/HTMLElement]
+      @description
+        The selector for the element the container should be created inside
+
+    @arg options [Object]
+      @property minMessageDuration [Number]
+        @description
+          Sets the minMessageDuration for the alerts/messages shown from this alert manager (in milliseconds)
+
+          This controls the minimum duration messages should be displayed for when not passing in @code[duration] to the
+          @code[message] method.
+
+          This is not used when a length is specified in the @code[message] options.
+
+        @default: 2000
+
+      @property maxMessageDuration [Number]
+        @description
+          Sets the maxMessageDuration for the alerts/messages shown from this alert manager (in milliseconds)
+
+          This controls the maximum duration messages should be displayed for when not passing in @code[duration] to the
+          @code[message] method.
+
+          This is not used when a length is specified in the @code[message] options.
+
+        @default: 7000
+
+      @property animationInDuration [Number]
+        @description
+          Sets the animationInDuration for the alerts/messages shown from this alert manager (in milliseconds)
+
+          This controls how long it takes for the alerts/messages to appear when closing (i.e. the animation duration)
+
+        @default: 200
+
+      @property animationOutDuration [Number]
+        @description
+          Sets the animationOutDuration for the alerts/messages shown from this alert manager (in milliseconds)
+
+          This controls how long it takes for the alerts/messages to disappear when closing (i.e. the animation duration)
+
+        @default: 200
+
+
+
+@function hx.alert
+  @added nextReleaseVersion
+
+  @description
+    Displays an alert notification that can only be dismissed by the user clicking the close button or by calling the @code[close] method.
+
+    This utilises the inbuilt alert manager that will add the alert container to the @code[body]
+
+  @arg options [Object]
+    @property title [String]
+      @description
+        The title to display in bold in the alert. This should be a short summary of the alert.
+
+    @property body [String]
+      @description
+        The main alert body to display next to the title.
+
+    @property? type [String]
+      @description
+        The type of message. Can be @code[success], @code[danger], @code[warning] or @code[undefined]
+
+
+  @returns Alert
+    @description
+      The alert that was added
+
+@function hx.message
+  @added nextReleaseVersion
+
+  @description
+    Displays an alert notification that can only be dismissed by the user clicking the close button or by calling the @code[close] method.
+
+    This utilises the inbuilt alert manager that will add the alert container to the @code[body]
+
+  @arg options [Object]
+    @property title [String]
+      @description
+        The title to display in bold in the alert. This should be a short summary of the alert.
+
+    @property body [String]
+      @description
+        The main alert body to display next to the title.
+
+    @property? type [String]
+      @description
+        The type of message. Can be @code[success] or @code[undefined]
+
+    @property? duration [Number]
+      @description
+        The time (in milliseconds) that the message shoiuld display. When undefined, this value is calcuated
+        using @code[Math.min(Math.max(numCharacters, minMessageDuration), maxMessageDuration)]
+
+        @code[minMessageDuration] is 2000 and @code[maxMessageDuration] is 7000 by default.
+
+
+  @returns Alert
+    @description
+      The alert that was added

docs/content/docs/alert/changelog/index.um

@@ -0,0 +1,12 @@
+@inline /templates/sidebar-page.um
+
+@topSection
+  @title Alert Changelog
+
+@contentSection
+  @changelogList
+    @groupByApi false
+    @reverseVisibleList true
+    @inline /templates/versions.um
+    @process
+      @inline ../api.um

docs/content/docs/alert/examples/auto.um

@@ -0,0 +1,45 @@
+@version nextReleaseVersion
+  @examples
+    @example
+      @@html
+        <div id="alertsDemo"></div>
+
+      @@js
+        hx.select('#alertsDemo')
+          .set([
+            hx.div('hx-header-small').text('Alerts'),
+            hx.detached('br'),
+            hx.button('hx-btn hx-flag-button').text('Success').on('click', () => hx.alert({
+              title: 'This is a success alert.',
+              body: 'Use it to let users know that something was successful.',
+              type: 'success',
+            })),
+            hx.button('hx-btn hx-flag-button').text('Warning').on('click', () => hx.alert({
+              title: 'This is a warning alert.',
+              body: 'Use it to tell users about something that could be a problem, but won\'t block them from doing things yet.',
+              type: 'warning',
+            })),
+            hx.button('hx-btn hx-flag-button').text('Danger').on('click', () => hx.alert({
+              title: 'This is an error alert.',
+              body: 'Use it to tell users about errors. Include steps that the user can take to resolve the error, even if it\'s just "Try again".',
+              type: 'danger',
+            })),
+            hx.button('hx-btn hx-flag-button').text('Default').on('click', () => hx.alert({
+              title: 'This is an information alert.',
+              body: 'Use it for alerts that don\'t fit into the other three categories.',
+            })),
+            hx.detached('br'),
+            hx.detached('br'),
+            hx.detached('hr'),
+            hx.div('hx-header-small').text('Messages'),
+            hx.detached('br'),
+            hx.button('hx-btn hx-flag-button').text('Success').on('click', () => hx.message({
+              title: 'This is a success message.',
+              body: 'Use it to let users know that something was successful.',
+              type: 'success',
+            })),
+            hx.button('hx-btn hx-flag-button').text('Default').on('click', () => hx.message({
+              title: 'This is an information message.',
+              body: 'Use it for messages that don\'t fit into the other three categories.',
+            })),
+          ]);

docs/content/docs/alert/index.um

@@ -0,0 +1,47 @@
+@inline /templates/sidebar-page.um
+@inline /templates/versioned-page.um
+
+@topSection
+  @source [{{editPageUrl}}]: Edit Page
+  @title Alerts and Messages
+  @description
+    Provides the @code[alert] and @code[message] functions
+
+
+@contentSection
+  @topic About
+    Alerts and messages are essentially the same, with messages being a sub-type of alerts.
+    The key difference between messages and alerts is that messages will auto-dismiss themselves
+    after a set duration and do not show a close button, while alert will persist on screen until
+    the close button is clicked. Both @code[message] and @code[alert] return an @code[Alert] and have
+    the same methods available.
+
+    Messages should be used to show information that is useful for the user to know, but isn’t critical, or too complex.
+    The best example of success message stating a task was completed successfully. Without the message the user will
+    not know if the system was able to complete the task. If the user finds they need to dismiss the message and it is too
+    distracting to the workflow, this is a good case to use message instead of alert.
+
+
+  @topic Alert Types
+    @b[Default]: use as informational/neutral alerts.
+
+    @b[Success]: use to inform of successful completion of a task.
+
+    @b[Warning]: use to alert of issues that do not require the user to take action, but be aware of them.
+
+    @b[Danger]: use to inform user of errors and unsuccessful completion of tasks. It is advised to provide advice on how to resolve the issue in the alert.
+
+  @topic Message Types
+    @b[Default]: use as informational/neutral messages.
+
+    @b[Success]: use to inform of successful completion of a task.
+
+  @topic Examples
+    @examples
+      @versioned
+        @inline examples/*.um
+
+  @topic Api
+    @hyperlink(/docs/alert/changelog)[Change Log]
+
+    @inline api.um

docs/content/templates/sidebar-page.um

@@ -58,6 +58,7 @@
             @page /docs/table/: Table
 
           @section Js Components
+            @page /docs/alert/: Alerts and Messages
             @page /docs/autocomplete-picker/: Autocomplete Picker
             @page /docs/autocomplete/: Autocomplete
             @page /docs/button-group/: Button Group