From e1c2b1ddb54d00697985620f7b16d1f7cd2c993c Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Mon, 21 Nov 2022 16:28:47 -0800
Subject: [PATCH 1/9] refine - what is not done yet

---
 docs/syntax/stateDiagram.md                   | 240 ++++++++++++++++--
 .../mermaid/src/docs/syntax/stateDiagram.md   | 190 ++++++++++++--
 2 files changed, 388 insertions(+), 42 deletions(-)

diff --git a/docs/syntax/stateDiagram.md b/docs/syntax/stateDiagram.md
index 1cec5afca1..afb1349efe 100644
--- a/docs/syntax/stateDiagram.md
+++ b/docs/syntax/stateDiagram.md
@@ -6,9 +6,12 @@
 
 # State diagrams
 
-> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems. State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the case, while at other times this is a reasonable abstraction." Wikipedia
+> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems.
+> State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the
+> case, while at other times this is a reasonable abstraction." Wikipedia
 
-Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make it easier for users to share diagrams between mermaid and plantUml.
+Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make
+it easier for users to share diagrams between mermaid and plantUml.
 
 ```mermaid-example
 ---
@@ -62,20 +65,23 @@ stateDiagram
     Crash --> [*]
 ```
 
-In state diagrams systems are described in terms of its states and how the systems state can change to another state via a transitions. The example diagram above shows three states **Still**, **Moving** and **Crash**. You start in the state of Still. From Still you can change the state to Moving. In Moving you can change the state either back to Still or to Crash. There is no transition from Still to Crash.
+In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
+a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the
+**Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
+the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
 
 ## States
 
-A state can be declared in multiple ways. The simplest way is to define a state id as a description.
+A state can be declared in multiple ways. The simplest way is to define a state with just an id:
 
 ```mermaid-example
 stateDiagram-v2
-    s1
+    stateId
 ```
 
 ```mermaid
 stateDiagram-v2
-    s1
+    stateId
 ```
 
 Another way is by using the state keyword with a description as per below:
@@ -106,7 +112,8 @@ stateDiagram-v2
 
 Transitions are path/edges when one state passes into another. This is represented using text arrow, "-->".
 
-When you define a transition between two states and the states are not already defined the undefined states are defined with the id from the transition. You can later add descriptions to states defined this way.
+When you define a transition between two states and the states are not already defined, the undefined states are defined
+with the id from the transition. You can later add descriptions to states defined this way.
 
 ```mermaid-example
 stateDiagram-v2
@@ -118,7 +125,7 @@ stateDiagram-v2
     s1 --> s2
 ```
 
-It is possible to add text to a transition. To describe what it represents.
+It is possible to add text to a transition to describe what it represents:
 
 ```mermaid-example
 stateDiagram-v2
@@ -132,7 +139,8 @@ stateDiagram-v2
 
 ## Start and End
 
-There are two special states indicating the start and stop of the diagram. These are written with the \[\*] syntax and the direction of the transition to it defines it either as a start or a stop state.
+There are two special states indicating the start and stop of the diagram. These are written with the \[\*] syntax and
+the direction of the transition to it defines it either as a start or a stop state.
 
 ```mermaid-example
 stateDiagram-v2
@@ -148,10 +156,11 @@ stateDiagram-v2
 
 ## Composite states
 
-In a real world use of state diagrams you often end up with diagrams that are multi-dimensional as one state can
+In a real world use of state diagrams you often end up with diagrams that are multidimensional as one state can
 have several internal states. These are called composite states in this terminology.
 
-In order to define a composite state you need to use the state keyword followed by an id and the body of the composite state between {}. See the example below:
+In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
+state between {}. See the example below:
 
 ```mermaid-example
 stateDiagram-v2
@@ -311,7 +320,7 @@ It is possible to specify a fork in the diagram using <\<fork>> <\<join>>.
 
 ## Notes
 
-Sometimes nothing says it better then a Post-it note. That is also the case in state diagrams.
+Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
 
 Here you can choose to put the note to the _right of_ or to the _left of_ a node.
 
@@ -381,7 +390,8 @@ stateDiagram-v2
 
 ## Setting the direction of the diagram
 
-With state diagrams you can use the direction statement to set the direction which the diagram will render like in this example.
+With state diagrams you can use the direction statement to set the direction which the diagram will render like in this
+example.
 
 ```mermaid-example
 stateDiagram
@@ -411,7 +421,9 @@ stateDiagram
 
 ## Comments
 
-Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax
+Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their
+own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next
+newline will be treated as a comment, including any diagram syntax
 
 ```mermaid-example
 stateDiagram-v2
@@ -435,22 +447,204 @@ stateDiagram-v2
     Crash --> [*]
 ```
 
-## Styling
+## Styling with classDefs
 
-Styling of the a state diagram is done by defining a number of css classes. During rendering these classes are extracted from the file located at src/themes/state.scss
+As with other diagrams (like flowcharts), you can define a style in the diagram itself and apply that named style to a
+state or states in the diagram.
+
+**These are the current limitations with state diagram classDefs:**
+
+1.  They cannot be applied to start or end states
+2.  The cannot be applied to or within composite states
+
+_These are in development and will be available in a future version._
+
+You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
+like a _CSS class_)
+followed by _a name for the style,_
+and then one or more _property-value pairs_. Each _property-value pair_ is
+a _[valid CSS property name](https://www.w3.org/TR/CSS/#properties)_ followed by a colon (`:`) and then a _value._
+
+Here is an example of a classDef with just one property-value pair:
+
+        classDef movement font-style:italic;
+
+where
+
+- the _name_ of the style is `movement`
+- the only _property_ is `font-style` and its _value_ is `italic`
+
+If you want to have more than one _property-value pair_ then you put a comma (`,`) between each _property-value pair._
+
+Here is an example with three property-value pairs:
+
+        classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+where
+
+- the _name_ of the style is `badBadEvent`
+- the first _property_ is `fill` and its _value_ is `#f00`
+- the second _property_ is `color` and its _value_ is `white`
+- the third _property_ is `font-weight` and its _value_ is `bold`
+- the fourth _property_ is `stroke-width` and its _value_ is `2px`
+- the fifth _property_ is `stroke` and its _value_ is `yello`
+
+### Apply classDef styles to states
+
+There are two ways to apply a `classDef` style to a state:
+
+1.  use the `class` keyword to apply a classDef style to one or more states in a single statement, or
+2.  use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
+    to/from another state)
+
+#### 1. `class` statement
+
+A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
+
+```text
+    class [one or more state names, separated by commas] [name of a style defined with classDef]
+```
+
+Here is an example applying the `badBadEvent` style to a state named `Crash`:
+
+```text
+class Crash badBadEvent
+```
+
+Here is an example applying the `movement` style to the two states `Moving` and `Crash`:
+
+```text
+class Moving, Crash movement
+```
+
+Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
+and `badBadEvent`
+
+```mermaid-example
+   stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*]--> Still
+   Still --> [*]
+   Still --> Moving
+   Moving --> Still
+   Moving --> Crash
+   Crash --> [*]
+
+   class Still notMoving
+   class Moving, Crash movement
+   class Crash badBadEvent
+   class end badBadEvent
+```
+
+```mermaid
+   stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*]--> Still
+   Still --> [*]
+   Still --> Moving
+   Moving --> Still
+   Moving --> Crash
+   Crash --> [*]
+
+   class Still notMoving
+   class Moving, Crash movement
+   class Crash badBadEvent
+   class end badBadEvent
+```
+
+#### 2. `:::` operator to apply a style to a state
+
+You can apply a classDef style to a state using the `:::` (three colons) operator. The syntax is
+
+```text
+[state]:::[style name]
+```
+
+You can use this in a diagram within a statement using a class. This includes the start and end states. For example:
+
+```mermaid-example
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic;
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*] --> Still:::notMoving
+   Still --> [*]
+   Still --> Moving:::movement
+   Moving --> Still
+   Moving --> Crash:::movement
+   Crash:::badBadEvent --> [*]
+```
+
+```mermaid
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic;
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*] --> Still:::notMoving
+   Still --> [*]
+   Still --> Moving:::movement
+   Moving --> Still
+   Moving --> Crash:::movement
+   Crash:::badBadEvent --> [*]
+```
 
 ## Spaces in state names
 
