Improve Polaris component examples - Batch 1 (MoneyField, PasswordField, Select, Switch, URLField)

.changeset/rude-memes-itch.md

@@ -0,0 +1,2 @@
+---
+---

packages/ui-extensions/src/surfaces/admin/components/MoneyField/MoneyField.doc.ts

@@ -42,18 +42,14 @@ const data: AdminReferenceEntityTemplateSchema = {
     },
   ],
   defaultExample: {
-    image: 'moneyfield-default.png',
+    description:
+      'Capture monetary values with automatic currency formatting. This example shows a labeled money field with placeholder text and helper details.',
     codeblock: {
-      title: 'Code',
+      title: 'Collect a currency value',
       tabs: [
         {
           code: './examples/default.html',
-          language: 'html',
-        },
-
-        {
-          code: './examples/default.jsx',
-          language: 'preview-jsx',
+          language: 'preview',
         },
       ],
     },
@@ -62,90 +58,57 @@ const data: AdminReferenceEntityTemplateSchema = {
     description: 'Component examples',
     exampleGroups: [
       {
-        title: 'Basic usage',
+        title: '',
         examples: [
           {
             description:
-              'Demonstrates a simple money field with a label, initial value, and numeric constraints.',
+              'Guide users with constraints and helpful context. This example shows a money field with min/max limits and helper text explaining the valid range.',
             codeblock: {
-              title: 'Basic usage',
+              title: 'Add a label and constraints',
               tabs: [
                 {
                   code: './examples/basic-usage.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/basic-usage.jsx',
-                  language: 'preview-jsx',
-                },
-              ],
-            },
-          },
-          {
-            description:
-              'Showcases a money field with explicit minimum and maximum value limits, and a detailed description for user guidance.',
-            codeblock: {
-              title: 'With validation limits',
-              tabs: [
-                {
-                  code: './examples/with-validation-limits.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/with-validation-limits.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Illustrates a money field demonstrating basic error handling and validation.',
+              'Communicate input problems clearly to users. This example shows an error message displayed when the entered value is invalid.',
             codeblock: {
-              title: 'Basic field',
+              title: 'Handle validation errors',
               tabs: [
                 {
                   code: './examples/basic-field.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/basic-field.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Displays multiple money fields in a vertical stack, showing how to integrate multiple currency inputs in a form with varied details and constraints.',
+              'Collect multiple monetary values in a single form. This example shows money fields for price, compare-at price, and cost with individual constraints.',
             codeblock: {
-              title: 'Currency formatting with form integration',
+              title: 'Combine multiple fields in a form',
               tabs: [
                 {
                   code: './examples/currency-formatting-with-form-integration.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/currency-formatting-with-form-integration.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
         ],
       },
       {
-        title: 'Form validation',
+        title: '',
         examples: [
           {
             description:
-              'Interactive example showing real-time validation with min/max limits and dynamic error messages.',
+              'Provide immediate feedback as users type. This example shows real-time validation with dynamic error messages when values exceed min/max limits.',
             codeblock: {
-              title: 'Money field validation',
+              title: 'Validate input in real time',
               tabs: [
                 {
                   code: './examples/validation-example.jsx',

packages/ui-extensions/src/surfaces/admin/components/MoneyField/examples/basic-usage.html

@@ -3,4 +3,5 @@
   value="19.99"
   min="0"
   max="1000"
+  details="Enter a value between $0 and $1,000"
 ></s-money-field>

packages/ui-extensions/src/surfaces/admin/components/PasswordField/PasswordField.doc.ts

@@ -39,18 +39,14 @@ const data: AdminReferenceEntityTemplateSchema = {
     },
   ],
   defaultExample: {
-    image: 'password-field-default.png',
+    description:
+      'Securely collect sensitive credentials from users. This example shows a labeled password field with masked input.',
     codeblock: {
-      title: 'Code',
+      title: 'Collect a password',
       tabs: [
         {
           code: './examples/default.html',
-          language: 'html',
-        },
-
-        {
-          code: './examples/default.jsx',
-          language: 'preview-jsx',
+          language: 'preview',
         },
       ],
     },
@@ -59,93 +55,86 @@ const data: AdminReferenceEntityTemplateSchema = {
     description: 'Component examples',
     exampleGroups: [
       {
-        title: 'Basic usage',
+        title: '',
         examples: [
           {
             description:
-              'Demonstrates a basic password field with a label, name, and required validation. Sets a minimum length of 8 characters and configures autocomplete for a new password.',
+              'Enforce password requirements before submission. This example shows a required field with minimum length validation and autocomplete for new passwords.',
             codeblock: {
-              title: 'Basic usage',
+              title: 'Set validation rules',
               tabs: [
                 {
                   code: './examples/basic-usage.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/basic-usage.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Shows a password field in an error state, displaying a custom error message when the password does not meet the minimum length requirement.',
+              "Communicate password problems clearly to users. This example shows an error message when the password doesn't meet length requirements.",
             codeblock: {
-              title: 'With error state',
+              title: 'Show validation errors',
               tabs: [
                 {
                   code: './examples/with-error-state.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/with-error-state.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Illustrates a password field with additional details providing guidance about password creation requirements.',
+              'Help users understand password requirements upfront. This example shows helper text beneath the field explaining what makes a valid password.',
             codeblock: {
-              title: 'With helper text',
+              title: 'Add helper text',
               tabs: [
                 {
                   code: './examples/with-helper-text.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/with-helper-text.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Shows how the password field can be integrated into a form alongside other input fields, such as an email field, to create a complete login or registration form.',
+              'Create a complete authentication form. This example shows a password field combined with an email field for login or registration.',
             codeblock: {
-              title: 'In form layout',
+              title: 'Build a login form',
               tabs: [
                 {
                   code: './examples/in-form-layout.html',
-                  language: 'html',
-                },
-
-                {
-                  code: './examples/in-form-layout.jsx',
-                  language: 'preview-jsx',
+                  language: 'preview',
                 },
               ],
             },
           },
           {
             description:
-              'Demonstrates a password field with dynamic password strength validation, showing real-time feedback on password complexity requirements.',
+              'Show users exactly what their password needs. This example shows a static checklist of requirements like character length and case requirements.',
             codeblock: {
-              title: 'With password strength requirements',
+              title: 'Display a requirement checklist',
               tabs: [
                 {
                   code: './examples/with-password-strength-requirements.html',
-                  language: 'html',
+                  language: 'preview',
                 },
-
+              ],
+            },
+          },
+        ],
+      },
+      {
+        title: '',
+        examples: [
+          {
+            description:
+              'Provide immediate feedback on password quality. This example shows real-time validation that checks requirements as the user types.',
+            codeblock: {
+              title: 'Validate password strength',
+              tabs: [
                 {
-                  code: './examples/with-password-strength-requirements.jsx',
+                  code: './examples/password-strength-validation.jsx',
                   language: 'preview-jsx',
                 },
               ],