Add support for additional callout variants (#201)

* Create callout variants; color scheme TBD

* Apply new color schemes to callouts

---------

Co-authored-by: Cameron James <[email protected]>

_data/header-nav.yml

@@ -109,7 +109,7 @@
         - title: Contributor's Guide
           blurb: Learn how to contribute to SwimOS and SwimOS docs.
           icon: "fa-solid fa-screwdriver-wrench"
-          url: https://www.swimos.org/meta/contribute.html
+          url: /meta/contribute.html
   more:
     - name: YouTube
       icon: "fa-brands fa-youtube"

_includes/callout-bad.html

@@ -0,0 +1,19 @@
+{% capture passThroughTitle %}
+{{ include.title }}
+{% endcapture %}
+
+{% capture passThroughText %}
+{{ include.text }}
+{% endcapture %}
+
+{% include
+  callout-base.html
+  icon="fa-solid fa-circle-xmark"
+  iconColor="text-callout-bad-icon"
+  backgroundColor="bg-callout-bad-fill"
+  border="border bg-callout-bad-border"
+  title=passThroughTitle
+  titleStyles='bg-callout-bad-text'
+  text=passThroughText
+  textStyle='text-callout-bad-text [&_strong]:text-callout-bad-text-accent [&_a]:text-callout-bad-text-accent'
+%}

_includes/callout-base.html

@@ -0,0 +1,30 @@
+
+{% if include.title or include.text %}
+<div class="rounded-md {{ include.backgroundColor }} p-4 my-5 border {{ include.border }}">
+  <div class="flex">
+      <div class="flex-shrink-0">
+          {% if include.icon %}
+            <div class="callout-icon-container h-8 w-8 flex justify-center items-center">
+              <i class="text-[24px] h-6 w-6 {{ include.icon }} {{ include.iconColor }}" />
+            </div>
+          {% else %}
+            <p>include.icon not found</p>
+          {% endif %}
+      </div>
+      <div class="ml-3">
+          {% if include.title %}
+              <h3 class="text-lg font-medium {{ include.textStyle or 'text-swim-body-text' }} mt-1 no_toc">
+                  {{ include.title }}
+              </h3>
+          {% endif %}
+          {% if include.text %}
+              <div class="mt-2 text-sm {{ include.textStyle or 'text-swim-body-text' }}">
+                  <p>
+                    {{ include.text }}
+                  </p>
+              </div>
+          {% endif %}
+      </div>
+  </div>
+</div>
+{% endif %}

_includes/callout-info.html

@@ -0,0 +1,19 @@
+{% capture passThroughTitle %}
+{{ include.title }}
+{% endcapture %}
+
+{% capture passThroughText %}
+{{ include.text }}
+{% endcapture %}
+
+{% include
+  callout-base.html
+  icon="fa-solid fa-circle-info"
+  iconColor="text-callout-info-icon"
+  backgroundColor="bg-callout-info-fill"
+  border="border border-callout-info-border"
+  title=passThroughTitle
+  titleStyles='text-callout-info-text'
+  text=passThroughText
+  textStyle='text-callout-info-text [&_strong]:text-callout-info-text-accent [&_a]:text-callout-info-text-accent'
+%}

_includes/callout-ok.html

@@ -0,0 +1,19 @@
+{% capture passThroughTitle %}
+{{ include.title }}
+{% endcapture %}
+
+{% capture passThroughText %}
+{{ include.text }}
+{% endcapture %}
+
+{% include
+  callout-base.html
+  icon="fa-solid fa-circle-check"
+  iconColor="text-callout-ok-icon"
+  backgroundColor="bg-callout-ok-fill"
+  border="border text-callout-ok-border"
+  title=passThroughTitle
+  titleStyles='text-callout-ok-text'
+  text=passThroughText
+  textStyle='text-callout-ok-text [&_strong]:text-callout-ok-text-accent [&_a]:text-callout-ok-text-accent'
+%}

_includes/callout-warning.html

@@ -0,0 +1,19 @@
+{% capture passThroughTitle %}
+{{ include.title }}
+{% endcapture %}
+
+{% capture passThroughText %}
+{{ include.text }}
+{% endcapture %}
+
+{% include
+  callout-base.html
+  icon="fa-solid fa-triangle-exclamation"
+  iconColor="text-callout-warning-icon"
+  backgroundColor="bg-callout-warning-fill"
+  border="border text-callout-warning-border"
+  title=passThroughTitle
+  titleStyles='text-callout-warning-text'
+  text=passThroughText
+  textStyle='text-callout-warning-text [&_strong]:text-callout-warning-text-accent [&_a]:text-callout-warning-text-accent'
+%}

src/_backend/command-lanes.md

@@ -164,7 +164,7 @@ class CustomClient {
 }
 ```
 
-{% include alert.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different command lanes within our <strong>UnitAgent</strong> with laneUri <strong>"takeAction"</strong>; how would the Swim runtime know which one to message? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
+{% include callout-warning.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different command lanes within our <strong>UnitAgent</strong> with laneUri <strong>"takeAction"</strong>; how would the Swim runtime know which one to message? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
 
 Note that the `command()` signature only allows for `swim.structure.Value` payloads. Lanes internally use *forms* to handle any necessary conversions, allowing users to treat lanes as properly parametrized data types, provided that a form for that data type exists. Even a custom Java class can be a lane type, provided that a form for that class exists. We will further discuss this topic in a more advanced cookbook.
 

src/_backend/demand-map-lanes.md

@@ -84,7 +84,7 @@ public class UnitAgent extends AbstractAgent {
 }
 ```
 
-{% include alert.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how does the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
+{% include callout-warning.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how does the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
 
 ### Linking to Map Lane and `cue(K key)`
 

src/_backend/demand-value-lanes.md

@@ -79,7 +79,7 @@ public class UnitAgent extends AbstractAgent {
 }
 ```
 
-{% include alert.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how does the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
+{% include callout-warning.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how does the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
 
 ### Linking to Value Lane and `cue()`
 

src/_backend/downlinks.md

@@ -93,7 +93,7 @@ Server-side, downlinks are explained in the [Server Downlinks guide]({% link _ba
 
 ### JavaScript
 
-For details on using downlinks with JavaScript, visit the [**downlinks**]({% link _frontend/downlinks.md %}) article in our [**frontend documentation**](/frontend)
+For details on using downlinks with JavaScript, visit the [**downlinks**]({% link _frontend/downlinks.md %}) article in our [**frontend documentation**](https://www.swimos.org/frontend/)
 
 Furthermore, the tutorial application demonstrates [using value downlinks](https://github.com/swimos/tutorial/blob/master/ui/pie.html#L58-L67){:data-proofer-ignore=''} and [map downlinks](https://github.com/swimos/tutorial/blob/master/ui/chart.html#L69-L79){:data-proofer-ignore=''} issued against a Swim client instance. Note the language-level loss of parametrization, but the otherwise-identical syntax to Java.
 

src/_backend/jms-ingestion.md

@@ -141,7 +141,7 @@ public class JmsAgent extends AbstractAgent {
 }
 ```
 
-{% include alert.html title='Warning' text='When we configure the Web Agent node URI routing paths (e.g. within <strong>server.recon</strong>), ensure that only one instance of <strong>JmsAgent</strong> can be instantiated.' %}
+{% include callout-warning.html title='Warning' text='When we configure the Web Agent node URI routing paths (e.g. within <strong>server.recon</strong>), ensure that only one instance of <strong>JmsAgent</strong> can be instantiated.' %}
 
 ### Step 3: `VehicleAgent` Implementation
 

src/_backend/join-value-lanes.md

@@ -78,7 +78,7 @@ public class BuildingAgent extends AbstractAgent {
 }
 ```
 
-{% include alert.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
+{% include callout-warning.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
 
 ### Aggregating value lanes
 

src/_backend/kafka-ingestion.md

@@ -142,7 +142,7 @@ public class KafkaConsumingAgent extends AbstractAgent {
 _Note: because `KafkaConsumingAgent` is the only class that that actively uses the `KafkaConsumer` class, you may choose to instantiate the `KafkaConsumer` instance from `KafkaConsumingAgent` instead._
 _The current approach has the advantage of "fast-failing" the process, avoiding any part of the Swim server from starting if there is an issue reaching the Kafka topic._
 
-{% include alert.html title='Warning' text='When we configure the Web Agent nodeUri routing paths (e.g. within <strong>server.recon</strong>), ensure that only one instance of <strong>KafkaConsumingAgent</strong> can be instantiated.' %}
+{% include callout-warning.html title='Warning' text='When we configure the Web Agent nodeUri routing paths (e.g. within <strong>server.recon</strong>), ensure that only one instance of <strong>KafkaConsumingAgent</strong> can be instantiated.' %}
 
 ### Step 3: `VehicleAgent` Implementation and Routing
 

src/_backend/map-lanes.md

@@ -85,7 +85,7 @@ public class UnitAgent extends AbstractAgent {
 }
 ```
 
-{% include alert.html title='Caution' text='If you have multiple lanes within an agent type, ensure that their <strong>laneUri</strong>s are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>. How will the Swim runtime know which one to set? That said, reusing <strong>laneUri</strong>s **across** Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different <strong>nodeUri</strong>s.' %}
+{% include callout-warning.html title='Caution' text='If you have multiple lanes within an agent type, ensure that their <strong>laneUri</strong>s are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>. How will the Swim runtime know which one to set? That said, reusing <strong>laneUri</strong>s **across** Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different <strong>nodeUri</strong>s.' %}
 
 ### External Addressability
 

src/_backend/mongodb-ingestion.md

@@ -153,7 +153,7 @@ public class MongoDbPollingAgent extends AbstractAgent {
 }
 ```
 
-{% include alert.html title='Warning' text='When we configure the Web Agent node URI routing paths (e.g. within <strong>server.recon</strong>), ensure that only one instance of <strong>MongoDbPollingAgent</strong> can be instantiated.' %}
+{% include callout-warning.html title='Warning' text='When we configure the Web Agent node URI routing paths (e.g. within <strong>server.recon</strong>), ensure that only one instance of <strong>MongoDbPollingAgent</strong> can be instantiated.' %}
 
 ### Step 3: `VehicleAgent` Implementation
 

src/_backend/value-lanes.md

@@ -81,7 +81,7 @@ public class UnitAgent extends AbstractAgent {
 }
 ```
 
-{% include alert.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how does the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
+{% include callout-warning.html title='Caution' text='If you have multiple lanes within an Agent type, ensure that their laneUris are not identical. Suppose we declare two different value lanes within our <strong>UnitAgent</strong> with laneUri <strong>"info"</strong>; how does the Swim runtime know which one to set? That said, reusing laneUris <strong>across</strong> Agent types is perfectly acceptable, as requests corresponding to these are guaranteed to have different nodeUris.' %}
 
 ### External Addressability
 

src/_backend/web-agents.md

@@ -106,7 +106,7 @@ A Dynamic Web Agent is only instantiated when its `nodeUri` is invoked for the f
 With the code we have so far, we can instantiate any number of `UnitAgent`s by either defining them in the configuration file or by invoking URIs with the `"/unit/"` prefix. 
 For example, if we invoke `"/unit/1"`, `"/unit/foo"`, and `"/unit/foo_1"`, three `UnitAgent`s will be instantiated, one for each URI.
 
-{% include alert.html title='Caution' text='If you have multiple agent types within a plane, ensure that their URI patterns do not **clash**. This is a stricter requirement than saying that the patterns are <strong>identical</strong>; for example, <strong>"/unit/:id"</strong> and <strong>"/unit/:foo"</strong> clash. Suppose these same patterns annotated different agent types; how would a plane know which type of Agent to seek or instantiate for the request <strong>"/unit/1"</strong>?' %}
+{% include callout-warning.html title='Caution' text='If you have multiple agent types within a plane, ensure that their URI patterns do not **clash**. This is a stricter requirement than saying that the patterns are <strong>identical</strong>; for example, <strong>"/unit/:id"</strong> and <strong>"/unit/:foo"</strong> clash. Suppose these same patterns annotated different agent types; how would a plane know which type of Agent to seek or instantiate for the request <strong>"/unit/1"</strong>?' %}
 
 In addition to the `nodeUri()` method mentioned in the previous section, every Agent also has access to a `Value getProp(String prop)` convenience method. 
 This returns a `swim.structure.Text` object containing the value of the dynamic `nodeUri` component with the name `prop`, `absent()` if it doesn't exist. 

src/_frontend/dataModel.md

@@ -7,7 +7,7 @@ layout: documentation
 redirect_from:
 ---
 
-{% include alert.html title='Version Note' text='This documentation describes Swim JS packages v4.0.0-dev-20230923 or later. Users of earlier package versions may experience differences in behavior.' %}
+{% include callout-warning.html title='Version Note' text='This documentation describes Swim JS packages v4.0.0-dev-20230923 or later. Users of earlier package versions may experience differences in behavior.' %}
 
 ## Overview
 

src/_frontend/downlinks.md

@@ -7,7 +7,7 @@ layout: documentation
 redirect_from:
 ---
 
-{% include alert.html title='Version Note' text='This documentation describes Swim JS packages v4.0.0-dev-20230923 or later. Users of earlier package versions may experience differences in behavior.' %}
+{% include callout-warning.html title='Version Note' text='This documentation describes Swim JS packages v4.0.0-dev-20230923 or later. Users of earlier package versions may experience differences in behavior.' %}
 
 A Downlink provides a virtual bidirectional stream between the client and a lane of a remote Web Agent. WARP clients transparently multiplex all links to [**Web Agents**]({% link _backend/web-agents.md %}) on a given host over a single WebSocket connection.
 

src/_frontend/eventDownlink.md

@@ -7,7 +7,7 @@ layout: documentation
 redirect_from:
 ---
 
-{% include alert.html title='Version Note' text='This documentation describes Swim JS packages v4.0.0-dev-20230923 or later. Users of earlier package versions may experience differences in behavior.' %}
+{% include callout-warning.html title='Version Note' text='This documentation describes Swim JS packages v4.0.0-dev-20230923 or later. Users of earlier package versions may experience differences in behavior.' %}
 
 `EventDownlink` is not so much a subtype of `Downlink` as it is the base type of all downlinks. While not literally a superclass of `ValueDownlink`, and `MapDownlink`, `EventDownlink` inherits from the same prototype as the others but contains no additional frills. For example, `MapDownlink` supports registering different callbacks for observing when a key-value pair has been added versus when one has been removed; and `ValueDownlink` has the `didSet` callback for when its synced value has been updated. `EventDownlink`, on the other hand, offers no specialized handling of WARP messages with respect to the type of Web Agent lane it is connected to. It provides a raw view of a WARP link, passing all received updates to a single `onEvent` callback.