-Spaces can be added to a state by defining it at the top and referencing the acronym later.
+Spaces can be added to a state by first defining the state with an id and then referencing the id later.
+
+In the following example there is a state with the id **yswsii** and description **Your state with spaces in it**.
+After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
+and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).\
+(**yswsii** has been styled so that it is different from the other states.)
 
 ```mermaid-example
-stateDiagram-v2
-    Yswsii: Your state with spaces in it
-    [*] --> Yswsii
+stateDiagram
+    classDef yourState font-style:italic,font-weight:bold,fill:white
+
+    yswsii: Your state with spaces in it
+    [*] --> yswsii:::yourState
+    [*] --> SomeOtherState
+    SomeOtherState --> YetAnotherState
+    yswsii --> YetAnotherState
+    YetAnotherState --> [*]
 ```
 
 ```mermaid
-stateDiagram-v2
-    Yswsii: Your state with spaces in it
-    [*] --> Yswsii
+stateDiagram
+    classDef yourState font-style:italic,font-weight:bold,fill:white
+
+    yswsii: Your state with spaces in it
+    [*] --> yswsii:::yourState
+    [*] --> SomeOtherState
+    SomeOtherState --> YetAnotherState
+    yswsii --> YetAnotherState
+    YetAnotherState --> [*]
 ```
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index 9293e10839..3687518b28 100644
--- a/packages/mermaid/src/docs/syntax/stateDiagram.md
+++ b/packages/mermaid/src/docs/syntax/stateDiagram.md
@@ -1,8 +1,11 @@
 # State diagrams
 
-> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems. State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the case, while at other times this is a reasonable abstraction." Wikipedia
+> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems.
+> State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the
+> case, while at other times this is a reasonable abstraction." Wikipedia
 
-Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make it easier for users to share diagrams between mermaid and plantUml.
+Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make
+it easier for users to share diagrams between mermaid and plantUml.
 
 ```mermaid-example
 ---
@@ -31,15 +34,18 @@ stateDiagram
     Crash --> [*]
 ```
 
-In state diagrams systems are described in terms of its states and how the systems state can change to another state via a transitions. The example diagram above shows three states **Still**, **Moving** and **Crash**. You start in the state of Still. From Still you can change the state to Moving. In Moving you can change the state either back to Still or to Crash. There is no transition from Still to Crash.
+In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
+a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the 
+ **Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
+the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
 
 ## States
 
-A state can be declared in multiple ways. The simplest way is to define a state id as a description.
+A state can be declared in multiple ways. The simplest way is to define a state with just an id:
 
 ```mermaid-example
 stateDiagram-v2
-    s1
+    stateId
 ```
 
 Another way is by using the state keyword with a description as per below:
@@ -60,14 +66,15 @@ stateDiagram-v2
 
 Transitions are path/edges when one state passes into another. This is represented using text arrow, "\-\-\>".
 
-When you define a transition between two states and the states are not already defined the undefined states are defined with the id from the transition. You can later add descriptions to states defined this way.
+When you define a transition between two states and the states are not already defined, the undefined states are defined
+with the id from the transition. You can later add descriptions to states defined this way.
 
 ```mermaid-example
 stateDiagram-v2
     s1 --> s2
 ```
 
-It is possible to add text to a transition. To describe what it represents.
+It is possible to add text to a transition to describe what it represents:
 
 ```mermaid-example
 stateDiagram-v2
@@ -76,7 +83,8 @@ stateDiagram-v2
 
 ## Start and End
 
-There are two special states indicating the start and stop of the diagram. These are written with the [\*] syntax and the direction of the transition to it defines it either as a start or a stop state.
+There are two special states indicating the start and stop of the diagram. These are written with the [\*] syntax and
+the direction of the transition to it defines it either as a start or a stop state.
 
 ```mermaid-example
 stateDiagram-v2
@@ -86,10 +94,11 @@ stateDiagram-v2
 
 ## Composite states
 
-In a real world use of state diagrams you often end up with diagrams that are multi-dimensional as one state can
+In a real world use of state diagrams you often end up with diagrams that are multidimensional as one state can
 have several internal states. These are called composite states in this terminology.
 
-In order to define a composite state you need to use the state keyword followed by an id and the body of the composite state between \{\}. See the example below:
+In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
+state between \{\}. See the example below:
 
 ```mermaid-example
 stateDiagram-v2
@@ -178,7 +187,7 @@ It is possible to specify a fork in the diagram using &lt;&lt;fork&gt;&gt; &lt;&
 
 ## Notes
 
-Sometimes nothing says it better then a Post-it note. That is also the case in state diagrams.
+Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
 
 Here you can choose to put the note to the _right of_ or to the _left of_ a node.
 
@@ -218,7 +227,8 @@ stateDiagram-v2
 
 ## Setting the direction of the diagram
 
-With state diagrams you can use the direction statement to set the direction which the diagram will render like in this example.
+With state diagrams you can use the direction statement to set the direction which the diagram will render like in this
+example.
 
 ```mermaid-example
 stateDiagram
@@ -235,7 +245,9 @@ stateDiagram
 
 ## Comments
 
-Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax
+Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their
+own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next
+newline will be treated as a comment, including any diagram syntax
 
 ```mmd
 stateDiagram-v2
@@ -248,16 +260,156 @@ stateDiagram-v2
     Crash --> [*]
 ```
 
