2.0: Readme updates (#461)

* docs: update readme screenshots * chore: update gallery to match readme * fix: `HelpButton` sizing * chore: deprecate `RelevanceIndicator` * update version, changelog, & remove `RelevanceIndicator` from gallery & tests
macosui · Jul 19, 2023 · be20db0 · be20db0
1 parent d7eaf5b
commit be20db0
Show file tree

Hide file tree

Showing 10 changed files with 112 additions and 141 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,10 @@
+## [2.0.0-beta.11]
+🚨 Breaking Changes 🚨
+* `RelevanceIndicator` has been deprecated
+
+🔄 Updated 🔄
+* `HelpButton` now sizes itself according to specification
+
 ## [2.0.0-beta.10]
 🛠️ Fixed 🛠️
 * Ensure builds targeting web do not utilize any `macos_window_utils` code

diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ Guides, codelabs, and other documentation can be found at https://macosui.dev
 [![codecov](https://github.com/GroovinChip/macos_ui/actions/workflows/codecov.yaml/badge.svg)](https://github.com/GroovinChip/macos_ui/actions/workflows/codecov.yaml)
 [![codecov](https://codecov.io/gh/GroovinChip/macos_ui/branch/dev/graph/badge.svg?token=1SZGEVVMCH)](https://codecov.io/gh/GroovinChip/macos_ui)
 
-<img src="https://imgur.com/5mFQKBU.png" width="75%"/>
+<img src="https://imgur.com/44iJB7H.png" width="75%"/>
 
 ## 🚨 Usage notes
 ### <img src="https://storage.googleapis.com/cms-storage-bucket/0dbfcc7a59cd1cf16282.png" height="14"/> Flutter channel
@@ -23,10 +23,13 @@ Guides, codelabs, and other documentation can be found at https://macosui.dev
 ### <img src="https://storage.googleapis.com/cms-storage-bucket/0dbfcc7a59cd1cf16282.png" height="14"/> Platform Compatibility
 
 pub.dev shows that `macos_ui` only supports macOS. This is because `macos_ui` calls some native code, and therefore 
-specifies macOS as a plugin platform in the `pubspec.yaml` file. `macos_ui` _will_ work on any platform that
-Flutter supports, **but you will get best results on macOS**.
+specifies macOS as a plugin platform in the `pubspec.yaml` file.
+
+`macos_ui` _technically_ will work on any platform that
+Flutter supports, **but you will get best results on macOS**. non-macOS platform support is ***not*** guaranteed.
 
 The features of `macos_ui` that will _not_ work on platforms other than macOS due to calling native code are:
+* Anything related to `macos_window_utils`
 * The `MacosColors.controlAccentColor()` function
 * The `MacosColorWell` widget
 
@@ -43,9 +46,8 @@ should avoid allowing your application window to be resized below the height of
 <details>
 <summary>Contributing & Resources</summary>
 
-- [macos_ui](#macos_ui)
-  - [Contributing](#contributing)
-  - [Resources](#resources)
+- [Contributing](#contributing)
+- [Resources](#resources)
 </details>
 
 <details>
@@ -111,7 +113,6 @@ should avoid allowing your application window to be resized below the height of
   - [Level Indicators](#level-indicators)
     - [CapacityIndicator](#capacityindicator)
     - [RatingIndicator](#ratingindicator)
-    - [RelevanceIndicator](#relevanceindicator)
 </details>
 
 <details>
@@ -131,9 +132,9 @@ should avoid allowing your application window to be resized below the height of
 
 ## Resources
 
+- [macOS Sonoma Figma kit](https://www.figma.com/file/M6K5L3GK0WJh6pnsASyVeE/macOS-Big-Sur-UI-Kit?node-id=1%3A2)
+- [macOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/designing-for-macos)
 - [macOS Design Resources](https://developer.apple.com/design/resources/)
-- [macOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/macos)
-- [macOS Big Sur Figma kit](https://www.figma.com/file/M6K5L3GK0WJh6pnsASyVeE/macOS-Big-Sur-UI-Kit?node-id=1%3A2)
 
 # Layout
 
@@ -158,7 +159,7 @@ A sidebar enables app navigation and provides quick access to top-level collecti
 
 Sidebars may be placed at the left or right of your app. To place a sidebar on the left, use the `MacosWindow.sidebar` property. To place a sidebar on the right, use the `MacosWindow.endSidebar` property.
 
-<img src="https://imgur.com/sz4VPNR.png" width="75%"/>
+<img src="https://imgur.com/BfoHcXE.png" width="75%"/>
 
 Example usage:
 
@@ -217,21 +218,20 @@ covering the entire window. To push a route outside a `MacosScaffold` wrapped in
 
 See the documentation for customizations and `ToolBar` examples.
 
-<img src="https://imgur.com/KT1fdjI.png" width="75%"/>
-
-<img src="https://imgur.com/4mknLAy.png" width="75%"/>
+<img src="https://imgur.com/ePV2x2p.png" width="75%"/>
 
-<img src="https://imgur.com/mXR2wwu.png" width="75%"/>
+<img src="https://imgur.com/76fpFE2.png" width="75%"/>
 
 ## Modern window look
 
-A new look for macOS apps was introduced in Big Sur (macOS 11). To match that look 
-in your Flutter app, macos_ui relies on [macos_window_utils](https://pub.dev/packages/macos_window_utils), which requires a minimum macOS deployment target of 10.14.6. Therefore, make sure to open the `macos/Runner.xcworkspace` folder of your project using Xcode and search for `Runner.xcodeproj`. Go to `Info` > `Deployment Target` and set the `macOS Deployment Target` to `10.14.6` or above. Then, open your project's `Podfile` (if it doesn't show up in Xcode, you can find it in your project's `macos` directory via VS Code) and set the minimum deployment version in the first line to `10.14.6` or above:
+A new look for macOS apps was introduced in Big Sur (macOS 11). To match that look in your Flutter app, macos_ui relies on [macos_window_utils](https://pub.dev/packages/macos_window_utils), which requires a minimum macOS deployment target of 10.14.6. Therefore, make sure to open the `macos/Runner.xcworkspace` folder of your project using Xcode and search for `Runner.xcodeproj`. Go to `Info` > `Deployment Target` and set the `macOS Deployment Target` to `10.14.6` or above. Then, open your project's `Podfile` (if it doesn't show up in Xcode, you can find it in your project's `macos` directory via VS Code) and set the minimum deployment version in the first line to `10.14.6` or above:
 
 ```podspec
 platform :osx, '10.14.6'
 ```
 
+You may also need to open up your app's `Runner.xcodeproj` in XCode and set the minimum deployment version there.
+
 Now, configure your window inside your `main()` as follows:
 
 ```dart
@@ -246,7 +246,7 @@ Future<void> _configureMacosWindowUtils() async {
 void main() async {
   await _configureMacosWindowUtils();
 
-  runApp(const MacosUIGalleryApp());
+  runApp(const YourAppHere());
 }
 ```
 
@@ -335,7 +335,7 @@ Other toolbar examples:
 <img src="https://imgur.com/Ouaud12.png"/>
 
 - Toolbar with a pulldown button open:
-<img src="https://imgur.com/QCxoGmM.png"/>
+<img src="https://imgur.com/msGmcNY.png"/>
 
 - Toolbar with title bar above (also see [the note above](#modern-window-look)):
 <img src="https://imgur.com/eAgcsKY.png"/>
@@ -408,7 +408,7 @@ MacosListTile(
 ## MacosTabView
 A multipage interface that displays one page at a time. Must be used in a `StatefulWidget`.
 
-<img src="https://imgur.com/Mdn7Li2.png"/>
+<img src="https://imgur.com/WNF1CSl.png"/>
 
 You can control the placement of the tabs using the `position` property.
 
@@ -472,9 +472,9 @@ A checkbox is a type of button that lets the user choose between two opposite st
 checkbox is considered on when it contains a checkmark and off when it's empty. A checkbox is almost always followed 
 by a title unless it appears in a checklist. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/buttons/checkboxes/)
 
-| Off                                                                                                                   | On                                                                                                                 | Mixed                                                                                                              |
+| Unchecked                                                                                                                   | Checked                                                                                                                 | Mixed                                                                                                              |
 | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| ![Off Checkbox](https://developer.apple.com/design/human-interface-guidelines/macos/images/CheckBoxes_Deselected.svg) | ![On Checkbox](https://developer.apple.com/design/human-interface-guidelines/macos/images/CheckBoxes_Selected.svg) | ![Mixed Checkbox](https://developer.apple.com/design/human-interface-guidelines/macos/images/CheckBoxes_Mixed.svg) |
+| ![Unchecked Checkbox](https://imgur.com/Pu4EDAE.png) | ![Checked Checkbox](https://imgur.com/CB3Kmwo.png) | ![Mixed Checkbox](https://imgur.com/T44rV38.png) |
 
 Here's an example of how to create a basic checkbox:
 
@@ -496,7 +496,7 @@ To make a checkbox in the `mixed` state, set `value` to `null`.
 A help button appears within a view and opens app-specific help documentation when clicked. All help buttons are 
 circular, consistently sized buttons that contain a question mark icon. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/buttons/help-buttons/)
 
-![HelpButton Example](https://developer.apple.com/design/human-interface-guidelines/macos/images/buttonsHelp.png)
+![HelpButton Example](https://imgur.com/DlP7uLV.png)
 
 Here's an example of how to create a help button:
 
@@ -517,7 +517,7 @@ A radio button is a small, circular button followed by a title. Typically presen
 buttons provide the user a set of related but mutually exclusive choices. A radio button’s state is either on 
 (a filled circle) or off (an empty circle). [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/buttons/radio-buttons/)
 
-![RadioButton Preview](https://developer.apple.com/design/human-interface-guidelines/macos/images/radioButtons.png)
+![RadioButton Preview](https://imgur.com/HI0eQsU.png)
 
 Here's an example of how to create a basic radio button:
 
@@ -636,8 +636,8 @@ Push buttons are the standard button type in macOS. Push buttons contain text—
 complete a task. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/buttons/push-buttons/)
 
 | Dark Theme                                 | Light Theme                                |
-|--------------------------------------------|--------------------------------------------|
-| <img src="https://imgur.com/iWNuPqs.png"/> | <img src="https://imgur.com/QPIHrJt.png"/> |
+| ------------------------------------------ | ------------------------------------------ |
+| <img src="https://imgur.com/RLg1tWu.png"/> | <img src="https://imgur.com/zymbEIE.png"/> |
 
 ℹ️ **Note** ℹ️
 Native push buttons can be styled as text-only, text with an icon, or icon-only. Currently, text-only push buttons are supported. To create an icon-only button, use the `MacosIconButton` widget.
@@ -666,8 +666,8 @@ control sizes:
 * `regular`
 
 | Off                                        | On                                         |
-|--------------------------------------------|--------------------------------------------|
-| <img src="https://imgur.com/NBeTMoZ.jpg"/> | <img src="https://imgur.com/SBfE0jf.jpg"/> |
+| ------------------------------------------ | ------------------------------------------ |
+| <img src="https://imgur.com/bH7I0Lg.png"/> | <img src="https://imgur.com/uuaXiS3.png"/> |
 
 Here's an example of how to create a basic toggle switch:
 
@@ -689,7 +689,7 @@ Learn more about switches [here](https://developer.apple.com/design/human-interf
 Displays one or more navigational tabs in a single horizontal group. Used by `MacosTabView` to navigate between the 
 different tabs of the tab bar.
 
-<img src="https://imgur.com/Igvms1w.jpg"/>
+<img src="https://imgur.com/6fIkCMr.png"/>
 
 The typical usage of this widget is by `MacosTabView`, to control the navigation of its children. You do not need to 
 specify a `MacosSegmentedControl` with your `MacosTabView`, as it is built by that widget.
@@ -722,9 +722,10 @@ showMacosAlertDialog(
 );
 ```
 
-![](https://imgur.com/G3dcjew.png)
-![](https://imgur.com/YHtgv59.png)
-![](https://imgur.com/xuBR5qK.png)
+![](https://imgur.com/4zbGsFi.png)
+![](https://imgur.com/5fgkRU9.png)
+![](https://imgur.com/jOyJrZO.png)
+![](https://imgur.com/NX9taPj.png)
 
 ## MacosSheet
 
@@ -736,7 +737,7 @@ showMacosSheet(
 );
 ```
 
-![](https://imgur.com/NV0o5Ws.png)
+![](https://imgur.com/Mnw2ywm.png)
 
 # Fields
 
@@ -823,8 +824,6 @@ Progress indicators have two distinct styles:
 People don't interact with progress indicators; however, they are often accompanied by a button for canceling the 
 corresponding operation. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/indicators/progress-indicators/)
 
-![Progress Indicator Example](https://developer.apple.com/design/human-interface-guidelines/macos/images/ProgressIndicators_Lead.png)
-
 ### ProgressCircle
 
 A `ProgressCircle` can be either determinate or indeterminate.
@@ -870,10 +869,8 @@ indicator styles, each with a different appearance, for communicating capacity,
 A capacity indicator illustrates the current level in relation to a finite capacity. Capacity indicators are often used 
 when communicating factors like disk and battery usage. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/indicators/level-indicators#capacity-indicators)
 
-| Continuous                                                                                                                                     | Discrete                                                                                                                                                                                                         |
-| ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ![Continuous CapacityIndicator Example](https://developer.apple.com/design/human-interface-guidelines/macos/images/indicators-continous.png)   | ![Discrete CapacityIndicator Example](https://developer.apple.com/design/human-interface-guidelines/macos/images/indicators-discrete.png)                                                                        |
-| A horizontal translucent track that fills with a colored bar to indicate the current value. Tick marks are often displayed to provide context. | A horizontal row of separate, equally sized, rectangular segments. The number of segments matches the total capacity, and the segments fill completely—never partially—with color to indicate the current value. |
+<img src="https://imgur.com/U7hcCqJ.png" />
+<img src="https://imgur.com/AJyXG6p.png" />
 
 Here's an example of how to create an interactive continuous capacity indicator:
 
@@ -919,7 +916,7 @@ MacosSlider(
 A rating indicator uses a series of horizontally arranged graphical symbols to communicate a ranking level. The default 
 symbol is a star.
 
-![RatingIndicator Example](https://developer.apple.com/design/human-interface-guidelines/macos/images/indicator-rating.png)
+![RatingIndicator Example](https://imgur.com/ySQBpL6.png)
 
 A rating indicator doesn’t display partial symbols—its value is rounded in order to display complete symbols only. 
 Within a rating indicator, symbols are always the same distance apart and don't expand or shrink to fit the control. 
@@ -939,22 +936,6 @@ RatingIndicator(
 )
 ```
 
-### RelevanceIndicator
-
-A relevance indicator communicates relevancy using a series of vertical bars. It often appears in a list of search 
-results for reference when sorting and comparing multiple items. [Learn more](https://developer.apple.com/design/human-interface-guidelines/macos/indicators/level-indicators#relevance-indicators)
-
-![RelevanceIndicator Example](https://developer.apple.com/design/human-interface-guidelines/macos/images/indicator-relevance.png)
-
-Here's an example of how to create a relevance indicator:
-
-```dart
-RelevanceIndicator(
-  value: 15,
-  amount: 20,
-)
-```
-
 # Selectors
 
 ## MacosDatePicker

diff --git a/example/lib/pages/buttons_page.dart b/example/lib/pages/buttons_page.dart
@@ -431,6 +431,10 @@ class _ButtonsPageState extends State<ButtonsPage> {
                     ],
                   ),
                   const SizedBox(height: 16),
+                  const WidgetTextTitle1(widgetName: 'HelpButton'),
+                  Divider(color: MacosTheme.of(context).dividerColor),
+                  HelpButton(onPressed: () {}),
+                  const SizedBox(height: 16),
                   Text(
                     'Icon Buttons',
                     style: MacosTypography.of(context).title1,

diff --git a/example/lib/pages/dialogs_page.dart b/example/lib/pages/dialogs_page.dart
@@ -209,47 +209,50 @@ class DemoSheet extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     return MacosSheet(
-      child: Center(
-        child: Column(
-          children: [
-            const SizedBox(height: 50),
-            const FlutterLogo(
-              size: 56,
-            ),
-            const SizedBox(height: 24),
-            Text(
-              'Welcome to macos_ui',
-              style: MacosTheme.of(context).typography.largeTitle.copyWith(
-                    fontWeight: FontWeight.bold,
-                  ),
-            ),
-            const SizedBox(height: 24),
-            const MacosListTile(
-              leading: MacosIcon(CupertinoIcons.lightbulb),
-              title: Text(
-                'A robust library of Flutter components for macOS',
-                //style: MacosTheme.of(context).typography.headline,
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 8.0),
+        child: Center(
+          child: Column(
+            children: [
+              const SizedBox(height: 50),
+              const FlutterLogo(
+                size: 56,
               ),
-              subtitle: Text(
-                'Create native looking macOS applications using Flutter',
+              const SizedBox(height: 24),
+              Text(
+                'Welcome to macos_ui',
+                style: MacosTheme.of(context).typography.largeTitle.copyWith(
+                      fontWeight: FontWeight.bold,
+                    ),
               ),
-            ),
-            const SizedBox(height: 16),
-            const MacosListTile(
-              leading: MacosIcon(CupertinoIcons.bolt),
-              title: Text(
-                'Create beautiful macOS applications in minutes',
-                //style: MacosTheme.of(context).typography.headline,
+              const SizedBox(height: 24),
+              const MacosListTile(
+                leading: MacosIcon(CupertinoIcons.lightbulb),
+                title: Text(
+                  'A robust library of Flutter components for macOS',
+                  //style: MacosTheme.of(context).typography.headline,
+                ),
+                subtitle: Text(
+                  'Create native looking macOS applications using Flutter',
+                ),
               ),
-            ),
-            const Spacer(),
-            PushButton(
-              controlSize: ControlSize.regular,
-              child: const Text('Get started'),
-              onPressed: () => Navigator.of(context).pop(),
-            ),
-            const SizedBox(height: 50),
-          ],
+              const SizedBox(height: 16),
+              const MacosListTile(
+                leading: MacosIcon(CupertinoIcons.bolt),
+                title: Text(
+                  'Create beautiful macOS applications in minutes',
+                  //style: MacosTheme.of(context).typography.headline,
+                ),
+              ),
+              const Spacer(),
+              PushButton(
+                controlSize: ControlSize.regular,
+                child: const Text('Get started'),
+                onPressed: () => Navigator.of(context).pop(),
+              ),
+              const SizedBox(height: 50),
+            ],
+          ),
         ),
       ),
     );