adds first 2 examples

example/getting-started.md

@@ -1 +1,25 @@
 # Getting Started
+
+Without a doubt, the most commonly used aspect of this module is [textBox](https://github.com/d3plus/d3plus-text#textBox), which is used for intelligently wrapping SVG text. At it's core, you can simply pass along data points with "text" values and the generator will add them to the page using a set of defaults. Here is a data array containing 3 different sentences to be wrapped:
+
+```js
+var data = [
+  {text: "Here is some sample text that has been wrapped using d3plus.textBox."},
+  {text: "...and here is a second sentence!"},
+  {text: "这是句3号。这也即使包装没有空格！"}
+];
+```
+
+And finally, this is how that data array would be passed to the [textBox](https://github.com/d3plus/d3plus-text#textBox) generator. Please note the `()` at the end of the chain of commands. This is what tells the [textBox](https://github.com/d3plus/d3plus-text#textBox) to finally render to the page, and allows setting multiple properties of the [textBox](https://github.com/d3plus/d3plus-text#textBox) without it trying to render after each one is set.
+
+```js
+d3plus.textBox()
+  .data(data)
+  .fontFamily("Verdana")
+  .fontSize(16)
+  .width(200)
+  .x(function(d, i) { return i * 250; })
+  ();
+```
+
+While [textBox](https://github.com/d3plus/d3plus-text#textBox) comes with some handy defaults, this example shows how any of the methods can be overridden with static values or accessor functions. For more information on how the [textSplit](#textSplit) function splits strings, specifically in languages that don't use spaces, check out [this blog post](https://blog.datawheel.us/english-is-not-chinese-69b43959bb47).

example/resizing-text.md

@@ -0,0 +1,25 @@
+# Automatic Font Resizing to Fit Container
+
+A useful method when using text to label variable sized shapes (like in a [tree map](https://github.com/d3plus/d3plus-treemap)) is the [fontResize](https://github.com/d3plus/d3plus-text#textBox.fontResize) function. When set to `true`, the [textBox](https://github.com/d3plus/d3plus-text#textBox) will attempt to scale up or down the [fontSize](https://github.com/d3plus/d3plus-text#textBox.fontSize) value to best fit the containing shape.
+
+```js
+var data = [
+  {text: "This is a sentence that will not be resized.", resize: false},
+  {text: "This is a sentence that will be resized.", resize: true}
+];
+```
+
+Here, we can compare the output of using [fontResize](https://github.com/d3plus/d3plus-text#textBox.fontResize) against the normal output, given a 200 x 100 rectangle boundary.
+
+```js
+d3plus.textBox()
+  .data(data)
+  .fontFamily("Verdana")
+  .fontResize(function(d) { return d.resize; })
+  .height(100)
+  .width(200)
+  .x(function(d, i) { return i * 250; })
+  ();
+```
+
+The [fontSize](https://github.com/d3plus/d3plus-text#textBox.fontSize) calculated by this method is constrained by the [fontMin](https://github.com/d3plus/d3plus-text#textBox.fontMin) and [fontMax](https://github.com/d3plus/d3plus-text#textBox.fontMax) values, which default to `8` and `50` respectively.

src/textBox.js

@@ -25,25 +25,8 @@ function boxId(d, i) {
 
 /**
     @function textBox
-    @desc Creates a wrapped text box based on an array of data. If *data* is specified, immediately wraps the text based on the specified array and returns this generator. If *data* is not specified on instantiation, it can be passed/updated after instantiation using the [data](#textBox.data) method.
-    @param {Array} [data = []]
-    @example <caption>a sample row of data</caption>
-var data = {"text": "Hello D3plus, please wrap this sentence for me."};
-@example <caption>passed to the generator</caption>
-textBox([data]);
-@example <caption>creates the following</caption>
-<text class="d3plus-textBox" id="d3plus-textBox-0" text-anchor="start" font-family="Helvetica Neue" font-size="16px" transform="translate(0,-3.6)">
-  <tspan dominant-baseline="alphabetic" opacity="1" x="0px" dx="0px" dy="18px" style="baseline-shift: 0%;">
-    Hello D3plus, please wrap
-  </tspan>
-  <tspan dominant-baseline="alphabetic" opacity="1" x="0px" dx="0px" dy="18px" style="baseline-shift: 0%;">
-    this sentence for me.
-  </tspan>
-</text>
-@example <caption>this is shorthand for the following</caption>
-textBox().data([data])();
-@example <caption>which also allows a post-draw callback function</caption>
-textBox().data([data])(function() { alert("draw complete!"); })
+    @desc Creates a wrapped text box based on an array of data. If *data* is specified, immediately wraps the text based on the specified array and returns this generator. If *data* is not specified on instantiation, it can be passed/updated after instantiation using the [data](#textBox.data) method. See [this example](https://d3plus.org/examples/d3plus-text/getting-started/) for help getting started using the textBox function.
+    @param {Array} [data = []] An array of text blocks to be wrapped.
 */
 export default function(data = []) {
 
@@ -348,7 +331,7 @@ export default function(data = []) {
       @memberof textBox
       @desc If *value* is specified, sets the ellipsis method to the specified function or string and returns this generator. If *value* is not specified, returns the current ellipsis method, which simply adds an ellipsis to the string by default.
       @param {Function|String} [*value*]
-      @example
+      @example <caption>default accessor</caption>
 function(d) {
   return d + "...";
 }
@@ -415,7 +398,7 @@ function(d) {
       @memberof textBox
       @desc If *value* is specified, sets the height accessor to the specified function or number and returns this generator. If *value* is not specified, returns the current height accessor.
       @param {Function|Number} [*value*]
-      @example
+      @example <caption>default accessor</caption>
 function(d) {
   return d.height || 200;
 }
@@ -428,7 +411,7 @@ function(d) {
       @memberof textBox
       @desc If *value* is specified, sets the id accessor to the specified function or number and returns this generator. If *value* is not specified, returns the current id accessor.
       @param {Function|Number} [*value*]
-      @example
+      @example <caption>default accessor</caption>
 function(d, i) {
   return d.id || i + "";
 }
@@ -494,7 +477,7 @@ function(d, i) {
       @memberof textBox
       @desc If *value* is specified, sets the text accessor to the specified function or string and returns this generator. If *value* is not specified, returns the current text accessor.
       @param {Function|String} [*value*]
-      @example
+      @example <caption>default accessor</caption>
 function(d) {
   return d.text;
 }
@@ -525,7 +508,7 @@ function(d) {
       @memberof textBox
       @desc If *value* is specified, sets the width accessor to the specified function or number and returns this generator. If *value* is not specified, returns the current width accessor.
       @param {Function|Number} [*value*]
-      @example
+      @example <caption>default accessor</caption>
 function(d) {
   return d.width || 200;
 }
@@ -538,7 +521,7 @@ function(d) {
       @memberof textBox
       @desc If *value* is specified, sets the x accessor to the specified function or number and returns this generator. If *value* is not specified, returns the current x accessor. The number returned should correspond to the left position of the textBox.
       @param {Function|Number} [*value*]
-      @example
+      @example <caption>default accessor</caption>
 function(d) {
   return d.x || 0;
 }
@@ -551,7 +534,7 @@ function(d) {
       @memberof textBox
       @desc If *value* is specified, sets the y accessor to the specified function or number and returns this generator. If *value* is not specified, returns the current y accessor. The number returned should correspond to the top position of the textBox.
       @param {Function|Number} [*value*]
-      @example
+      @example <caption>default accessor</caption>
 function(d) {
   return d.y || 0;
 }