-## Styling
+## Styling with classDefs
+
+As with other diagrams (like flowcharts), you can define a style in the diagram itself and apply that named style to a
+state or states in the diagram.
+
+**These are the current limitations with state diagram classDefs:**
+1. They cannot be applied to start or end states
+2. The cannot be applied to or within composite states
+
+_These are in development and will be available in a future version._
+
+
+You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
+like a _CSS class_)
+followed by _a name for the style,_
+and then one or more _property-value pairs_. Each _property-value pair_ is
+a _[valid CSS property name](https://www.w3.org/TR/CSS/#properties)_ followed by a colon (`:`) and then a _value._
+
+Here is an example of a classDef with just one property-value pair:
+
+```
+    classDef movement font-style:italic;
+```
+
+where
+
+- the _name_ of the style is `movement`
+- the only _property_ is `font-style` and its _value_ is `italic`
+
+If you want to have more than one _property-value pair_ then you put a comma (`,`) between each _property-value pair._
+
+Here is an example with three property-value pairs:
+
+```
+    classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+```
+
+where
+
+- the _name_ of the style is `badBadEvent`
+- the first _property_ is `fill` and its _value_ is `#f00`
+- the second _property_ is `color` and its _value_ is `white`
+- the third _property_ is `font-weight` and its _value_ is `bold`
+- the fourth _property_ is `stroke-width` and its _value_ is `2px`
+- the fifth _property_ is `stroke` and its _value_ is `yello`
+
+### Apply classDef styles to states
+
+There are two ways to apply a `classDef` style to a state:
+
+1. use the `class` keyword to apply a classDef style to one or more states in a single statement, or
+2. use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
+   to/from another state)
+
+
+#### 1. `class` statement
+
+A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
+
+```text
+    class [one or more state names, separated by commas] [name of a style defined with classDef]
+```
+
+Here is an example applying the `badBadEvent` style to a state named `Crash`:
+
+```text
+class Crash badBadEvent
+```
+
+Here is an example applying the `movement` style to the two states `Moving` and `Crash`:
+
+```text
+class Moving, Crash movement
+```
+
+
+Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
+and `badBadEvent`
+
+```mermaid-example
+   stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*]--> Still
+   Still --> [*]
+   Still --> Moving
+   Moving --> Still
+   Moving --> Crash
+   Crash --> [*]
+
+   class Still notMoving
+   class Moving, Crash movement
+   class Crash badBadEvent
+   class end badBadEvent
+```
+
+#### 2. `:::` operator to apply a style to a state
+
+You can apply a classDef style to a state using the `:::` (three colons) operator. The syntax is
+
+```text
+[state]:::[style name]
+```
+
+You can use this in a diagram within a statement using a class. This includes the start and end states. For example:
+
+```mermaid-example
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic;
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*] --> Still:::notMoving
+   Still --> [*]
+   Still --> Moving:::movement
+   Moving --> Still
+   Moving --> Crash:::movement
+   Crash:::badBadEvent --> [*]
+```
+
 
-Styling of the a state diagram is done by defining a number of css classes. During rendering these classes are extracted from the file located at src/themes/state.scss
 
 ## Spaces in state names
 
-Spaces can be added to a state by defining it at the top and referencing the acronym later.
+Spaces can be added to a state by first defining the state with an id and then referencing the id later.
 
+In the following example there is a state with the id **yswsii** and description **Your state with spaces in it**.
+After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
+and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).  
+(**yswsii** has been styled so that it is different from the other states.)
 ```mermaid-example
-stateDiagram-v2
-    Yswsii: Your state with spaces in it
-    [*] --> Yswsii
+stateDiagram
+    classDef yourState font-style:italic,font-weight:bold,fill:white
+    
+    yswsii: Your state with spaces in it
+    [*] --> yswsii:::yourState
+    [*] --> SomeOtherState
+    SomeOtherState --> YetAnotherState
+    yswsii --> YetAnotherState
+    YetAnotherState --> [*]
 ```

From 98e4b6f338cb725947bd496403c5d6bec0537b0f Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Mon, 21 Nov 2022 16:58:59 -0800
Subject: [PATCH 2/9] add 'horz' to cSpell (in pieDetector.ts commented out
 barChart work)

---
 cSpell.json                                      | 1 +
 packages/mermaid/src/diagrams/pie/pieDetector.ts | 1 -
 2 files changed, 1 insertion(+), 1 deletion(-)

diff --git a/cSpell.json b/cSpell.json
index 03891165f5..8e92ffa8af 100644
--- a/cSpell.json
+++ b/cSpell.json
@@ -36,6 +36,7 @@
     "graphlib",
     "grav",
     "greywolf",
+    "horz",
     "inkdrop",
     "jaoude",
     "jison",
diff --git a/packages/mermaid/src/diagrams/pie/pieDetector.ts b/packages/mermaid/src/diagrams/pie/pieDetector.ts
index 9010f8a96e..e267c710ab 100644
--- a/packages/mermaid/src/diagrams/pie/pieDetector.ts
+++ b/packages/mermaid/src/diagrams/pie/pieDetector.ts
@@ -2,6 +2,5 @@ import type { DiagramDetector } from '../../diagram-api/types';
 
 export const pieDetector: DiagramDetector = (txt) => {
   const logOutput = txt.match(/^\s*pie/) !== null || txt.match(/^\s*bar/) !== null;
-  console.log(logOutput);
   return logOutput;
 };

From e2e604a76a9ad0316967d5fac8b304cffe072791 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Mon, 21 Nov 2022 16:59:55 -0800
Subject: [PATCH 3/9] update demos/state.html to includ examples; formatting

---
 demos/state.html                              | 82 +++++++++++++++++--
 .../mermaid/src/docs/syntax/stateDiagram.md   | 13 ++-
 2 files changed, 78 insertions(+), 17 deletions(-)

diff --git a/demos/state.html b/demos/state.html
index c13da84d88..3d070f3795 100644
--- a/demos/state.html
+++ b/demos/state.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="en" xmlns="http://www.w3.org/1999/html">
   <head>
     <meta charset="utf-8" />
     <meta http-equiv="X-UA-Compatible" content="IE=edge" />
@@ -33,8 +33,9 @@ <h4>Here are the <code>classDef</code> statements:</h4>
     <p>
       <code>
         classDef notMoving fill:white<br />
-        classDef movement font-style:italic;<br />
-        classDef badBadEvent fill:#f00,color:white,font-weight:bold<br />
+        classDef movement font-style:italic<br />
+        classDef badBadEvent
+        fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow<br />
       </code>
     </p>
     <h4>And these are how they are applied:</h4>
@@ -49,15 +50,17 @@ <h4>And these are how they are applied:</h4>
 ---
 title: Very simple diagram
 ---
-		stateDiagram-v2
+		stateDiagram
+      direction TB
+
 		  accTitle: This is the accessible title
       accDescr: This is an accessible description
 
       classDef notMoving fill:white
-      classDef movement font-style:italic;
-      classDef badBadEvent fill:#f00,color:white,font-weight:bold
+      classDef movement font-style:italic
+      classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
 
-      [*] --> Still
+      [*]--> Still
       Still --> [*]
       Still --> Moving
       Moving --> Still
@@ -67,10 +70,57 @@ <h4>And these are how they are applied:</h4>
       class Still notMoving
       class Moving, Crash movement
       class Crash badBadEvent
