Merge pull request #4395 from Shopify/jhen__update_checkbox_docs_to_support_label_slot

Update checkbox docs to support label slot

Author: justinhenricks

.changeset/checkbox-rich-label.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': minor
+---
+
+The `label` prop on the checkout and customer-account `s-checkbox` component now accepts a label as a slot in addition to a plain string, label slots can include only plain text and s-links.

packages/ui-extensions/src/surfaces/checkout/components/Checkbox.d.ts

@@ -11,31 +11,49 @@
 import type {CheckboxProps$1} from './components-shared.d.ts';
 
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. This is used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+     */
     ref?: preact.Ref<TClass>;
+    /**
+     * Assigns the element to a named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 /**
  * An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.
+ * @publicDocs
  */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
 /**
  * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ * @publicDocs
  */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
 }) | null;
 
 declare const tagName = "s-checkbox";
 /** @publicDocs */
-export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'label' | 'name' | 'required' | 'value'> {
+export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'name' | 'required' | 'value'> {
     command?: Extract<CheckboxProps$1['command'], '--auto' | '--show' | '--hide' | '--toggle'>;
+    /**
+     * The visual content to use as the control label. Use a string to provide a simple text label displayed to the user.
+     *
+     * If a `label` slot is also provided, the slot content takes precedence. [Learn more about slots](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/checkbox#slots-propertydetail-label).
+     */
+    label?: string;
 }
+/** @publicDocs */
 export interface CheckboxEvents extends Pick<CheckboxProps$1, 'onChange'> {
 }
 /** @publicDocs */
@@ -47,9 +65,20 @@ export interface CheckboxElementEvents {
      */
     change?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface CheckboxElement extends CheckboxElementProps, Omit<HTMLElement, 'id' | 'onchange'> {
     onchange: CheckboxEvents['onChange'];
 }
+/** @publicDocs */
+export interface CheckboxElementSlots {
+    /**
+     * The visual content to use as the control label.
+     *
+     * Use an `HTMLElement` as a rich control label composed of elements. Only an `s-text` element is supported with plain text and `s-link` as its only allowed children. Any other elements are stripped while preserving their text content.
+     */
+    label?: HTMLElement;
+}
+/** @publicDocs */
 export interface CheckboxProps extends CheckboxElementProps, CheckboxEvents {
 }
 declare global {
@@ -65,4 +94,4 @@ declare module 'preact' {
     }
 }
 
-export type { CheckboxElement, CheckboxElementEvents, CheckboxElementProps, CheckboxEvents, CheckboxProps };
+export type { CheckboxElement, CheckboxElementEvents, CheckboxElementProps, CheckboxElementSlots, CheckboxEvents, CheckboxProps };

packages/ui-extensions/src/surfaces/checkout/components/Checkbox/Checkbox.doc.ts

@@ -5,7 +5,7 @@ import {createComponentDoc} from '../../../../docs/shared/component-definitions'
 
 const data: ReferenceEntityTemplateSchema = createComponentDoc({
   ...sharedContent,
-  definitions: {properties: true, events: true},
+  definitions: {properties: true, events: true, slots: true},
 });
 
 export default data;