Advanced timeline filtering docs (#209)

* advanced filtering docs and updates

docs/planning/timeline-editing.mdx

@@ -1,7 +1,8 @@
 import timelineEditor from './assets/timeline-editor.png';
 import timelineRowEditor from './assets/timeline-row-editor.png';
-import timelineActivityOptionsEditor from './assets/timeline-activity-options-editor.png';
+import timelineDiscreteOptionsEditor from './assets/timeline-discrete-options-editor.png';
 import timelineActivityOptionsMode from './assets/timeline-activity-options-mode.png';
+import timelineActivityFilteringModal from './assets/timeline-activity-filtering-modal.png';
 import timelineYAxisSettings from './assets/timeline-y-axis-settings.png';
 import timelineActivityTree from './assets/timeline-activity-tree.png';
 import timelineActivityEditingDemo from './assets/timeline-activity-layer-adding.mov';
@@ -49,54 +50,108 @@ Edit row properties from within the timeline row editor. If multiple rows exist
 
 ### Add an Activity Layer
 
-To visualize activities on the timeline add a new layer using the plus button in the Layers section. By default new layers have a layer type of Activity. Additionally, the default Aerie UI view creates a row with a single activity layer with all activities grouped by type. Manage which activities are visualized in an activity layer by clicking on the search input for the layer and selecting activities. Activities can be filtered by substring match using the input. Once you have a filter applied you can also select all matches using the Select X activities button at the bottom of the result list. You can also manage the color of the layer using the color picker. All activity layers within a row are drawn on the same canvas so that all of the activities are grouped and packed together correctly. Below is a demonstration of this workflow.
+To visualize activities on the timeline, add a new activity layer using the plus button in the Activity Layers section. The default Aerie UI view creates a row with a single activity layer with all activities grouped by type. Manage which activities are visualized in an activity layer by clicking on the Activity Layer filter button within the layer. Activity filtering will be explained in the next section. You can also manage the color of the activities rendered by this layer using the color picker. All activity layers within a single row are drawn on the same canvas so that all of the activities are grouped and packed together correctly. Below is a demonstration of this workflow.
 
 <video controls>
   <source src={timelineActivityEditingDemo} />
 </video>
 
-### Manage how Activities are Rendered
+### Filter Activities
 
-An Activity Options section will appear in the row editor when the row has at least one activity layer. Activity options govern how activities are rendered for this row.
+Each activity layer can be configured with a custom filter on activity types and directive/span instance properties. Clicking on the default Activity Layer button on a layer will open the Activity Filtering overlay. This overlay can be repositioned by dragging on the top bar of the overlay. The overlay can also be resized using the resize handle in the bottom right of the overlay. With this overlay you can:
+
+- Manually specify activity types to include in the layer
+- Dynamically specify activity types to include in the layer by type name and/or subsystem
+- Apply other filters on top of the manual and dynamic type filters that target specific directives/spans. This includes
+  filtering by tags, activity name, scheduling goal id, and activity parameter values. These filters can also be applied to specific activity types.
 
 <figure>
   <img
-    alt="Aerie UI - Timeline Activity Options"
-    src={timelineActivityOptionsEditor}
+    alt="Aerie UI - Activity Filtering"
+    src={timelineActivityFilteringModal}
     style={{ maxHeight: '100%', width: '100%' }}
   />
-  <figcaption>Figure 3: Aerie UI Timeline Activity Options Editor - Manage Activity Rendering</figcaption>
+  <figcaption>Figure 3: Aerie UI Activity Filtering</figcaption>
 </figure>
 
-#### 1. Activity Display Mode
+#### 1. Layer Name
+
+Change the activity layer name. It is recommended that you name your activity layers when you have multiple activity layers within a row in order to better keep track of what your layers are filtering on. No name is automatically generated from your filters.
+
+#### 2. Manually Select Types
+
+Manually select specific activity types to render in the activity layer. This is useful when you want tighter control over a small set of activity types.
+
+#### 3. Dynamically Select Types
+
+Dynamically select activity types by type name and/or subsystem. Click on the filter with the plus button to add a new clause. For example, you could create a filter such as `Type includes "banana"` to match all activity types that include the string banana. This matching is case insensitive. Each clause is ANDed together, so if you add another clause such as `Type does not include "grow"` the final statement would be `Type includes "banana" AND does not include "grow"`. Dynamic type filters are stored as clauses within the UI View so that they can be dynamically applied to any model.
+
+:::info Note
+The resulting activity types for a filter are determined using the union of the manual and dynamic types. If no manual or dynamic type filters are added, all activity types are by default included.
+:::
 
-Activities can be rendered in two ways:
+#### 4. Other Activity filters
 
-- `Grouped Mode`: Activities are recursively grouped by type. In this mode, activity groups appear in the left side of the row and can be expanded to reveal the directives and spans within each type group. If a directive/span has descendents, the directive/span can be expanded to reveal its grouped descendents. This behavior continues down the decomposition tree until the resulting directive/span has no descendents. This mode is useful for understanding larger sets of activities in a broad sense across an entire plan, especially if the plan is long or contains a significant number of activities that cannot easily be visualized in a small area.
-- `Compact Mode`: Activities from all of the layers are packed together in a space efficient waterfall manner. This mode is useful for visualizing smaller sets of activities in a more traditional timeline view. In this mode the row will not autosize and must be manually adjusted to accommodate the current activity packing solution. This allows for a more precise adjustment of the density in the timeline.
+Filter activity directive and span instances by tags, activity name, scheduling goal id, and activity parameter values. These filters apply to the set of manually and dynamically selected types (or all types if none specified). These filters behave similarly to dynamic types – each clause is ANDed together. For example, you could create a filter such as `Tag includes (FOO or "Bar") AND Parameter "biteSize" equals 1`. The list of parameters is filtered by the list of resulting activity types. Additionally, parameters are uniquely identified in the filter by the combination of parameter name and parameter type. Parameter filtering works across activity types when the parameter name + type is shared - a common use case when multiple spacecraft are being modeled that share certain parameters.
+
+##### 5. Resulting Types
+
+This section shows the list of types resulting from the manually and dynamically selected types. If no manual or dynamic filters have been specified, all types in the model will be included. The indicator to the right of the Resulting Types text shows the number of resulting types followed by the number of "instances" which is the number of directives and spans (where each span does not have a direct parent directive) that match your filters.
+
+##### 6. Resulting Type Filter
+
+Add other filters (see 4) to a specific activity type in order to further filter instances of that type.
+
+### Manage how Activities and Events are Rendered
+
+A Layer Options section will appear in the row editor when the row has at least one activity or event layer. Layer Options affect how activities and events are rendered for this row.
+
+<figure>
+  <img
+    alt="Aerie UI - Timeline Discrete Options"
+    src={timelineDiscreteOptionsEditor}
+    style={{ maxHeight: '100%', width: '100%' }}
+  />
+  <figcaption>Figure 4: Aerie UI Timeline Discrete Options Editor - Manage Activity and Event Rendering</figcaption>
+</figure>
+
+#### 1. Height
+
+Sets the height of activities and events in the row.
+
+#### 2. Display Mode
+
+Activities and events can be rendered in two ways:
+
+- `Grouped Mode`: Activities are recursively grouped by type. In this mode, activity groups appear in the left side of the row and can be expanded to reveal the directives and spans within each type group. If a directive/span has descendant, the directive/span can be expanded to reveal its grouped descendants. This behavior continues down the decomposition tree until the resulting directive/span has no descendants. This mode is useful for understanding larger sets of activities in a broad sense across an entire plan, especially if the plan is long or contains a significant number of activities that cannot easily be visualized in a small area. Events render in a similar manner to activities.
+- `Compact Mode`: Activities from all of the layers are packed together in a space efficient waterfall manner. This mode is useful for visualizing smaller sets of activities in a more traditional timeline view. In this mode the row will not autosize and must be manually adjusted to accommodate the current activity packing solution. This allows for a more precise adjustment of the density in the timeline. Events render in a similar manner to activities.
 
 <figure>
   <img
     alt="Aerie UI - Timeline Activity Display Mode"
     src={timelineActivityOptionsMode}
     style={{ maxHeight: '100%', width: '100%' }}
   />
-  <figcaption>Figure 4: Aerie UI Timeline Activity Options Display Mode</figcaption>
+  <figcaption>Figure 5: Aerie UI Timeline Layer Options Display Mode</figcaption>
 </figure>
 
-#### 2. Activity Label Visibility
+#### 3. Label Visibility
+
+There are several options to control how activity and event labels appear in the timeline:
 
-There are several options to control how activity labels appear in the timeline:
+- `On`: Always show labels regardless of collision.
+- `Off`: Never show labels.
+- `Auto`: Show labels when they do not collide with other labels or rectangles.
 
-- `On`: Always show activity labels regardless of collision.
-- `Off`: Never show activity labels.
-- `Auto`: Show activity labels when they do not collide with other labels or activities.
+A Layer Options section will appear in the row editor when the row has at least one activity or event layer. Layer Options affect how activities and events are rendered for this row.
 
-#### 3. Directive and Span Visibility
+### Activity Specific Options
+
+#### 4. Directive and Span Visibility
 
 By default, both directives and spans are shown in a row. Alternatively you may choose to show only directive or only spans.
 
-#### 4. Hierarchy Root
+#### 5. Hierarchy Root
 
 _This option is only available in `Grouped` mode._
 
@@ -105,9 +160,13 @@ Affects which activities appear in the initial type groups. By default, `Flat` i
 - `Flat`: Both activity directives and spans will appear in the top most type groups. This is useful when examining all activities resulting from a simulation without needing to consider activity decomposition.
 - `By Directive`: Only activity directives will appear in the top most type groups, effectively hiding any child spans until further down in the trees. This is useful when examining the timeline from a decomposition perspective.
 
-#### 5. Activity Height
+### Event Specific Options
+
+#### 6. Directive and Span Visibility
 
-Sets the height of activities in the row.
+_This option is only available in `Grouped` mode._
+
+Group events either by event source or by event type.
 
 ### Understanding the Grouped Activity Tree
 
@@ -117,7 +176,7 @@ Sets the height of activities in the row.
     src={timelineActivityTree}
     style={{ maxHeight: '100%', width: '100%' }}
   />
-  <figcaption>Figure 5: Aerie UI Timeline Activity Tree</figcaption>
+  <figcaption>Figure 6: Aerie UI Timeline Activity Tree</figcaption>
 </figure>
 
 In `Grouped` mode the activity tree presented in the row header has several important indicators and actions:
@@ -132,7 +191,7 @@ In `Grouped` mode the activity tree presented in the row header has several impo
 
 ### Add a Resource Line Layer
 
-To show resources on the timeline in a line plot, add a new layer using the plus button in the Layers section and change the layer type to Line. If the row did not already contain a Y axis, a new one will automatically be created and assigned to the line layer. To select resources to plot on this layer, click on the input on the layer and select a resource. It is not recommended to select more than one resource.
+To show resources on the timeline in a line plot, add a new resource layer using the plus button in the Resource Layers section. If the row did not already contain a Y axis, a new one will automatically be created and assigned to the line layer. To select a resource to plot on this layer, click on the input on the layer and select a resource.
 
 :::info Note
 Y axes are independent of layers. When you create a new line or x-range layer the layer will automatically be assigned to a Y axis. To modify which Y axis a layer is associated with, click on the settings icon for the layer and select a Y axis from the Y Axis dropdown.
@@ -146,7 +205,11 @@ Below is a demonstration of this workflow.
 
 ### Add a Resource X-Range Layer
 
-To show resources on the timeline in as an x-range plot, add a new layer using the plus button in the Layers section and change the layer type to X-Range. If the row did not already contain a Y axis, a new one will automatically be created and assigned to the x-range layer. A Y Axis is only used to provide a label to the x-range plot. To select resources to plot on this layer, click on the input on the layer and select one or more resources.
+To show resources on the timeline in a line plot, add a new resource layer using the plus button in the Resource Layers section and click on the x-range icon next to the line icon. If the row did not already contain a Y axis, a new one will automatically be created and assigned to the x-range layer. A Y Axis is only used to provide a label to the x-range plot. To select a resource to plot on this layer, click on the input on the layer and select one or more resources.
+
+:::info Showing X-Range as Line Plot
+X-Range plots can be shown as line plots through the corresponding option in the layer settings menu. Use this option when you would like to visualize a discrete resource (Banananation's `producer` resource for example) as a line plot.
+:::
 
 ### Manage Y Axis Settings
 
@@ -158,7 +221,7 @@ Y Axes have additional options available in the settings menu popover. By defaul
 
 <figure>
   <img alt="Aerie UI - Y Axis Settings" src={timelineYAxisSettings} style={{ maxHeight: '100%', width: '100%' }} />
-  <figcaption>Figure 6: Aerie UI Timeline Y Axis Settings</figcaption>
+  <figcaption>Figure 7: Aerie UI Timeline Y Axis Settings</figcaption>
 </figure>
 
 ### Manage Line and X-Range Names

docs/planning/ui-views.md

@@ -137,50 +137,61 @@ interface Timeline {
 }
 ```
 
-To visualize data in a timeline you need to add row objects to the `rows` array. A row is a layered visualization of time-ordered data. Each layer of a row is specified as an object of the `layers` array. The interfaces for a `Row`, `Layer`, and `ActivityOptions` are as follows:
+To visualize data in a timeline you need to add row objects to the `rows` array. A row is a layered visualization of time-ordered data. Each layer of a row is specified as an object of the `layers` array. The types for a `Row`, `Layer`, and `DiscreteOptions` are as follows:
 
 ```ts
-interface Row {
-  activityOptions?: ActivityOptions;
+type Row = {
   autoAdjustHeight: boolean;
+  discreteOptions: DiscreteOptions;
   expanded: boolean;
   height: number;
   horizontalGuides: HorizontalGuide[];
   id: number;
   layers: Layer[];
   name: string;
   yAxes: Axis[];
-}
+};
 
-interface Layer {
-  chartType: 'activity' | 'line' | 'x-range';
+type Layer {
+  chartType: 'activity' | 'line' | 'x-range' | 'external-event';
   filter: {
     activity?: ActivityLayerFilter;
+    externalEvent?: ExternalEventLayerFilter;
     resource?: ResourceLayerFilter;
   };
   id: number;
+  name: string;
   yAxisId: number | null;
 }
 
-type ActivityOptions = {
-  // Height of activity subrows
-  activityHeight: number;
+type DiscreteOptions = {
+  // Activity-Layer-specific Options
+  activityOptions?: {
+    // Whether or not to display only directives, only spans, or both in the row
+    composition: 'directives' | 'spans' | 'both';
 
-  // Whether or not to display only directives, only spans, or both in the row
-  composition: 'directives' | 'spans' | 'both';
+    // If 'directive' the activities are grouped starting with directive types, if 'flat' activities are grouped by type regardless of hierarchy
+    hierarchyMode: 'directive' | 'flat';
+  };
 
-  // Describes the primary method in which activities are visualized within this row
+  // Describes the primary method in which external events are visualized within this row
   displayMode: 'grouped' | 'compact';
 
-  // If 'directive' the activities are grouped starting with directive types, if 'flat' activities are grouped by type regardless of hierarchy
-  hierarchyMode: 'directive' | 'flat';
+  // External-Event-Layer-specific Options
+  externalEventOptions?: {
+    // Determines whether to group the External Events by their event type, or their external source
+    groupBy: 'event_type_name' | 'source_key';
+  };
+
+  // Height of subrows
+  height: number;
 
-  // Activity text label behavior
+  // Item text label behavior
   labelVisibility: 'on' | 'off' | 'auto';
 };
 ```
 
-Here is a JSON object that creates a single row with one activity layer.
+Here is a JSON object that creates a single row with one activity layer that renders all activity types. Activity layer filtering and customization is discussed in depth on the [Timeline Editing](./timeline-editing.mdx) page.
 
 ```json
 {
@@ -191,9 +202,7 @@ Here is a JSON object that creates a single row with one activity layer.
   "layers": [
     {
       "activityColor": "#283593",
-      "activityHeight": 20,
       "chartType": "activity",
-      "filter": { "activity": { "types": ["BiteBanana", "PickBanana"] } },
       "id": 0,
       "yAxisId": null
     }
@@ -225,13 +234,6 @@ Here is the JSON for creating a row with two overlaid `resource` layers. The fir
 
 ```json
 {
-  "activityOptions": {
-    "activityHeight": 16,
-    "composition": "both",
-    "displayMode": "grouped",
-    "hierarchyMode": "flat",
-    "labelVisibility": "auto"
-  },
   "autoAdjustHeight": false,
   "height": 100,
   "horizontalGuides": [],