+      class end badBadEvent
     </pre>
 
     <hr />
 
+    <h2>Here is a diagram that uses the ::: operator to apply styles to states</h2>
+    <h4>Here are the <code>classDef</code> statements:</h4>
+    <p>
+      <code>
+        classDef notMoving fill:white<br />
+        classDef movement font-style:italic<br />
+        classDef badBadEvent
+        fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow<br />
+      </code>
+    </p>
+    <h4>And these are how they are applied:</h4>
+    <p>
+      <code>
+        [*] --> Still:::notMoving<br />
+        ...<br />
+        Still --> Moving:::movement<br />
+        ...<br />
+        Moving --> Crash:::movement<br />
+        Crash:::badBadEvent --> [*]<br />
+      </code>
+    </p>
+    <p>
+      Note that both the starting state and the end state have styles applied:<br />
+      The start state has the <i>start</i> classDef style<br />and the end state has the
+      <i>stop</i> classDef style applied.
+    </p>
+    <pre class="mermaid">
+    stateDiagram
+      direction TB
+
+		  accTitle: This is the accessible title
+      accDescr: This is an accessible description
+
+      classDef notMoving fill:white
+      classDef movement font-style:italic
+      classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+      [*] --> Still:::notMoving
+      Still --> [*]
+      Still --> Moving:::movement
+      Moving --> Still
+      Moving --> Crash:::movement
+      Crash:::badBadEvent --> [*]
+    </pre>
+    <hr />
+
     <pre class="mermaid">
     stateDiagram-v2
       accTitle: very very simple state
@@ -79,6 +129,20 @@ <h4>And these are how they are applied:</h4>
     </pre>
     <hr />
 
+    <h2>States with spaces in them</h2>
+    <pre class="mermaid">
+      stateDiagram
+        classDef yourState font-style:italic,font-weight:bold,fill:white
+
+        yswsii: Your state with spaces in it
+        [*] --> yswsii:::yourState
+        [*] --> SomeOtherState
+        SomeOtherState --> YetAnotherState
+        yswsii --> YetAnotherState
+        YetAnotherState --> [*]
+    </pre>
+    <hr />
+
     <h2>You can label the relationships</h2>
     <pre class="mermaid">
     stateDiagram-v2
@@ -127,7 +191,7 @@ <h2>transition labels can span multiple lines using "br" tags or \n</h2>
     <pre class="mermaid">
       stateDiagram-v2
       [*] --> S1
-      S1 --> S2: This long line uses a br tag<br/>to create multiple<br/>lines.
+      S1 --> S2: This long line uses a br tag<br />to create multiple<br />lines.
       S1 --> S3: This transition descripton uses \na newline character\nto create multiple\nlines.
 
     </pre>
@@ -139,7 +203,7 @@ <h2>You can add Notes</h2>
       direction LR
       State1: A state with a note
       note right of State1
-        Important information!<br />You can write notes.<br/>And\nthey\ncan\nbe\nmulti-\nline.
+        Important information!<br />You can write notes.<br />And\nthey\ncan\nbe\nmulti-\nline.
       end note
       State1 --> State2
       note left of State2 : Notes can be to the left of a state\n(like this one).
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index 3687518b28..a9cb729480 100644
--- a/packages/mermaid/src/docs/syntax/stateDiagram.md
+++ b/packages/mermaid/src/docs/syntax/stateDiagram.md
@@ -35,8 +35,8 @@ stateDiagram
 ```
 
 In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
-a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the 
- **Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
+a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the
+**Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
 the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
 
 ## States
@@ -266,12 +266,12 @@ As with other diagrams (like flowcharts), you can define a style in the diagram
 state or states in the diagram.
 
 **These are the current limitations with state diagram classDefs:**
+
 1. They cannot be applied to start or end states
 2. The cannot be applied to or within composite states
 
 _These are in development and will be available in a future version._
 
-
 You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
 like a _CSS class_)
 followed by _a name for the style,_
@@ -314,7 +314,6 @@ There are two ways to apply a `classDef` style to a state:
 2. use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
    to/from another state)
 
-
 #### 1. `class` statement
 
 A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
@@ -335,7 +334,6 @@ Here is an example applying the `movement` style to the two states `Moving` and
 class Moving, Crash movement
 ```
 
-
 Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
 and `badBadEvent`
 
@@ -392,8 +390,6 @@ stateDiagram
    Crash:::badBadEvent --> [*]
 ```
 
-
-
 ## Spaces in state names
 
 Spaces can be added to a state by first defining the state with an id and then referencing the id later.
@@ -402,10 +398,11 @@ In the following example there is a state with the id **yswsii** and description
 After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
 and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).  
 (**yswsii** has been styled so that it is different from the other states.)
+
 ```mermaid-example
 stateDiagram
     classDef yourState font-style:italic,font-weight:bold,fill:white
-    
+
     yswsii: Your state with spaces in it
     [*] --> yswsii:::yourState
     [*] --> SomeOtherState

From 828e99d4b9268b1d7ece754fb05fa1217e35f67f Mon Sep 17 00:00:00 2001
From: Ashley Engelund <weedySeaDragon@users.noreply.github.com>
Date: Tue, 22 Nov 2022 08:49:08 -0800
Subject: [PATCH 4/9] remove 'horz' from  cSpell.json

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>
---
 cSpell.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/cSpell.json b/cSpell.json
index 8e92ffa8af..03891165f5 100644
--- a/cSpell.json
+++ b/cSpell.json
@@ -36,7 +36,6 @@
     "graphlib",
     "grav",
     "greywolf",
-    "horz",
     "inkdrop",
     "jaoude",
     "jison",

From 8066aaeeb04231ee85b937a56537db507878adff Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Mon, 21 Nov 2022 16:28:47 -0800
Subject: [PATCH 5/9] refine - what is not done yet

---
 docs/syntax/stateDiagram.md                   | 240 ++++++++++++++++--
 .../mermaid/src/docs/syntax/stateDiagram.md   | 190 ++++++++++++--
 2 files changed, 388 insertions(+), 42 deletions(-)

diff --git a/docs/syntax/stateDiagram.md b/docs/syntax/stateDiagram.md
index 1cec5afca1..afb1349efe 100644
--- a/docs/syntax/stateDiagram.md
+++ b/docs/syntax/stateDiagram.md
@@ -6,9 +6,12 @@
 
 # State diagrams
 
-> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems. State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the case, while at other times this is a reasonable abstraction." Wikipedia
+> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems.
+> State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the
+> case, while at other times this is a reasonable abstraction." Wikipedia
 
-Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make it easier for users to share diagrams between mermaid and plantUml.
+Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make
+it easier for users to share diagrams between mermaid and plantUml.
 
 ```mermaid-example
 ---
@@ -62,20 +65,23 @@ stateDiagram
     Crash --> [*]
 ```
 
