Add documentation and examples for POS form component events and slots (#3374)

Resolves
[2025-10 Docs][Followup component audit] ChoiceList	shop/issues-retail#18638
[2025-10 Docs][Followup component audit] DateField	shop/issues-retail#18640
[2025-10 Docs][Followup component audit] DatePicker	shop/issues-retail#18641
[2025-10 Docs][Followup component audit] DateSpinner	shop/issues-retail#18642
[2025-10 Docs][Followup component audit] EmailField	shop/issues-retail#18644
[2025-10 Docs][Followup component audit] NumberField	shop/issues-retail#18649
[2025-10 Docs][Followup component audit] SearchField	shop/issues-retail#18653
[2025-10 Docs][Followup component audit] TextField	shop/issues-retail#18658
[2025-10 Docs][Followup component audit] TimeField	shop/issues-retail#18660
[2025-10 Docs][Followup component audit] TimePicker	shop/issues-retail#18661

### Background

This PR enhances the documentation for POS UI Extension form components by adding JSDoc comments for event handlers and providing usage examples.

### Solution

- Added detailed JSDoc comments to all event handlers (onChange, onInput, onFocus, onBlur) across form components
- Standardized the order of event handlers to be consistent across all components
- Added code examples demonstrating event handling patterns for each component
- Clarified the purpose of accessory slots with better descriptions
- Added examples showing how to use command system with date/time pickers

These improvements make it easier for developers to understand when different events fire and how to properly handle them in their extensions.

### 🎩

Companion PR: https://app.graphite.dev/github/pr/Shopify/shopify-dev/63109

- Verified documentation renders correctly with new JSDoc comments

### Checklist

- [x] I have 🎩'd these changes
- [x] I have updated relevant documentation

Author: awoodall

packages/ui-extensions/src/surfaces/point-of-sale/components.d.ts

@@ -39,8 +39,10 @@ export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
 declare const tagName = 's-choice-list';
 export interface ChoiceListJSXProps
   extends Pick<ChoiceListProps, 'values' | 'multiple'> {
-  onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /** Function called when the user changes a choice. Fires simultaneously with onChange. */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /** Function called when the user changes a choice. Fires simultaneously with onInput. */
+  onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   children?: ComponentChildren;
 }
 declare global {

packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList.d.ts

@@ -15,7 +15,8 @@ const data: ReferenceEntityTemplateSchema = {
     },
     {
       title: 'Events',
-      description: '',
+      description:
+        'Learn more about registering [events](/docs/api/pos-ui-extensions/using-polaris-components#events)',
       type: 'ChoiceListEvents',
     },
     {
@@ -40,6 +41,35 @@ const data: ReferenceEntityTemplateSchema = {
     },
   },
   related: [],
+  examples: {
+    description: 'ChoiceList usage patterns',
+    examples: [
+      {
+        description: 'Enable multiple selection mode with controlled values',
+        codeblock: {
+          title: 'Multiple selection',
+          tabs: [
+            {
+              code: './examples/multiple-selection.jsx',
+              language: 'jsx',
+            },
+          ],
+        },
+      },
+      {
+        description: 'Handle onChange and onInput events.',
+        codeblock: {
+          title: 'Event handling',
+          tabs: [
+            {
+              code: './examples/event-handling.jsx',
+              language: 'jsx',
+            },
+          ],
+        },
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/ChoiceList.doc.ts

@@ -3,4 +3,4 @@
   <s-choice value="m">Medium</s-choice>
   <s-choice value="l">Large</s-choice>
   <s-choice value="xl">Extra large</s-choice>
-</s-choice-list>
+</s-choice-list>

packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/examples/default.html

@@ -0,0 +1,8 @@
+<s-choice-list
+  onChange={(event) => console.log('onChange:', event.target.values)}
+  onInput={(event) => console.log('onInput:', event.target.values)}
+>
+  <s-choice value="option1">Option 1</s-choice>
+  <s-choice value="option2" disabled>Option 2 (disabled)</s-choice>
+  <s-choice value="option3">Option 3</s-choice>
+</s-choice-list>

packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/examples/event-handling.jsx

@@ -0,0 +1,9 @@
+<s-choice-list 
+  multiple
+  values={['small', 'medium']}
+  onChange={(event) => console.log('Selected:', event.target.values)}
+>
+  <s-choice value="small">Small</s-choice>
+  <s-choice value="medium">Medium</s-choice>
+  <s-choice value="large">Large</s-choice>
+</s-choice-list>

packages/ui-extensions/src/surfaces/point-of-sale/components/ChoiceList/examples/multiple-selection.jsx

@@ -8,12 +8,7 @@
 /* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {
-  DateFieldProps,
-  Key,
-  Ref,
-  ComponentChild,
-} from './components-shared.d.ts';
+import type {DateFieldProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
@@ -47,11 +42,14 @@ export interface DateFieldJSXProps
     DateFieldProps,
     'label' | 'details' | 'value' | 'disabled' | 'error'
   > {
+  /** Function called when the user makes any changes in the field. */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /** Function called after editing completes (typically on blur). */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
-  accessory?: ComponentChild;
+  /** Function called when the element loses focus. */
+  onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /** Function called when the element receives focus. */
+  onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 declare global {
   interface HTMLElementTagNameMap {

packages/ui-extensions/src/surfaces/point-of-sale/components/DateField.d.ts

@@ -13,14 +13,10 @@ const data: ReferenceEntityTemplateSchema = {
       description: '',
       type: 'DateField',
     },
-    {
-      title: 'Slots',
-      description: '',
-      type: 'DateFieldSlots',
-    },
     {
       title: 'Events',
-      description: '',
+      description:
+        'Learn more about registering [events](/docs/api/pos-ui-extensions/using-polaris-components#events)',
       type: 'DateFieldEvents',
     },
   ],
@@ -39,6 +35,23 @@ const data: ReferenceEntityTemplateSchema = {
     },
   },
   related: [],
+  examples: {
+    description: 'DateField usage patterns',
+    examples: [
+      {
+        description: 'Handle date input events',
+        codeblock: {
+          title: 'Event handling',
+          tabs: [
+            {
+              code: './examples/event-handling.jsx',
+              language: 'jsx',
+            },
+          ],
+        },
+      },
+    ],
+  },
 };
 
 export default data;

packages/ui-extensions/src/surfaces/point-of-sale/components/DateField/DateField.doc.ts

@@ -0,0 +1,8 @@
+<s-date-field 
+  label="Order date"
+  value="2024-10-26"
+  onInput={(event) => console.log('Input:', event.target.value)}
+  onChange={(event) => console.log('Change:', event.target.value)}
+  onFocus={(event) => console.log('Focused with:', event.target.value)}
+  onBlur={(event) => console.log('Blurred with:', event.target.value)}
+/>

packages/ui-extensions/src/surfaces/point-of-sale/components/DateField/examples/event-handling.jsx

@@ -39,10 +39,14 @@ export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
 declare const tagName = 's-date-picker';
 export interface DatePickerJSXProps
   extends Pick<DatePickerProps, 'id' | 'value'> {
+  /** Function called when the user selects a date from the picker. */
+  onInput?: (event: CallbackEvent<typeof tagName>) => void | null;
+  /** Function called when the user selects a date from the picker that is different to the current value. */
+  onChange?: (event: CallbackEvent<typeof tagName>) => void | null;
+  /** Function called when the date picker is dismissed. */
   onBlur?: (event: CallbackEvent<typeof tagName>) => void | null;
+  /** Function called when the date picker is revealed. */
   onFocus?: (event: CallbackEvent<typeof tagName>) => void | null;
-  onChange?: (event: CallbackEvent<typeof tagName>) => void | null;
-  onInput?: (event: CallbackEvent<typeof tagName>) => void | null;
 }
 declare global {
   interface HTMLElementTagNameMap {