@heymantle/litho 0.0.14 → 0.0.16

package/dist/esm/components/DropZone.js

@@ -10,6 +10,19 @@ function _array_with_holes(arr) {
 function _array_without_holes(arr) {
     if (Array.isArray(arr)) return _array_like_to_array(arr);
 }
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
 function _iterable_to_array(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
@@ -43,6 +56,45 @@ function _non_iterable_rest() {
 function _non_iterable_spread() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
 function _sliced_to_array(arr, i) {
     return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
 }
@@ -69,34 +121,20 @@ import SkeletonText from "./SkeletonText.js";
 import Spinner from "./Spinner.js";
 import Text from "./Text.js";
 import { CancelMajor, CircleAlertMajor, FileMinor, ImageMajor, ImagesMajor, MagicMajor } from "@shopify/polaris-icons";
-var dropZoneStyles = tv({
-    base: "Litho-DropZone w-full flex items-center justify-center p-4 border border-form-border border-dashed rounded-md focus:outline-hidden",
-    variants: {
-        uploading: {
-            true: "bg-form-bg-disabled",
-            false: ""
-        },
-        disabled: {
-            true: "pointer-events-none user-select-none",
-            false: "cursor-pointer bg-form-bg hover:bg-form-bg-hover"
-        },
-        hasFocusWithin: {
-            true: "ring ring-form-focus border-form-border-focus",
-            false: ""
-        },
-        dragOver: {
-            true: "bg-form-bg-hover border-form-border-focus ring ring-form-focus",
-            false: ""
-        }
-    },
-    defaultVariants: {
-        disabled: false,
-        uploading: false,
-        dragOver: false
-    }
-});
 /**
- * DropZone component for handling file uploads with previews.
+ * @component DropZone
+ *
+ * @description A file upload area that accepts drag-and-drop or click-to-browse file selection with type and size validation.
+ *
+ * @usage
+ * - DO: Use for file upload areas that accept drag-and-drop or click-to-browse.
+ * - DON'T: Use for non-file inputs.
+ *
+ * @accessibility
+ * - Supports keyboard activation; ensure a descriptive label is provided for the upload area.
+ *
+ * @alternative
+ * - If you need a simple file input, use a native `<input type="file">` with TextField styling.
  *
  * @param {Object} props - Component props.
  * @param {string} [props.id] - The ID for the DropZone input.
@@ -127,14 +165,72 @@ var dropZoneStyles = tv({
  * @param {Function} [props.onFilePreviewClick] - Callback for clicking a file preview.
  * @param {string} [props.filename] - Name of the file being uploaded.
  * @returns {JSX.Element} DropZone component.
- */ function DropZone() {
+ */ var normalizeDropZoneAccept = function(accept) {
+    if (!accept) return [];
+    return typeof accept === "string" ? [
+        accept
+    ] : accept;
+};
+var isFileAcceptedForDropZone = function(file) {
+    var accept = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : [];
+    if (!accept || accept.length === 0) return true;
+    return accept.some(function(type) {
+        if (!type) return false;
+        if (type === "*/*") return true;
+        if (type.endsWith("/*")) {
+            var _type_split = _sliced_to_array(type.split("/"), 1), prefix = _type_split[0];
+            if (prefix === "*") return true;
+            return !!(file === null || file === void 0 ? void 0 : file.type) && file.type.startsWith("".concat(prefix, "/"));
+        }
+        return (file === null || file === void 0 ? void 0 : file.type) === type;
+    });
+};
+var partitionFilesByDropZoneAccept = function(files) {
+    var accept = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : [];
+    var acceptedFiles = [];
+    var rejectedFiles = [];
+    files.forEach(function(file) {
+        if (isFileAcceptedForDropZone(file, accept)) {
+            acceptedFiles.push(file);
+        } else {
+            rejectedFiles.push(file);
+        }
+    });
+    return {
+        acceptedFiles: acceptedFiles,
+        rejectedFiles: rejectedFiles
+    };
+};
+var dropZoneStyles = tv({
+    base: "Litho-DropZone w-full flex items-center justify-center p-4 border border-form-border border-dashed rounded-md focus:outline-hidden",
+    variants: {
+        uploading: {
+            true: "bg-form-bg-disabled",
+            false: ""
+        },
+        disabled: {
+            true: "pointer-events-none user-select-none",
+            false: "cursor-pointer bg-form-bg hover:bg-form-bg-hover"
+        },
+        hasFocusWithin: {
+            true: "ring ring-form-focus border-form-border-focus",
+            false: ""
+        },
+        dragOver: {
+            true: "bg-form-bg-hover border-form-border-focus ring ring-form-focus",
+            false: ""
+        }
+    },
+    defaultVariants: {
+        disabled: false,
+        uploading: false,
+        dragOver: false
+    }
+});
+function DropZone() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var id = props.id, label = props.label, labelHidden = props.labelHidden, labelAction = props.labelAction, tooltip = props.tooltip, labelVariant = props.labelVariant, _props_type = props.type, type = _props_type === void 0 ? "file" : _props_type, _accept = props.accept, _props_allowMultiple = props.allowMultiple, allowMultiple = _props_allowMultiple === void 0 ? false : _props_allowMultiple, _props_showDropZoneWhenDisabled = props.showDropZoneWhenDisabled, showDropZoneWhenDisabled = _props_showDropZoneWhenDisabled === void 0 ? true : _props_showDropZoneWhenDisabled, _disabled = props.disabled, onDrop = props.onDrop, onDropAccepted = props.onDropAccepted, onDropRejected = props.onDropRejected, helpText = props.helpText, error = props.error, _props_uploading = props.uploading, uploading = _props_uploading === void 0 ? false : _props_uploading, _props_uploadedFiles = props.uploadedFiles, uploadedFiles = _props_uploadedFiles === void 0 ? [] : _props_uploadedFiles, _props_uploadLabel = props.uploadLabel, uploadLabel = _props_uploadLabel === void 0 ? "Drag and drop files or click to upload" : _props_uploadLabel, _props_uploadingLabel = props.uploadingLabel, uploadingLabel = _props_uploadingLabel === void 0 ? "Uploading..." : _props_uploadingLabel, _props_dragLabel = props.dragLabel, dragLabel = _props_dragLabel === void 0 ? "Release to upload" : _props_dragLabel, tmp = props.showFilePreview, _showFilePreview = tmp === void 0 ? true : tmp, previewLoading = props.previewLoading, _props_previewRows = props.previewRows, previewRows = _props_previewRows === void 0 ? 2 : _props_previewRows, onRemove = props.onRemove, onFilePreviewClick = props.onFilePreviewClick, filename = props.filename;
-    var accept = _accept ? typeof _accept === "string" ? [
-        _accept
-    ] : _accept : [
-        "*/*"
-    ];
+    var accept = normalizeDropZoneAccept(_accept);
     var inputRef = useRef(null);
     var _useState = _sliced_to_array(useState(false), 2), hasFocusWithin = _useState[0], setHasFocusWithin = _useState[1];
     var _useState1 = _sliced_to_array(useState(false), 2), isDraggingOver = _useState1[0], setIsDraggingOver = _useState1[1];
@@ -195,22 +291,7 @@ var dropZoneStyles = tv({
         setDragFileCount(0);
         if (disabled) return;
         var droppedFiles = Array.from(event.dataTransfer.files);
-        var acceptedFiles = [];
-        var rejectedFiles = [];
-        droppedFiles.forEach(function(file) {
-            var isValidType = typeAccept.length === 0 || typeAccept.some(function(type) {
-                if (type.endsWith("/*")) {
-                    return file.type.startsWith("".concat(type.split("/")[0], "/"));
-                }
-                return file.type === type;
-            });
-            var isValid = isValidType;
-            if (isValid) {
-                acceptedFiles.push(file);
-            } else {
-                rejectedFiles.push(file);
-            }
-        });
+        var _partitionFilesByDropZoneAccept = partitionFilesByDropZoneAccept(droppedFiles, typeAccept), acceptedFiles = _partitionFilesByDropZoneAccept.acceptedFiles, rejectedFiles = _partitionFilesByDropZoneAccept.rejectedFiles;
         if (onDrop) {
             onDrop(droppedFiles);
         }
@@ -223,22 +304,7 @@ var dropZoneStyles = tv({
     };
     var handleFileChange = function(event) {
         var selectedFiles = Array.from(event.target.files);
-        var acceptedFiles = [];
-        var rejectedFiles = [];
-        selectedFiles.forEach(function(file) {
-            var isValidType = typeAccept.length === 0 || typeAccept.some(function(type) {
-                if (type.endsWith("/*")) {
-                    return file.type.startsWith("".concat(type.split("/")[0], "/"));
-                }
-                return file.type === type;
-            });
-            var isValid = isValidType;
-            if (isValid) {
-                acceptedFiles.push(file);
-            } else {
-                rejectedFiles.push(file);
-            }
-        });
+        var _partitionFilesByDropZoneAccept = partitionFilesByDropZoneAccept(selectedFiles, typeAccept), acceptedFiles = _partitionFilesByDropZoneAccept.acceptedFiles, rejectedFiles = _partitionFilesByDropZoneAccept.rejectedFiles;
         if (onDrop) {
             onDrop(selectedFiles);
         }
@@ -358,6 +424,56 @@ var dropZoneStyles = tv({
         ]
     });
 }
+var DropTarget = function() {
+    var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
+    var _accept = props.accept, _props_allowMultiple = props.allowMultiple, allowMultiple = _props_allowMultiple === void 0 ? true : _props_allowMultiple, _props_disabled = props.disabled, disabled = _props_disabled === void 0 ? false : _props_disabled, onDrop = props.onDrop, onDropAccepted = props.onDropAccepted, onDropRejected = props.onDropRejected, className = props.className, dragOverClassName = props.dragOverClassName, children = props.children;
+    var accept = normalizeDropZoneAccept(_accept);
+    var _useState = _sliced_to_array(useState(false), 2), isDraggingOver = _useState[0], setIsDraggingOver = _useState[1];
+    var handleDragOver = function(event) {
+        event.preventDefault();
+        event.stopPropagation();
+        if (!disabled) {
+            setIsDraggingOver(true);
+        }
+    };
+    var handleDragLeave = function(event) {
+        event.preventDefault();
+        event.stopPropagation();
+        setIsDraggingOver(false);
+    };
+    var handleDrop = function(event) {
+        event.preventDefault();
+        event.stopPropagation();
+        setIsDraggingOver(false);
+        if (disabled) return;
+        var droppedFiles = Array.from(event.dataTransfer.files);
+        if (allowMultiple === false) {
+            droppedFiles = droppedFiles.slice(0, 1);
+        }
+        var _partitionFilesByDropZoneAccept = partitionFilesByDropZoneAccept(droppedFiles, accept), acceptedFiles = _partitionFilesByDropZoneAccept.acceptedFiles, rejectedFiles = _partitionFilesByDropZoneAccept.rejectedFiles;
+        if (onDrop) {
+            onDrop(droppedFiles);
+        }
+        if (onDropAccepted && acceptedFiles.length > 0) {
+            onDropAccepted(acceptedFiles);
+        }
+        if (onDropRejected && rejectedFiles.length > 0) {
+            onDropRejected(rejectedFiles);
+        }
+    };
+    var dropTargetClassName = [
+        className,
+        isDraggingOver && dragOverClassName
+    ].filter(Boolean).join(" ");
+    return /*#__PURE__*/ _jsx("div", {
+        className: dropTargetClassName,
+        onDragOver: handleDragOver,
+        onDragLeave: handleDragLeave,
+        onDrop: handleDrop,
+        children: children
+    });
+};
+DropZone.DropTarget = DropTarget;
 var previewContainerStyles = tv({
     base: "flex flex-col",
     variants: {
@@ -439,11 +555,21 @@ var previewStyles = tv({
             return /*#__PURE__*/ _jsxs("div", {
                 className: "flex justify-between items-center gap-2",
                 children: [
-                    /*#__PURE__*/ _jsxs("div", {
+                    /*#__PURE__*/ _jsxs("div", _object_spread_props(_object_spread({
                         className: previewClasses,
                         onClick: onClick ? function() {
                             return onClick(file);
-                        } : undefined,
+                        } : undefined
+                    }, onClick ? {
+                        role: "button",
+                        tabIndex: 0,
+                        onKeyDown: function(e) {
+                            if (e.key === "Enter" || e.key === " ") {
+                                e.preventDefault();
+                                onClick(file);
+                            }
+                        }
+                    } : {}), {
                         children: [
                             /*#__PURE__*/ _jsx(FileThumbnail, {
                                 file: file
@@ -465,7 +591,7 @@ var previewStyles = tv({
                                 ]
                             })
                         ]
-                    }),
+                    })),
                     onRemove && /*#__PURE__*/ _jsx(Button, {
                         size: "small",
                         icon: CancelMajor,

package/dist/esm/components/EmptyState.js

@@ -4,12 +4,21 @@ import Image from "./Image.js";
 import Text from "./Text.js";
 import ProgressBar from "./ProgressBar.js";
 import { tv } from "tailwind-variants";
-var styles = tv({
-    base: "Litho-EmptyState py-16 px-4 flex flex-col items-center text-center gap-6"
-});
 /**
- * EmptyState component for displaying a structured layout with a title, description,
- * icon, and action buttons when no content is available.
+ * @component EmptyState
+ *
+ * @description A placeholder component displayed when a resource list, table, or page has no content, with a heading, description, and call-to-action.
+ *
+ * @usage
+ * - DO: Display when a resource list, table, or page has no data to show.
+ * - DON'T: Use for error states (use `Banner` instead).
+ *
+ * @accessibility
+ * - Ensure the heading and action buttons are descriptive; decorative images should have empty alt text.
+ *
+ * @alternative
+ * - If you need to show an error or warning message, use `Banner` instead.
+ * - If you need a loading state, use `SkeletonText`.
  *
  * @param {Object} props - The properties to customize the EmptyState component.
  * @param {string} [props.description] - Text description to display in the empty state.
@@ -33,7 +42,10 @@ var styles = tv({
  * @param {number} [props.progress] - Progress value to display in the empty state.
  *
  * @returns {JSX.Element} The rendered EmptyState component.
- */ function EmptyState() {
+ */ var styles = tv({
+    base: "Litho-EmptyState py-16 px-4 flex flex-col items-center text-center gap-6"
+});
+function EmptyState() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var description = props.description, icon = props.icon, iconSource = props.iconSource, primaryAction = props.primaryAction, secondaryAction = props.secondaryAction, title = props.title, _props_titleVariant = props.titleVariant, titleVariant = _props_titleVariant === void 0 ? "headingXl" : _props_titleVariant, _props_descriptionVariant = props.descriptionVariant, descriptionVariant = _props_descriptionVariant === void 0 ? "bodyLg" : _props_descriptionVariant, progress = props.progress, className = props.className;
     var classes = styles();

package/dist/esm/components/Filters.js

@@ -122,33 +122,21 @@ import TextField from "./TextField.js";
 import Tooltip from "./Tooltip.js";
 import { CancelSmallMinor, CaretDownMinor, DeleteMinor, HorizontalDotsMinor, PlusMinor, SearchMajor, ChevronLeftMinor, ChevronRightMinor } from "@shopify/polaris-icons";
 import { useDarkMode } from "./AppProvider.js";
-var styles = tv({
-    base: "Litho-Filters flex items-center overflow-x-auto",
-    variants: {
-        showTextField: {
-            true: "justify-between",
-            false: ""
-        }
-    }
-});
-var filterContainerStyles = tv({
-    base: "Litho-FiltersContainer flex flex-wrap gap-1.5 items-center",
-    variants: {
-        showTextField: {
-            true: "p-2",
-            false: ""
-        },
-        padded: {
-            true: "p-2",
-            false: ""
-        }
-    }
-});
 /**
- * Filters Component - A React component that manages filters for a given dataset.
- * Includes functionality for visible filters, more filters, and a query field.
+ * @component Filters
+ *
+ * @description A filter management component that renders active filter pills and controls for filtering table or resource list data.
+ *
+ * @usage
+ * - DO: Use for filtering content in tables or resource lists with removable filter pills.
+ * - DON'T: Use for general-purpose tabs (use Tabs).
+ *
+ * @accessibility
+ * - Filter pills are keyboard accessible with remove actions; ensure each filter has a descriptive label.
+ *
+ * @alternative
+ * - If you need general-purpose tabs, use `Tabs`. If you need a search input, use `TextField`.
  *
- * @component
  * @param {Object} props - The component props.
  * @param {Array<{
  *   key: string,
@@ -177,7 +165,29 @@ var filterContainerStyles = tv({
  * @param {boolean} [props.disableQueryField=false] - Whether the query text field is disabled.
  * @param {string} [props.className] - Additional class names for the component.
  * @returns {JSX.Element|null} The Filters component or null if no filters are available.
- */ function Filters(props) {
+ */ var styles = tv({
+    base: "Litho-Filters flex items-center overflow-x-auto",
+    variants: {
+        showTextField: {
+            true: "justify-between",
+            false: ""
+        }
+    }
+});
+var filterContainerStyles = tv({
+    base: "Litho-FiltersContainer flex flex-wrap gap-1.5 items-center",
+    variants: {
+        showTextField: {
+            true: "p-2",
+            false: ""
+        },
+        padded: {
+            true: "p-2",
+            false: ""
+        }
+    }
+});
+function Filters(props) {
     var _filters_filter;
     var _props_filters = props.filters, filters = _props_filters === void 0 ? [] : _props_filters, _props_appliedFilters = props.appliedFilters, appliedFilters = _props_appliedFilters === void 0 ? [] : _props_appliedFilters, onClearAll = props.onClearAll, _props_showTextField = props.showTextField, showTextField = _props_showTextField === void 0 ? false : _props_showTextField, _props_textFieldSubdued = props.textFieldSubdued, textFieldSubdued = _props_textFieldSubdued === void 0 ? false : _props_textFieldSubdued, _props_padded = props.padded, padded = _props_padded === void 0 ? false : _props_padded, queryValue = props.queryValue, onQueryChange = props.onQueryChange, onQueryBlur = props.onQueryBlur, onQueryFocus = props.onQueryFocus, onQueryClear = props.onQueryClear, _props_queryPlaceholder = props.queryPlaceholder, queryPlaceholder = _props_queryPlaceholder === void 0 ? "Search" : _props_queryPlaceholder, _props_ignorePromotedFiltersWhenRemoving = props.ignorePromotedFiltersWhenRemoving, ignorePromotedFiltersWhenRemoving = _props_ignorePromotedFiltersWhenRemoving === void 0 ? true : _props_ignorePromotedFiltersWhenRemoving, disableQueryField = props.disableQueryField, className = props.className;
     var classes = styles({
@@ -442,9 +452,11 @@ var pillTextStyles = tv({
     }
 });
 /**
- * Filters.Pill - A subcomponent for rendering filter pills.
+ * @component Filters.Pill
+ *
+ * @usage
+ * - DO: Display active filter values as removable chips.
  *
- * @component
  * @param {Object} props - The component props.
  * @param {string} props.label - The label of the filter pill.
  * @param {boolean} [props.applied=false] - Whether the pill represents an applied filter.
@@ -463,9 +475,19 @@ var pillTextStyles = tv({
     var textClasses = pillTextStyles({
         applied: applied
     });
-    var content = /*#__PURE__*/ _jsx("div", {
+    var content = /*#__PURE__*/ _jsx("div", _object_spread_props(_object_spread({
         className: classes,
-        onClick: onClick,
+        onClick: onClick
+    }, onClick && {
+        role: "button",
+        tabIndex: disabled ? -1 : 0,
+        onKeyDown: function(e) {
+            if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onClick();
+            }
+        }
+    }), {
         children: destructive ? /*#__PURE__*/ _jsx(Icon, {
             source: DeleteMinor,
             color: "subdued"
@@ -485,7 +507,7 @@ var pillTextStyles = tv({
                 })
             ]
         })
-    });
+    }));
     if (destructive) {
         return /*#__PURE__*/ _jsx(Tooltip, {
             content: "Remove filters",
@@ -518,9 +540,11 @@ var rightGradientStyles = tv({
     }
 });
 /**
- * Filters.Tabs - A subcomponent for managing tabs with scrollable functionality.
+ * @component Filters.Tabs
+ *
+ * @usage
+ * - DO: Group filter pills with tab-based categories.
  *
- * @component
  * @param {Object} props - The component props.
  * @param {Array} props.tabs - The tabs to display.
  * @param {Object} [props.insertBeforeTabs] - Tab to insert before the main tabs.
@@ -719,9 +743,11 @@ var tabActionIconStyles = tv({
     base: "opacity-80"
 });
 /**
- * Filters.Tab - A subcomponent for rendering individual tabs within the Filters.Tabs component.
+ * @component Filters.Tab
+ *
+ * @usage
+ * - DO: Use as an individual tab within Filters.Tabs.
  *
- * @component
  * @param {Object} props - The component props.
  * @param {React.ReactNode} [props.icon=HorizontalDotsMinor] - The icon displayed in the tab (default is a horizontal dots icon).
  * @param {boolean} [props.selected=false] - Whether the tab is currently selected.
@@ -749,6 +775,15 @@ var tabActionIconStyles = tv({
     return /*#__PURE__*/ _jsx("div", {
         className: classes,
         onClick: onClick,
+        role: "tab",
+        tabIndex: 0,
+        "aria-selected": selected,
+        onKeyDown: function(e) {
+            if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onClick === null || onClick === void 0 ? void 0 : onClick();
+            }
+        },
         children: /*#__PURE__*/ _jsxs("div", {
             className: "flex flex-col items-start justify-start",
             children: [
@@ -763,7 +798,20 @@ var tabActionIconStyles = tv({
                         }),
                         onAction && /*#__PURE__*/ _jsxs("div", {
                             className: actionClasses,
-                            onClick: onAction,
+                            onClick: function(e) {
+                                e.stopPropagation();
+                                onAction(e);
+                            },
+                            role: "button",
+                            tabIndex: 0,
+                            "aria-label": tooltip,
+                            onKeyDown: function(e) {
+                                if (e.key === "Enter" || e.key === " ") {
+                                    e.preventDefault();
+                                    e.stopPropagation();
+                                    onAction(e);
+                                }
+                            },
                             children: [
                                 !interactive && /*#__PURE__*/ _jsx("div", {
                                     className: "min-h-full min-w-2 bg-linear-to-l from-surface-highest to-transparent"

package/dist/esm/components/FooterHelp.js

@@ -2,11 +2,21 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import Icon from "./Icon.js";
 import { CircleInformationMajor } from "@shopify/polaris-icons";
 /**
- * Renders a `FooterHelp` component, which provides additional information
- * or guidance to users, typically displayed at the bottom of a page. The component
- * centers its content within a rounded, styled box that includes an icon and customizable text.
+ * @component FooterHelp
+ *
+ * @description A bottom-of-page help component that displays a link to additional resources or documentation.
+ *
+ * @usage
+ * - DO: Place at the bottom of a page to provide contextual help links.
+ * - DON'T: Use in card footers or inline (use `Link` instead).
+ *
+ * @accessibility
+ * - Renders help text with a link; ensure the link text is descriptive for screen readers.
+ *
+ * @alternative
+ * - If you need an inline help link, use `Link` instead.
+ * - If you need contextual tips, use `Tip`.
  *
- * @component
  * @param {Object} [props] - The props for the FooterHelp component.
  * @param {React.ReactNode} [props.children] - The content to display next to the information icon.
  * This is typically a text string or any valid React node.

package/dist/esm/components/Form.js

@@ -1,7 +1,18 @@
 /**
- * A reusable Form component that provides a structured HTML form with customizable attributes and submission handling.
+ * @component Form
+ *
+ * @description A form wrapper that handles submit events and integrates with the contextual save bar for unsaved changes.
+ *
+ * @usage
+ * - DO: Wrap form fields to handle submission with Enter key and prevent default behavior.
+ * - DON'T: Use for non-form content.
+ *
+ * @accessibility
+ * - Renders a semantic `<form>` element; screen readers identify it as a form region.
+ *
+ * @alternative
+ * - If you need to manage form save state globally, use `ContextualSaveBar` alongside Form.
  *
- * @component
  * @param {Object} [props={}] - The properties passed to the component.
  * @param {string} [props.acceptCharset] - The character encoding that the form accepts.
  * @param {string} [props.action] - The URL where the form data should be submitted.