-In state diagrams systems are described in terms of its states and how the systems state can change to another state via a transitions. The example diagram above shows three states **Still**, **Moving** and **Crash**. You start in the state of Still. From Still you can change the state to Moving. In Moving you can change the state either back to Still or to Crash. There is no transition from Still to Crash.
+In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
+a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the
+**Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
+the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
 
 ## States
 
-A state can be declared in multiple ways. The simplest way is to define a state id as a description.
+A state can be declared in multiple ways. The simplest way is to define a state with just an id:
 
 ```mermaid-example
 stateDiagram-v2
-    s1
+    stateId
 ```
 
 ```mermaid
 stateDiagram-v2
-    s1
+    stateId
 ```
 
 Another way is by using the state keyword with a description as per below:
@@ -106,7 +112,8 @@ stateDiagram-v2
 
 Transitions are path/edges when one state passes into another. This is represented using text arrow, "-->".
 
-When you define a transition between two states and the states are not already defined the undefined states are defined with the id from the transition. You can later add descriptions to states defined this way.
+When you define a transition between two states and the states are not already defined, the undefined states are defined
+with the id from the transition. You can later add descriptions to states defined this way.
 
 ```mermaid-example
 stateDiagram-v2
@@ -118,7 +125,7 @@ stateDiagram-v2
     s1 --> s2
 ```
 
-It is possible to add text to a transition. To describe what it represents.
+It is possible to add text to a transition to describe what it represents:
 
 ```mermaid-example
 stateDiagram-v2
@@ -132,7 +139,8 @@ stateDiagram-v2
 
 ## Start and End
 
-There are two special states indicating the start and stop of the diagram. These are written with the \[\*] syntax and the direction of the transition to it defines it either as a start or a stop state.
+There are two special states indicating the start and stop of the diagram. These are written with the \[\*] syntax and
+the direction of the transition to it defines it either as a start or a stop state.
 
 ```mermaid-example
 stateDiagram-v2
@@ -148,10 +156,11 @@ stateDiagram-v2
 
 ## Composite states
 
-In a real world use of state diagrams you often end up with diagrams that are multi-dimensional as one state can
+In a real world use of state diagrams you often end up with diagrams that are multidimensional as one state can
 have several internal states. These are called composite states in this terminology.
 
-In order to define a composite state you need to use the state keyword followed by an id and the body of the composite state between {}. See the example below:
+In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
+state between {}. See the example below:
 
 ```mermaid-example
 stateDiagram-v2
@@ -311,7 +320,7 @@ It is possible to specify a fork in the diagram using <\<fork>> <\<join>>.
 
 ## Notes
 
-Sometimes nothing says it better then a Post-it note. That is also the case in state diagrams.
+Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
 
 Here you can choose to put the note to the _right of_ or to the _left of_ a node.
 
@@ -381,7 +390,8 @@ stateDiagram-v2
 
 ## Setting the direction of the diagram
 
-With state diagrams you can use the direction statement to set the direction which the diagram will render like in this example.
+With state diagrams you can use the direction statement to set the direction which the diagram will render like in this
+example.
 
 ```mermaid-example
 stateDiagram
@@ -411,7 +421,9 @@ stateDiagram
 
 ## Comments
 
-Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax
+Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their
+own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next
+newline will be treated as a comment, including any diagram syntax
 
 ```mermaid-example
 stateDiagram-v2
@@ -435,22 +447,204 @@ stateDiagram-v2
     Crash --> [*]
 ```
 
-## Styling
+## Styling with classDefs
 
-Styling of the a state diagram is done by defining a number of css classes. During rendering these classes are extracted from the file located at src/themes/state.scss
+As with other diagrams (like flowcharts), you can define a style in the diagram itself and apply that named style to a
+state or states in the diagram.
+
+**These are the current limitations with state diagram classDefs:**
+
+1.  They cannot be applied to start or end states
+2.  The cannot be applied to or within composite states
+
+_These are in development and will be available in a future version._
+
+You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
+like a _CSS class_)
+followed by _a name for the style,_
+and then one or more _property-value pairs_. Each _property-value pair_ is
+a _[valid CSS property name](https://www.w3.org/TR/CSS/#properties)_ followed by a colon (`:`) and then a _value._
+
+Here is an example of a classDef with just one property-value pair:
+
+        classDef movement font-style:italic;
+
+where
+
+- the _name_ of the style is `movement`
+- the only _property_ is `font-style` and its _value_ is `italic`
+
+If you want to have more than one _property-value pair_ then you put a comma (`,`) between each _property-value pair._
+
+Here is an example with three property-value pairs:
+
+        classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+where
+
+- the _name_ of the style is `badBadEvent`
+- the first _property_ is `fill` and its _value_ is `#f00`
+- the second _property_ is `color` and its _value_ is `white`
+- the third _property_ is `font-weight` and its _value_ is `bold`
+- the fourth _property_ is `stroke-width` and its _value_ is `2px`
+- the fifth _property_ is `stroke` and its _value_ is `yello`
+
+### Apply classDef styles to states
+
+There are two ways to apply a `classDef` style to a state:
+
+1.  use the `class` keyword to apply a classDef style to one or more states in a single statement, or
+2.  use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
+    to/from another state)
+
+#### 1. `class` statement
+
+A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
+
+```text
+    class [one or more state names, separated by commas] [name of a style defined with classDef]
+```
+
+Here is an example applying the `badBadEvent` style to a state named `Crash`:
+
+```text
+class Crash badBadEvent
+```
+
+Here is an example applying the `movement` style to the two states `Moving` and `Crash`:
+
+```text
+class Moving, Crash movement
+```
+
+Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
+and `badBadEvent`
+
+```mermaid-example
+   stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*]--> Still
+   Still --> [*]
+   Still --> Moving
+   Moving --> Still
+   Moving --> Crash
+   Crash --> [*]
+
+   class Still notMoving
+   class Moving, Crash movement
+   class Crash badBadEvent
+   class end badBadEvent
+```
+
+```mermaid
+   stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*]--> Still
+   Still --> [*]
+   Still --> Moving
+   Moving --> Still
+   Moving --> Crash
+   Crash --> [*]
+
+   class Still notMoving
+   class Moving, Crash movement
+   class Crash badBadEvent
+   class end badBadEvent
+```
+
+#### 2. `:::` operator to apply a style to a state
+
+You can apply a classDef style to a state using the `:::` (three colons) operator. The syntax is
+
+```text
+[state]:::[style name]
+```
+
+You can use this in a diagram within a statement using a class. This includes the start and end states. For example:
+
+```mermaid-example
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic;
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*] --> Still:::notMoving
+   Still --> [*]
+   Still --> Moving:::movement
+   Moving --> Still
+   Moving --> Crash:::movement
+   Crash:::badBadEvent --> [*]
+```
+
+```mermaid
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic;
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*] --> Still:::notMoving
+   Still --> [*]
+   Still --> Moving:::movement
+   Moving --> Still
+   Moving --> Crash:::movement
+   Crash:::badBadEvent --> [*]
+```
 
 ## Spaces in state names
 
