more scenery basics

docs/js/scenery-basics/path-basic-example.js

@@ -0,0 +1,38 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "path-basic-example", ( scene, stepEmitter, display ) => {
+  const box = ( () => {
+    /*START*/
+    const content = new HBox( {
+      spacing: 10,
+      children: [
+        // Rectangles are specified with x, y, width, height
+        new Rectangle( 0, 0, 50, 50, {
+          // fill is the "internal" color
+          fill: 'red',
+
+          // stroke color is applied on top, on the border of the shape
+          stroke: 'black',
+
+          // the width of the stroke can be controlled
+          lineWidth: 3
+        } ),
+        // Circles have a radius specified
+        new Circle( 25, { fill: 'green' } ),
+        // Lines are specified with x1, y1, x2, y2 (connecting two points)
+        new Line( 0, 0, 50, 50, {
+          stroke: 'blue',
+          lineWidth: 5,
+
+          // lineCap can be used to control the appearance of the
+          // ends of the line similarly, lineJoin can be used to
+          // control the appearance of any corners
+          lineCap: 'round'
+        } )
+      ]
+    } );
+    /*END*/
+    return content;
+  } )();
+  scene.addChild( box );
+} );

docs/js/scenery-basics/path-shape-example.js

@@ -0,0 +1,23 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "path-shape-example", ( scene, stepEmitter, display ) => {
+  const box = ( () => {
+    /*START*/
+    // Method calls on the Shape can be chained for convenience
+    const shape = new Shape()
+      .moveTo( 0, 0 ) // start at 0,0
+      .lineTo( 40, 40 ) // line from 0.0 to 40,40
+      .quadraticCurveTo( 80, 0, 40, -40 ) // cubic to 40,-40
+      .lineTo( 40, 0 ) // line from 40,-40 to 40,0
+      .close(); // close with a line from 40,0 to 0,0
+
+    const content = new Path( shape, {
+      fill: 'red',
+      stroke: 'black',
+      lineWidth: 2
+    } );
+    /*END*/
+    return content;
+  } )();
+  scene.addChild( box );
+} );

docs/js/scenery-basics/path-svg-example.js

@@ -0,0 +1,16 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "path-svg-example", ( scene, stepEmitter, display ) => {
+  const box = ( () => {
+    /*START*/
+    const shape = new Shape( 'M 0 0 L 40 40 Q 80 0 40 -40 L 40 0 L 0 0 Z' );
+    const content = new Path( shape, {
+      fill: 'cyan',
+      stroke: 'black',
+      lineWidth: 2
+    } );
+    /*END*/
+    return content;
+  } )();
+  scene.addChild( box );
+} );

docs/js/scenery-basics/text-basic-example.js

@@ -0,0 +1,14 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "text-basic-example", ( scene, stepEmitter, display ) => {
+  const box = ( () => {
+    /*START*/
+    const content = new Text( 'Lauren Ipsum, daughter of Dolor Sit Amet', {
+      fill: 'purple',
+      font: 'bold 20px Arial' // any CSS font property is valid
+    } );
+    /*END*/
+    return content;
+  } )();
+  scene.addChild( box );
+} );

docs/js/scenery-basics/text-property-example.js

@@ -0,0 +1,22 @@
+import { createSandbox } from "/js/createSandbox.js";
+
+createSandbox( "text-property-example", ( scene, stepEmitter, display ) => {
+  const box = ( () => {
+    /*START*/
+    const property = new StringProperty( 'Initial Text' );
+    const content = new Text( property, {
+      fill: 'purple',
+
+      // font properties can be specified independently
+      fontFamily: 'serif',
+      fontSize: 26,
+      fontStyle: 'italic'
+    } );
+
+    // change the text property
+    property.value = 'Different, serif text';
+    /*END*/
+    return content;
+  } )();
+  scene.addChild( box );
+} );

docs/learn/scenery-basics.md

@@ -78,6 +78,9 @@ or by using `mutate()`:
 When using the declarative options syntax, the parameters are executed in an order such that anything that affects
 the size of the node will be applied before anything that depends on the position of the node (e.g. `center`).
 
+Note that these approaches (declarative, or imperative setters) should function for all properties of the basic
+Scenery node types (e.g. [Text] `font`, [Path] `fill`, etc.)
+
 ## Children
 
 Nodes can have children, which are other nodes that are positioned relative to their parent. The order of the children
@@ -99,31 +102,50 @@ and the ability to `removeChild()` or `insertChild()` exists for when you need t
 
 ## Paths
 
-Shapes are displayed with the [Path] subtype of [Node]. They are created from [Shape] objects, which represent
-the 2d shapes that can be rendered. The API is very similar to the 
+Shapes are displayed with the [Path] subtype of [Node]. There are a number of flexible [Path] subtypes for common shapes:
+[Rectangle], [Circle], and [Line]. All [Path] types (along with anything [Paintable], like [Text]) can take fills, strokes, and
+other parameters that control their appearance.
+
+<div id="path-basic-example" class="sandbox-example"></div>
+<script type="module" async src="/js/scenery-basics/path-basic-example.js"></script>
+
+It is also possible to create custom shapes with the [Shape] object. The API is very similar to the 
 [CanvasRenderingContext2D](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D) API, where
-the path commands are used to define the [Shape], and the `fill`, `stroke`, and `lineWidth` properties are used to
-style the [Path].
+the path commands are used to define the [Shape]:
 
-TODO: example
+<div id="path-shape-example" class="sandbox-example"></div>
+<script type="module" async src="/js/scenery-basics/path-shape-example.js"></script>
 
-**Note**: The `fill` and `stroke` properties are examples of [Paintable] properties, which are also shared by [Text] nodes.
+[Path] objects can also be created with a SVG path string (see [documentation for the SVG path syntax](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d)):
 
-[Path] objects can also be created with a SVG path string (see [documentation for the SVG path syntax](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d):
+<div id="path-svg-example" class="sandbox-example"></div>
+<script type="module" async src="/js/scenery-basics/path-svg-example.js"></script>
 
-TODO: example
+To learn more about [Shape] objects, see the [Shape Guide](./shapes.md).
 
 ## Text
 
-Text is displayed with the [Text] subtype of [Node]. The text can be styled with the `font`, `fill`, and `stroke`.
+### Basic Text
+
+Basic text is displayed with the [Text] subtype of [Node]. The text can be styled with the `font`, `fill`, and `stroke`.
+
+<div id="text-basic-example" class="sandbox-example"></div>
+<script type="module" async src="/js/scenery-basics/text-basic-example.js"></script>
 
 [Text] nodes take in either a `string` or a `TReadOnlyProperty<string>` object (a [Property], [ReadOnlyProperty], or [TinyProperty] with a string value).
-They will dynamically update their displayed text when the Property changes.
+They will dynamically update their displayed text when the Property changes, to support dynamic and translated content:
 
-TODO: example
+<div id="text-property-example" class="sandbox-example"></div>
+<script type="module" async src="/js/scenery-basics/text-property-example.js"></script>
 
 **Note**: Text is positioned so that the origin of the node is at the left baseline of the text.
 
+### Rich Text
+
+TODO: docs and examples
+
+-- include separators
+
 ## Images
 
 Images can be displayed (with the upper-left corner at the origin of the node) with the [Image] subtype of [Node].
@@ -406,4 +428,4 @@ Visibility
 Opacity
 Clip area
 Filters
-Renderer
+Renderer