init

.gitignore

@@ -0,0 +1 @@
+.DS_Store

Capabilities/dataViewMappings.md

@@ -0,0 +1,113 @@
+#dataViewMappings
+
+A DataViewMapping describes how the data roles relate to each other and allows you to specify conditional requirements for the them.
+
+Each valid mapping will produce a DataView, but currently we only support performing one query per visual so in most situations you will only get one DataView. However, you can provide multiple data mappings with different conditions which allow
+
+```json
+[
+    {
+        "conditions": [ ... ],
+        "requiredProperties": [ ... ],
+        "single": { ... },
+        "categorical": { ... },
+        "table": { ... },
+        "matrix": { ... }
+    }
+]
+```
+
+###Conditions
+
+Describes conditions for a particular data mapping. You can provide multiple sets of conditions and if the data matches one of the described sets of conditions the visual will accept the data as valid.
+
+Currently, for each field you can specify a min and max value. This represents the number of fields that can be bound to that data role. Note: if a data role is ommitted in the condition it can have any number of fields.
+
+**Example 1**
+
+By default, you can drag multiple fields into each data role. In this example we limited category to 1 and y to 2.
+
+```json
+[
+    { "category": { "max": 1 }, "y": { "max": 2 } },
+]
+```
+
+**Example 2**
+
+In this example, there can be at most 2 y values, but not until there is at least 1 category assigned (min: 1).
+
+```json
+[
+    { "category": { "min": 1, "max": 1 }, "y": { "max": 2 } },
+]
+```
+
+###Required Properties
+
+```typescript
+//todo
+```
+
+###Single Data Mapping
+
+Single data mapping is the simplest form of data mapping. It accepts a single measure field and gives you the total. If the field is numeric it will give you the sum. Otherwise it will give you a count of unique values.
+
+To use single data mapping you simply define the name of the data role you want to map. This will only work with a single measure field. If a second field is assigned no data view will be generated so it is also good practice to include a condition that limits the data to a single field.
+
+Note: This data mapping cannot be used in conjunction with any other data mapping. It is meant to reduce data into a single numeric value.
+
+**Example**
+
+```json
+{
+    "conditions": [
+        { "Y": { "max": 1 } }
+    ],
+    "single": {
+        "role": "Y"
+    }
+}  
+```
+
+The resulting data view will still contain the other types (table, categorical, etc), but each mapping will only contain the single value. Best practice is to just access the value inside of single.
+
+![](../images/DataViewMappingResultSingle.png)
+
+###Categorical Data Mapping
+
+Categorical is the most commonly used data mapping.
+
+```json
+{
+    "categorical": {
+        "categories": {
+            "for": {
+                "in": "category"
+            }
+        },
+        "values": {
+            "select": [
+                {
+                    "bind": {
+                        "to": "measure"
+                    }
+                }
+            ]
+        }
+    }
+}
+
+```
+
+###Table Data Mapping
+
+```typescript
+//TODO
+```
+
+###Matrix Data Mapping
+
+```typescript
+//TODO
+```

Capabilities/readme.md

@@ -0,0 +1,79 @@
+#Using Capabilities
+
+Capabilities are used to provide information to the host about your visual.
+
+Your visual's capabilities are loaded from
+
+```json
+{
+    "dataRoles": [ ... ],
+
+    "dataViewMappings": [ ... ],
+
+    "objects":  { ... },
+
+    "supportsHighlight": true|false,
+
+    "sorting": { ... }
+}
+
+```
+
+
+##Define the data fields your visual expects - `dataRoles`
+
+To define fields that can be bound to data we use `dataRoles` which takes an array of `DataViewRole` objects which defines all of the properties needed.
+
+###Properties
+
+* **name** - the internal name of this data field (must be unique)
+* **kind** - the kind of field:
+    * 0 `Grouping` - Discrete values used for grouping of measure fields
+    * 1 `Measure` - Numeric data values 
+    * 2 `GroupingOrMeasure` - Can be used as either a grouping or measure
+* **displayName** - the name displayed to the user in the properties pane
+* **description** - a short description of the field (optional)
+
+###Example
+
+```json
+[
+    {
+        "displayName": "Category Data",
+        "name": "category",
+        "kind": 0
+    },
+    {
+        "displayName": "Measure Data",
+        "name": "measure",
+        "kind": 1
+    }
+]
+```
+
+The above data roles would create the following fields
+
+![](../images/dataRoleDisplay.png)
+
+
+##Define how you want the data mapped - `dataViewMappings`
+
+A DataViewMapping describes how the data roles relate to each other and allows you to specify conditional requirements for the them.
+
+Most visuals provide a single mapping, but you can provide multiple dataViewMappings. Each valid mapping will produce a DataView. 
+
+```json
+[
+    {
+        "conditions": [ ... ],
+        "requiredProperties": [ ... ],
+        "categorical": { ... },
+        "table": { ... }
+    }
+]
+```
+
+[Learn more about dataViewMappings](dataViewMappings.md)
+
+
+##Define property pane options - `objects`

ChangeLog.md