-Spaces can be added to a state by defining it at the top and referencing the acronym later.
+Spaces can be added to a state by first defining the state with an id and then referencing the id later.
+
+In the following example there is a state with the id **yswsii** and description **Your state with spaces in it**.
+After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
+and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).\
+(**yswsii** has been styled so that it is different from the other states.)
 
 ```mermaid-example
-stateDiagram-v2
-    Yswsii: Your state with spaces in it
-    [*] --> Yswsii
+stateDiagram
+    classDef yourState font-style:italic,font-weight:bold,fill:white
+
+    yswsii: Your state with spaces in it
+    [*] --> yswsii:::yourState
+    [*] --> SomeOtherState
+    SomeOtherState --> YetAnotherState
+    yswsii --> YetAnotherState
+    YetAnotherState --> [*]
 ```
 
 ```mermaid
-stateDiagram-v2
-    Yswsii: Your state with spaces in it
-    [*] --> Yswsii
+stateDiagram
+    classDef yourState font-style:italic,font-weight:bold,fill:white
+
+    yswsii: Your state with spaces in it
+    [*] --> yswsii:::yourState
+    [*] --> SomeOtherState
+    SomeOtherState --> YetAnotherState
+    yswsii --> YetAnotherState
+    YetAnotherState --> [*]
 ```
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index 9293e10839..3687518b28 100644
--- a/packages/mermaid/src/docs/syntax/stateDiagram.md
+++ b/packages/mermaid/src/docs/syntax/stateDiagram.md
@@ -1,8 +1,11 @@
 # State diagrams
 
-> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems. State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the case, while at other times this is a reasonable abstraction." Wikipedia
+> "A state diagram is a type of diagram used in computer science and related fields to describe the behavior of systems.
+> State diagrams require that the system described is composed of a finite number of states; sometimes, this is indeed the
+> case, while at other times this is a reasonable abstraction." Wikipedia
 
-Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make it easier for users to share diagrams between mermaid and plantUml.
+Mermaid can render state diagrams. The syntax tries to be compliant with the syntax used in plantUml as this will make
+it easier for users to share diagrams between mermaid and plantUml.
 
 ```mermaid-example
 ---
@@ -31,15 +34,18 @@ stateDiagram
     Crash --> [*]
 ```
 
-In state diagrams systems are described in terms of its states and how the systems state can change to another state via a transitions. The example diagram above shows three states **Still**, **Moving** and **Crash**. You start in the state of Still. From Still you can change the state to Moving. In Moving you can change the state either back to Still or to Crash. There is no transition from Still to Crash.
+In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
+a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the 
+ **Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
+the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
 
 ## States
 
-A state can be declared in multiple ways. The simplest way is to define a state id as a description.
+A state can be declared in multiple ways. The simplest way is to define a state with just an id:
 
 ```mermaid-example
 stateDiagram-v2
-    s1
+    stateId
 ```
 
 Another way is by using the state keyword with a description as per below:
@@ -60,14 +66,15 @@ stateDiagram-v2
 
 Transitions are path/edges when one state passes into another. This is represented using text arrow, "\-\-\>".
 
-When you define a transition between two states and the states are not already defined the undefined states are defined with the id from the transition. You can later add descriptions to states defined this way.
+When you define a transition between two states and the states are not already defined, the undefined states are defined
+with the id from the transition. You can later add descriptions to states defined this way.
 
 ```mermaid-example
 stateDiagram-v2
     s1 --> s2
 ```
 
-It is possible to add text to a transition. To describe what it represents.
+It is possible to add text to a transition to describe what it represents:
 
 ```mermaid-example
 stateDiagram-v2
@@ -76,7 +83,8 @@ stateDiagram-v2
 
 ## Start and End
 
-There are two special states indicating the start and stop of the diagram. These are written with the [\*] syntax and the direction of the transition to it defines it either as a start or a stop state.
+There are two special states indicating the start and stop of the diagram. These are written with the [\*] syntax and
+the direction of the transition to it defines it either as a start or a stop state.
 
 ```mermaid-example
 stateDiagram-v2
@@ -86,10 +94,11 @@ stateDiagram-v2
 
 ## Composite states
 
-In a real world use of state diagrams you often end up with diagrams that are multi-dimensional as one state can
+In a real world use of state diagrams you often end up with diagrams that are multidimensional as one state can
 have several internal states. These are called composite states in this terminology.
 
-In order to define a composite state you need to use the state keyword followed by an id and the body of the composite state between \{\}. See the example below:
+In order to define a composite state you need to use the state keyword followed by an id and the body of the composite
+state between \{\}. See the example below:
 
 ```mermaid-example
 stateDiagram-v2
@@ -178,7 +187,7 @@ It is possible to specify a fork in the diagram using &lt;&lt;fork&gt;&gt; &lt;&
 
 ## Notes
 
-Sometimes nothing says it better then a Post-it note. That is also the case in state diagrams.
+Sometimes nothing says it better than a Post-it note. That is also the case in state diagrams.
 
 Here you can choose to put the note to the _right of_ or to the _left of_ a node.
 
@@ -218,7 +227,8 @@ stateDiagram-v2
 
 ## Setting the direction of the diagram
 
-With state diagrams you can use the direction statement to set the direction which the diagram will render like in this example.
+With state diagrams you can use the direction statement to set the direction which the diagram will render like in this
+example.
 
 ```mermaid-example
 stateDiagram
@@ -235,7 +245,9 @@ stateDiagram
 
 ## Comments
 
-Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax
+Comments can be entered within a state diagram chart, which will be ignored by the parser. Comments need to be on their
+own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next
+newline will be treated as a comment, including any diagram syntax
 
 ```mmd
 stateDiagram-v2
@@ -248,16 +260,156 @@ stateDiagram-v2
     Crash --> [*]
 ```
 
