Start tutorial

Sources/AccessibilityDocumentation/Constants.swift

@@ -341,20 +341,20 @@ extension UIAccessibilityTraits_ {
 //    
 //    case combined = 2
 //}
-//@available(iOS 11.0, *)
-//public enum UIAccessibilityContainerType : Int, @unchecked Sendable {
-//    
-//    case none = 0
-//    
-//    case dataTable = 1
-//    
-//    case list = 2
-//    
-//    case landmark = 3
-//    
-//    @available(iOS 13.0, *)
-//    case semanticGroup = 4
-//}
+@available(iOS 11.0, *)
+public enum UIAccessibilityContainerType : Int, @unchecked Sendable {
+
+    case none = 0
+
+    case dataTable = 1
+
+    case list = 2
+
+    case landmark = 3
+
+    @available(iOS 13.0, *)
+    case semanticGroup = 4
+}
 //
 //// The following constants can be used with either the accessibilityTextualContext property, or with the
 //// UIAccessibilityTextAttributeContext attributed key.

Sources/AccessibilityDocumentation/Documentation.docc/Articles/AdjustableElements.md

@@ -46,13 +46,16 @@ var accessibilityTraits: UIAccessibilityTraits {
 
 ### Selection follow focus
 
+@Comment {
 // TODO: Selection follow focus
 // TODO: Visual Samples
+}
 
+### `button` and `adjustable`
 
-### Buttona and Adjustable
-
+@Comment {
 // TODO: Stories sample
+}
 
 ### Tutorial
 

Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/ControlHierarchy.md

@@ -40,6 +40,38 @@ Voice Control and Switch Control place focus on buttons and tree should be diffe
 
 As a result you can control what elements from your layout will be exposed to different technologies for better user experience. 
 
+### Containers, nodes and leaf
+
+Visual hierarchy is based on child-parent relation and accessibility tree use the same paradigm. You have two main operations to control the tree:
+- Hide *branch* of element at all. Use ``Book/accessibilityElementsHidden`` to hide the branch.
+- Set element node (leaf or any parent) to be focusable. 
+
+> Important: Setting ``Book/isAccessibilityElement`` to `false` has different meaning according to type of a node:
+> - **Leaf of the tree** will be hidden
+> - **Node of the tree** will be *not focusable*: hierarchy will be traversed for any focusable leaf, when ``Book/isAccessibilityElement`` is set to `true` to them. If there is no such leaf, entire subtree will be hidden.
+
+> Note: Some container can have additional name that prefixed first focused element's description. Supports only by VoiceOver, read more at ``AccessibilityContainer/accessibilityContainerType`` with type ``UIAccessibilityContainerType/semanticGroup``
+
+@Comment {
+    // TODO: Container can has a label when use .semantic
+}
+
+### Tutorial
+
+Read <doc:AdoptingCell> for example
+
+### Modal views
+
+Modal view should done three main things:
+- Limit focus movement by himself. To mark a node as modal we use property ``Book/accessibilityViewIsModal``.
+- Set focus to the first element by posting ``Book/post(notification:argument:)`` with type `.screenChanged`.
+- Support escape gesture to close the screen by adding function ``Book/accessibilityPerformEscape`` to first responder
+
+@Comment {
+    // TODO: Add link to notification
+    // TODO: Add Product Card tutorial
+}
+
 ## Topics
 
 - ``Book/isAccessibilityElement``

Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/DescribeElements.md

@@ -61,7 +61,13 @@ The most common trait is ``UIAccessibilityTraits_/button`` – it helps user to
 
 > Important: Label and Value are `String` properties, but Trait can be selected only from limited amount of variants. Not duplicate trait's textual description inside Label or Value, because different technologies uses trait in different manear, not only for textual description.  
 
-// TODO: Draw full scheme
+@Comment {
+    // TODO: Draw full scheme    
+}
+
+### Tutorial
+
+Read <doc:AdoptingCell> for example
 
 ## Topics
 

Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_1.swift

@@ -0,0 +1,9 @@
+Chicken BBQ
+Pizza sauce...
+from AED 30
+Meat King Supreme
+Pizza sauce...
+from AED 30
+Hawaii
+Pizza sauce...
+from AED 30

Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_2.swift

@@ -0,0 +1,9 @@
+Chicken BBQ
+Pizza sauce...
+from AED 30
+Meat King Supreme
+Pizza sauce...
+from AED 30 // Is it relates...
+Hawaii      // To this title?
+Pizza sauce...
+from AED 30

Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/AdoptingCell.tutorial

@@ -0,0 +1,113 @@
+@Tutorial(time: 10) {
+    @Intro(title: "Adopting cell") {
+
+        Common case when a cell become accessible element and combine all data in its description. For example we have a cell with pizza's description: image, title, ingredients and price. We can dramatically simplify cell for VoiceOver
+
+
+    }
+
+    @Section(title: "The point") {
+        @ContentAndMedia {
+            Cell looks simple, but straitforward layout leads to several accessibility issues
+
+            @Image(source: "Chicken BBQ", alt: "Cell of Chicken BBQ with image, title, ingredients and price")
+        }
+
+        @Steps {
+            @Step {
+                Let's start from VoiceOver problems. 
+
+                First of all focus outlines ever separate element in cell. 
+                Image is hidden from VoiceOver by default (and it's fine), and first focused element is cell. 
+
+                @Image(source: "DescribeCell_1", alt: "Focus outlines title")
+            }
+
+            @Step {
+                After swipe to the right focus moves to ingredients
+
+                @Image(source: "DescribeCell_2", alt: "Focus outlines ingredients")
+            }
+
+            @Step {
+                Next swipe move focus to the button with price. 
+
+                Only here user can understand, that it is interactive element by hearing `.button` trait
+
+                @Image(source: "DescribeCell_3", alt: "Focus outlines button with price")
+            }
+
+            @Step {                
+                In the end user had to do three swipes to passthrough just one cell. 
+
+                Moreover, when he swipes through several steps he can lose his understanding which element connects to which pizza, ingredients will be repetitive and etc
+
+                @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_1.swift") {
+                    @Image(source: "DescribeCell_3_3", alt: "Focus outlines button with price")
+                }
+            }
+
+            @Step {                
+                For e.g. price button may looks connected to next title.
+
+                @Code(name: "Several cells and wrong rhyme", file: "DescribeCell_3_2.swift") {
+                    @Image(source: "DescribeCell_3_3", alt: "Focus outlines button with price")
+                }
+            }
+
+            @Step {
+                Voice Control and Switch Control have problems too. They works with interactive buttons, as a result label will be shown only for price button and user had to pronounce `Tap From AED thirty` to press the cell. 
+
+                It would be much better, if we use title as cell's label. 
+
+                @Image(source: "DescribeCell_4", alt: "Voice Control show badge over button with price")
+            }
+        }
+    }
+
+    @Section(title: "Describe cell") {
+        @ContentAndMedia {
+            <#text#>
+
+            @Image(source: <#file#>, alt: "<#accessible description#>")
+        }
+
+        @Steps {
+            @Step {
+                <#text#>
+
+                @Image(source: <#file#>, alt: "<#accessible description#>")
+            }
+
+            @Step {
+                <#text#>
+
+                @Code(name: "<#display name#>", file: <#filename.swift#>)
+            }
+
+            @Step {
+                <#text#>
+
+                @Code(name: "<#display name#>", file: <#filename.swift#>)
+            }
+        }
+    }
+
+    @Section(title: "Simplify scroll") {
+        @Steps {
+            @Step {
+                <#text#>
+
+                @Image(source: <#file#>, alt: "<#accessible description#>")
+            }
+
+            @Step {
+                <#text#>
+
+                @Code(name: "<#display name#>", file: <#filename.swift#>)
+            }
+        }
+    }
+}
+
+<!--Also we had to set ``Book/isAccessibilityElement`` to `true`, read <doc:ControlHierarchy> for details.-->

Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial

@@ -9,14 +9,22 @@
 <!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
     }
 
-    @Chapter(name: "Desribe elements") {
+    @Chapter(name: "Describe elements") {
         Simplifies navigation and control over a complex element for VoiceOver
 
 <!--        @Image(source: <#file#>, alt: "<#accessible description#>")-->
 
         @TutorialReference(tutorial: "doc:AdjustableTutorial")
     }
 
+    @Chapter(name: "Adopting cell") {
+        Simplifies navigation and control over a complex element for VoiceOver
+
+        @Image(source: "Chicken BBQ", alt: "Cell of Chicken BBQ with image, title, ingredients and price")
+
+        @TutorialReference(tutorial: "doc:AdoptingCell")
+    }
+
     @Chapter(name: "Control hierarchy") {
         Simplifies navigation and control over a complex element for VoiceOver
 
@@ -25,6 +33,8 @@
         @TutorialReference(tutorial: "doc:AdjustableTutorial")
     }
 
+
+
     @Chapter(name: "Adjustable elements") {
         Simplifies navigation and control over a complex element for VoiceOver