@@ -0,0 +1,13 @@
+#Change Log
+
+The page contains a quick summary of every version of the API
+
+##v1.1.0
+
+* SelectionIdBuilder - allows for creation of unique identifiers used for data selection
+* SelectionManager - manages the selection state of the visual and communicates changes to the visual host
+* DataView transform - allows pre-processing of DataView into your visuals view model.
+
+##v1.0.0
+
+* Initial API release

Colors.md

@@ -0,0 +1,3 @@
+#Host Color Pallet
+
+Not yet implemented

Glossary.md

@@ -0,0 +1,6 @@
+#Glossary
+
+* **DataRole** - DataRole(s) are used to define data bindings for your visual. They are displayed as fields in the Power BI interface.
+* **DataView** - DataView is a JavaScript object model for canonical representations of data. The lifeblood of Power BI visuals.
+* **IVisual** - The interface that all visuals must implement. Also, commonly used to refer to a PowerBI Visual.
+* **Visual Host** - The platform that contains the `IVisual`

README.md

@@ -1,2 +1,20 @@
-# PowerBI-visuals-docs
-Documentation for creating visuals for Power BI
+#Microsoft Power BI Visuals API
+
+This guide is meant to provide the quickest path to creating your first custom visual.
+
+##Setup
+
+The easiest way to create custom visuals is by using the PowerBI Custom Visuals CLI tools which can be easily to installed via NPM.
+
+[Setup instructions](tools/README.md)
+
+##Creating Visuals
+
+* [Anatomy of a Visual Project](VisualProject.md)
+* [Defining Visual Capabilities](Capabilities/readme.md)
+    * [Data Mapping](Capabilities/dataViewMappings.md)
+* [Handling Selection](Selection.md)
+* todo...
+* [Glossary](Glossary.md)
+* [Change Log](ChangeLog.md)
+* [Roadmap](Roadmap/Readme.md)

Roadmap/README.md

@@ -0,0 +1,5 @@
+#Roadmap
+
+## 1.2
+
+* [LoadMore](loadmore.md) (Load additional rows of data)

Roadmap/loadmore.md

@@ -0,0 +1 @@
+#LoadMore

Selection.md

@@ -0,0 +1,92 @@
+#Handling Selection
+
+Most visuals allow users to select data points or categories by clicking them with the mouse. 
+
+For example, in stacked column chart you can select a particular bar.
+
+![Stacked Column Chart Selection](images/stackedColumnSelected.png)
+
+##Creating Selection IDs `SelectionIdBuilder`
+
+In order for the visual host to track selected items for your visual and apply cross-filtering to other visuals, you have to generate and store a `SelectionId` for every selectable item. You can use the `SelectionIdBuilder` to generate selection ids.
+
+**Initialize a SelectionIdBuilder**
+
+First, you need to create a `SelectionIdBuilder` in your constructor and store it in a private variable in your visual class for later use.
+
+```typescript
+class MyVisual implements IVisual {
+
+    private selectionIdBuilder: ISelectionIdBuilder;
+
+    constructor(options: VisualConstructorOptions) {
+        this.selectionIdBuilder = options.host.createSelectionIdBuilder();
+    }
+}
+```
+
+**Generating Selection Ids**
+
+```typescript
+var categoricalData = dataView[0].categorical;
+var category = categoricalData.categories[0];
+var categories = categoricalData.values;
+var item = categorical.values[i];
+
+var selector: ISelectionId = this.selectionIdBuilder
+    .withSeries(cats, item)
+    .withMeasure(item.source.queryName)
+    .withCategory(categorical.categories[0], j)
+    .createSelectionId();
+```
+
+##Managing Selection `SelectionManager`
+
+You can use `SelectionManager` to notify the visual host of changes in the selection state. 
+
+**Initialize a SelectionManager**
+
+First, you need to create a `SelectionManager` in your constructor and store it in a private variable in your visual class for later use.
+
+```typescript
+class MyVisual implements IVisual {
+
+    private selectionManager: ISelectionManager;
+
+    constructor(options: VisualConstructorOptions) {
+        this.selectionManager = options.host.createSelectionManager();
+    }
+}
+```
+
+**Setting selection**
+
+To select an item simply call `select` on the selectionManager passing in the `SelectionId` of the item you want to select. If there are any other items selected the selection manager will automatically deselect them.
+
+The select function returns a promise that will resolve with an array of currently selected ids.
+
+```typescript
+this.selectionManager.select(selector).then((ids: ISelectionId[]) => {
+    //called when setting the selection has been completed successfully
+});
+```
+
+**Multiple selection**
+
+To support multi-selection you can provide the optional second parameter with a `true` value. When this is set it will not clear previous selection and just add the new selection to the list of selected ids. 
+
+```typescript
+this.selectionManager.select(selector, true).then((ids: ISelectionId[]) => {
+    //called when setting the selection has been completed successfully
+});
+```
+
+**Clearing selection**
+
+To clear selection simply call `clear` on the selection manager. This also retruns a promise that will resolve once the selection is cleared successfully.
+
+```typescript
+this.selectionManager.clear().then(() => {
+    //called when clearing the selection has been completed successfully
+});
+```