-## Styling
+## Styling with classDefs
+
+As with other diagrams (like flowcharts), you can define a style in the diagram itself and apply that named style to a
+state or states in the diagram.
+
+**These are the current limitations with state diagram classDefs:**
+1. They cannot be applied to start or end states
+2. The cannot be applied to or within composite states
+
+_These are in development and will be available in a future version._
+
+
+You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
+like a _CSS class_)
+followed by _a name for the style,_
+and then one or more _property-value pairs_. Each _property-value pair_ is
+a _[valid CSS property name](https://www.w3.org/TR/CSS/#properties)_ followed by a colon (`:`) and then a _value._
+
+Here is an example of a classDef with just one property-value pair:
+
+```
+    classDef movement font-style:italic;
+```
+
+where
+
+- the _name_ of the style is `movement`
+- the only _property_ is `font-style` and its _value_ is `italic`
+
+If you want to have more than one _property-value pair_ then you put a comma (`,`) between each _property-value pair._
+
+Here is an example with three property-value pairs:
+
+```
+    classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+```
+
+where
+
+- the _name_ of the style is `badBadEvent`
+- the first _property_ is `fill` and its _value_ is `#f00`
+- the second _property_ is `color` and its _value_ is `white`
+- the third _property_ is `font-weight` and its _value_ is `bold`
+- the fourth _property_ is `stroke-width` and its _value_ is `2px`
+- the fifth _property_ is `stroke` and its _value_ is `yello`
+
+### Apply classDef styles to states
+
+There are two ways to apply a `classDef` style to a state:
+
+1. use the `class` keyword to apply a classDef style to one or more states in a single statement, or
+2. use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
+   to/from another state)
+
+
+#### 1. `class` statement
+
+A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
+
+```text
+    class [one or more state names, separated by commas] [name of a style defined with classDef]
+```
+
+Here is an example applying the `badBadEvent` style to a state named `Crash`:
+
+```text
+class Crash badBadEvent
+```
+
+Here is an example applying the `movement` style to the two states `Moving` and `Crash`:
+
+```text
+class Moving, Crash movement
+```
+
+
+Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
+and `badBadEvent`
+
+```mermaid-example
+   stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*]--> Still
+   Still --> [*]
+   Still --> Moving
+   Moving --> Still
+   Moving --> Crash
+   Crash --> [*]
+
+   class Still notMoving
+   class Moving, Crash movement
+   class Crash badBadEvent
+   class end badBadEvent
+```
+
+#### 2. `:::` operator to apply a style to a state
+
+You can apply a classDef style to a state using the `:::` (three colons) operator. The syntax is
+
+```text
+[state]:::[style name]
+```
+
+You can use this in a diagram within a statement using a class. This includes the start and end states. For example:
+
+```mermaid-example
+stateDiagram
+   direction TB
+
+   accTitle: This is the accessible title
+   accDescr: This is an accessible description
+
+   classDef notMoving fill:white
+   classDef movement font-style:italic;
+   classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+   [*] --> Still:::notMoving
+   Still --> [*]
+   Still --> Moving:::movement
+   Moving --> Still
+   Moving --> Crash:::movement
+   Crash:::badBadEvent --> [*]
+```
+
 
-Styling of the a state diagram is done by defining a number of css classes. During rendering these classes are extracted from the file located at src/themes/state.scss
 
 ## Spaces in state names
 
-Spaces can be added to a state by defining it at the top and referencing the acronym later.
+Spaces can be added to a state by first defining the state with an id and then referencing the id later.
 
+In the following example there is a state with the id **yswsii** and description **Your state with spaces in it**.
+After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
+and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).  
+(**yswsii** has been styled so that it is different from the other states.)
 ```mermaid-example
-stateDiagram-v2
-    Yswsii: Your state with spaces in it
-    [*] --> Yswsii
+stateDiagram
+    classDef yourState font-style:italic,font-weight:bold,fill:white
+    
+    yswsii: Your state with spaces in it
+    [*] --> yswsii:::yourState
+    [*] --> SomeOtherState
+    SomeOtherState --> YetAnotherState
+    yswsii --> YetAnotherState
+    YetAnotherState --> [*]
 ```

From 4703523d6ba5bab6d40816b1e03c7117b3a6e643 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Mon, 21 Nov 2022 16:58:59 -0800
Subject: [PATCH 6/9] add 'horz' to cSpell (in pieDetector.ts commented out
 barChart work)

---
 cSpell.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/cSpell.json b/cSpell.json
index 03891165f5..8e92ffa8af 100644
--- a/cSpell.json
+++ b/cSpell.json
@@ -36,6 +36,7 @@
     "graphlib",
     "grav",
     "greywolf",
+    "horz",
     "inkdrop",
     "jaoude",
     "jison",

From 7f5b48920c78234701cce25d5728ebc9a384f20a Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Mon, 21 Nov 2022 16:59:55 -0800
Subject: [PATCH 7/9] update demos/state.html to includ examples; formatting

---
 demos/state.html                              | 82 +++++++++++++++++--
 .../mermaid/src/docs/syntax/stateDiagram.md   | 13 ++-
 2 files changed, 78 insertions(+), 17 deletions(-)

diff --git a/demos/state.html b/demos/state.html
index c13da84d88..3d070f3795 100644
--- a/demos/state.html
+++ b/demos/state.html
@@ -1,5 +1,5 @@
 <!DOCTYPE html>
-<html lang="en">
+<html lang="en" xmlns="http://www.w3.org/1999/html">
   <head>
     <meta charset="utf-8" />
     <meta http-equiv="X-UA-Compatible" content="IE=edge" />
@@ -33,8 +33,9 @@ <h4>Here are the <code>classDef</code> statements:</h4>
     <p>
       <code>
         classDef notMoving fill:white<br />
-        classDef movement font-style:italic;<br />
-        classDef badBadEvent fill:#f00,color:white,font-weight:bold<br />
+        classDef movement font-style:italic<br />
+        classDef badBadEvent
+        fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow<br />
       </code>
     </p>
     <h4>And these are how they are applied:</h4>
@@ -49,15 +50,17 @@ <h4>And these are how they are applied:</h4>
 ---
 title: Very simple diagram
 ---
-		stateDiagram-v2
+		stateDiagram
+      direction TB
+
 		  accTitle: This is the accessible title
       accDescr: This is an accessible description
 
       classDef notMoving fill:white
-      classDef movement font-style:italic;
-      classDef badBadEvent fill:#f00,color:white,font-weight:bold
+      classDef movement font-style:italic
+      classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
 
-      [*] --> Still
+      [*]--> Still
       Still --> [*]
       Still --> Moving
       Moving --> Still
@@ -67,10 +70,57 @@ <h4>And these are how they are applied:</h4>
       class Still notMoving
       class Moving, Crash movement
       class Crash badBadEvent
+      class end badBadEvent
     </pre>
 
     <hr />
 
+    <h2>Here is a diagram that uses the ::: operator to apply styles to states</h2>
+    <h4>Here are the <code>classDef</code> statements:</h4>
+    <p>
+      <code>
+        classDef notMoving fill:white<br />
+        classDef movement font-style:italic<br />
+        classDef badBadEvent
+        fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow<br />
+      </code>
+    </p>
+    <h4>And these are how they are applied:</h4>
+    <p>
+      <code>
+        [*] --> Still:::notMoving<br />
+        ...<br />
+        Still --> Moving:::movement<br />
+        ...<br />
+        Moving --> Crash:::movement<br />
+        Crash:::badBadEvent --> [*]<br />
+      </code>
+    </p>
+    <p>
+      Note that both the starting state and the end state have styles applied:<br />
+      The start state has the <i>start</i> classDef style<br />and the end state has the
+      <i>stop</i> classDef style applied.
+    </p>
+    <pre class="mermaid">
+    stateDiagram
+      direction TB
+
+		  accTitle: This is the accessible title
+      accDescr: This is an accessible description
+
+      classDef notMoving fill:white
+      classDef movement font-style:italic
+      classDef badBadEvent fill:#f00,color:white,font-weight:bold,stroke-width:2px,stroke:yellow
+
+      [*] --> Still:::notMoving
+      Still --> [*]
+      Still --> Moving:::movement
+      Moving --> Still
+      Moving --> Crash:::movement
+      Crash:::badBadEvent --> [*]
+    </pre>
+    <hr />
+
     <pre class="mermaid">
     stateDiagram-v2
       accTitle: very very simple state
