diff --git a/Sources/AccessibilityDocumentation/Constants.swift b/Sources/AccessibilityDocumentation/Constants.swift index 5e8f036..28ec870 100644 --- a/Sources/AccessibilityDocumentation/Constants.swift +++ b/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. diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/AdjustableElements.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/AdjustableElements.md index 4083bce..4f47f7f 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/AdjustableElements.md +++ b/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 diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/ControlHierarchy.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/ControlHierarchy.md index 6d7b19c..b9872f1 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/ControlHierarchy.md +++ b/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 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`` diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/DescribeElements.md b/Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/DescribeElements.md index f9930ae..34e336f 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Articles/Process/DescribeElements.md +++ b/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 for example ## Topics diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/Chicken BBQ.PNG b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/Chicken BBQ.PNG new file mode 100644 index 0000000..3962358 Binary files /dev/null and b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/Chicken BBQ.PNG differ diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_1.png b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_1.png new file mode 100644 index 0000000..0fef8a3 Binary files /dev/null and b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_1.png differ diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_2.png b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_2.png new file mode 100644 index 0000000..0c8ad92 Binary files /dev/null and b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_2.png differ diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3.png b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3.png new file mode 100644 index 0000000..c6e4388 Binary files /dev/null and b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3.png differ diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_1.swift b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_1.swift new file mode 100644 index 0000000..d4f2243 --- /dev/null +++ b/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 diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_2.swift b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_2.swift new file mode 100644 index 0000000..2a25408 --- /dev/null +++ b/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 diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_3.jpeg b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_3.jpeg new file mode 100644 index 0000000..5e0ab27 Binary files /dev/null and b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_3_3.jpeg differ diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_4.png b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_4.png new file mode 100644 index 0000000..6c34a0b Binary files /dev/null and b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_4.png differ diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_5.png b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_5.png new file mode 100644 index 0000000..3025f10 Binary files /dev/null and b/Sources/AccessibilityDocumentation/Documentation.docc/Resources/DescribeElement/DescribeCell_5.png differ diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/AdoptingCell.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/AdoptingCell.tutorial new file mode 100644 index 0000000..b562984 --- /dev/null +++ b/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#>) + } + } + } +} + + diff --git a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial index 0b6377a..01c11e6 100644 --- a/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial +++ b/Sources/AccessibilityDocumentation/Documentation.docc/Tutorials/Tutorial Table of Contents.tutorial @@ -9,7 +9,7 @@ } - @Chapter(name: "Desribe elements") { + @Chapter(name: "Describe elements") { Simplifies navigation and control over a complex element for VoiceOver @@ -17,6 +17,14 @@ @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