@@ -79,6 +129,20 @@ <h4>And these are how they are applied:</h4>
     </pre>
     <hr />
 
+    <h2>States with spaces in them</h2>
+    <pre class="mermaid">
+      stateDiagram
+        classDef yourState font-style:italic,font-weight:bold,fill:white
+
+        yswsii: Your state with spaces in it
+        [*] --> yswsii:::yourState
+        [*] --> SomeOtherState
+        SomeOtherState --> YetAnotherState
+        yswsii --> YetAnotherState
+        YetAnotherState --> [*]
+    </pre>
+    <hr />
+
     <h2>You can label the relationships</h2>
     <pre class="mermaid">
     stateDiagram-v2
@@ -127,7 +191,7 @@ <h2>transition labels can span multiple lines using "br" tags or \n</h2>
     <pre class="mermaid">
       stateDiagram-v2
       [*] --> S1
-      S1 --> S2: This long line uses a br tag<br/>to create multiple<br/>lines.
+      S1 --> S2: This long line uses a br tag<br />to create multiple<br />lines.
       S1 --> S3: This transition descripton uses \na newline character\nto create multiple\nlines.
 
     </pre>
@@ -139,7 +203,7 @@ <h2>You can add Notes</h2>
       direction LR
       State1: A state with a note
       note right of State1
-        Important information!<br />You can write notes.<br/>And\nthey\ncan\nbe\nmulti-\nline.
+        Important information!<br />You can write notes.<br />And\nthey\ncan\nbe\nmulti-\nline.
       end note
       State1 --> State2
       note left of State2 : Notes can be to the left of a state\n(like this one).
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index 3687518b28..a9cb729480 100644
--- a/packages/mermaid/src/docs/syntax/stateDiagram.md
+++ b/packages/mermaid/src/docs/syntax/stateDiagram.md
@@ -35,8 +35,8 @@ stateDiagram
 ```
 
 In state diagrams systems are described in terms of _states_ and how one _state_ can change to another _state_ via
-a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the 
- **Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
+a _transition._ The example diagram above shows three states: **Still**, **Moving** and **Crash**. You start in the
+**Still** state. From **Still** you can change to the **Moving** state. From **Moving** you can change either back to the **Still** state or to
 the **Crash** state. There is no transition from **Still** to **Crash**. (You can't crash if you're still.)
 
 ## States
@@ -266,12 +266,12 @@ As with other diagrams (like flowcharts), you can define a style in the diagram
 state or states in the diagram.
 
 **These are the current limitations with state diagram classDefs:**
+
 1. They cannot be applied to start or end states
 2. The cannot be applied to or within composite states
 
 _These are in development and will be available in a future version._
 
-
 You define a style using the `classDef` keyword, which is short for "class definition" (where "class" means something
 like a _CSS class_)
 followed by _a name for the style,_
@@ -314,7 +314,6 @@ There are two ways to apply a `classDef` style to a state:
 2. use the `:::` operator to apply a classDef style to a state as it is being used in a transition statement (e.g. with an arrow
    to/from another state)
 
-
 #### 1. `class` statement
 
 A `class` statement tells Mermaid to apply the named classDef to one or more classes. The form is:
@@ -335,7 +334,6 @@ Here is an example applying the `movement` style to the two states `Moving` and
 class Moving, Crash movement
 ```
 
-
 Here is a diagram that shows the examples in use. Note that the `Crash` state has two classDef styles applied: `movement`
 and `badBadEvent`
 
@@ -392,8 +390,6 @@ stateDiagram
    Crash:::badBadEvent --> [*]
 ```
 
-
-
 ## Spaces in state names
 
 Spaces can be added to a state by first defining the state with an id and then referencing the id later.
@@ -402,10 +398,11 @@ In the following example there is a state with the id **yswsii** and description
 After it has been defined, **yswsii** is used in the diagram in the first transition (`[*] --> yswsii`)
 and also in the transition to **YetAnotherState** (`yswsii --> YetAnotherState`).  
 (**yswsii** has been styled so that it is different from the other states.)
+
 ```mermaid-example
 stateDiagram
     classDef yourState font-style:italic,font-weight:bold,fill:white
-    
+
     yswsii: Your state with spaces in it
     [*] --> yswsii:::yourState
     [*] --> SomeOtherState

From a09ec69a962c4e2b2c40debdeee2aa226e3fcffc Mon Sep 17 00:00:00 2001
From: Ashley Engelund <weedySeaDragon@users.noreply.github.com>
Date: Tue, 22 Nov 2022 08:49:08 -0800
Subject: [PATCH 8/9] remove 'horz' from  cSpell.json

Co-authored-by: Sidharth Vinod <sidharthv96@gmail.com>
---
 cSpell.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/cSpell.json b/cSpell.json
index 8e92ffa8af..03891165f5 100644
--- a/cSpell.json
+++ b/cSpell.json
@@ -36,7 +36,6 @@
     "graphlib",
     "grav",
     "greywolf",
-    "horz",
     "inkdrop",
     "jaoude",
     "jison",

From c3e054c15573bc413aae98074cf019eb48700597 Mon Sep 17 00:00:00 2001
From: "Ashley Engelund (weedySeaDragon @ github)" <ashley.engelund@gmail.com>
Date: Tue, 22 Nov 2022 08:58:55 -0800
Subject: [PATCH 9/9] tiny fix and change: "The/y cannot" -> "Cannot..."

---
 docs/syntax/stateDiagram.md                      | 4 ++--
 packages/mermaid/src/docs/syntax/stateDiagram.md | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/syntax/stateDiagram.md b/docs/syntax/stateDiagram.md
index afb1349efe..72d7ec63bd 100644
--- a/docs/syntax/stateDiagram.md
+++ b/docs/syntax/stateDiagram.md
@@ -454,8 +454,8 @@ state or states in the diagram.
 
 **These are the current limitations with state diagram classDefs:**
 
-1.  They cannot be applied to start or end states
-2.  The cannot be applied to or within composite states
+1.  Cannot be applied to start or end states
+2.  Cannot be applied to or within composite states
 
 _These are in development and will be available in a future version._
 
diff --git a/packages/mermaid/src/docs/syntax/stateDiagram.md b/packages/mermaid/src/docs/syntax/stateDiagram.md
index a9cb729480..29e355a72b 100644
--- a/packages/mermaid/src/docs/syntax/stateDiagram.md
+++ b/packages/mermaid/src/docs/syntax/stateDiagram.md
@@ -267,8 +267,8 @@ state or states in the diagram.
 
 **These are the current limitations with state diagram classDefs:**
 
-1. They cannot be applied to start or end states
-2. The cannot be applied to or within composite states
+1. Cannot be applied to start or end states
+2. Cannot be applied to or within composite states
 
 _These are in development and will be available in a future version._