@heymantle/litho 0.0.15 → 0.0.16

package/dist/esm/components/ColorField.js

@@ -7,6 +7,19 @@ function _array_like_to_array(arr, len) {
 function _array_with_holes(arr) {
     if (Array.isArray(arr)) return 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_limit(arr, i) {
     var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
     if (_i == null) return;
@@ -34,6 +47,21 @@ function _iterable_to_array_limit(arr, i) {
 function _non_iterable_rest() {
     throw new TypeError("Invalid attempt to destructure 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 _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();
 }
@@ -45,28 +73,27 @@ function _unsupported_iterable_to_array(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 }
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from "react";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useRef, useState } from "react";
 import Sketch from "@uiw/react-color-sketch";
 import { tv } from "tailwind-variants";
 import Text from "./Text.js";
-var colorContainer = tv({
-    base: "Litho-ColorField relative flex items-center gap-2 cursor-pointer px-1 py-1 rounded-md w-full-plus-2 -left-1",
-    variants: {
-        hoverable: {
-            true: "hover"
-        }
-    }
-});
-var colorCell = tv({
-    base: "w-8 h-8 min-w-8 min-h-8 rounded-md border border-tint-5"
-});
+import TextField from "./TextField.js";
 /**
- * ColorField component provides a UI for selecting colors using the SketchPicker.
- * It displays the currently selected color and allows toggling a color picker popover.
- * Useful for choosing solid colors in forms or design tools.
+ * @component ColorField
+ *
+ * @description A color picker input that displays a swatch preview and a text field for entering hex color values.
+ *
+ * @usage
+ * - DO: Use for selecting colors in theme or design settings.
+ * - DON'T: Use for text input (use TextField).
+ *
+ * @accessibility
+ * - Ensure the color input has a descriptive label; provide text representation of selected color for screen readers.
+ *
+ * @alternative
+ * - If you need a text input, use `TextField`. If you need a select from predefined options, use `Select`.
  *
- * @component
  * @example
  * <ColorField
  *   label="Primary Color"
@@ -77,23 +104,139 @@ var colorCell = tv({
  *   presetColors={['#ff0000', '#00ff00', '#0000ff']}
  * />
  *
+ * @example
+ * // Textfield variant with inline editing and color swatch
+ * <ColorField
+ *   variant="textfield"
+ *   label="Brand Color"
+ *   name="brand"
+ *   value="#ff0000"
+ *   onChange={(newColor) => setColor(newColor)}
+ *   placeholder="#000000"
+ * />
+ *
  * @param {Object} props - Component props
+ * @param {('default'|'textfield')} [props.variant='default'] - Visual variant; "textfield" renders an editable TextField with color swatch
  * @param {string} props.label - The label displayed above the color value
  * @param {string} props.name - The name associated with the color field, used as a key
  * @param {string} props.value - The currently selected color value; can be a hex string or CSS variable
  * @param {function} props.onChange - Callback function that receives the new color value when changed
  * @param {number} [props.zIndexOverride] - Optional z-index value to override the default popover z-index
  * @param {string[]} [props.presetColors=[]] - Optional array of preset colors shown in the picker
+ * @param {string} [props.placeholder] - Placeholder text (textfield variant only)
+ * @param {string} [props.helpText] - Help text below the field (textfield variant only)
+ * @param {string} [props.error] - Error message (textfield variant only)
+ * @param {boolean} [props.disabled] - Whether the field is disabled (textfield variant only)
  *
  * @returns {JSX.Element} A color picker field with label and current value preview
- */ var ColorField = function(param) {
-    var label = param.label, name = param.name, _value = param.value, onChange = param.onChange, zIndexOverride = param.zIndexOverride, _param_presetColors = param.presetColors, presetColors = _param_presetColors === void 0 ? [] : _param_presetColors;
-    var value = _value.startsWith("var(--") ? getComputedStyle(document.documentElement).getPropertyValue(_value.replace("var(", "").replace(")", "")).trim() : _value;
+ */ var colorContainer = tv({
+    base: "Litho-ColorField relative flex items-center gap-2 cursor-pointer px-1 py-1 rounded-md w-full-plus-2 -left-1",
+    variants: {
+        hoverable: {
+            true: "hover"
+        }
+    }
+});
+var colorCell = tv({
+    base: "w-8 h-8 min-w-8 min-h-8 rounded-md border border-tint-5"
+});
+var ColorField = function(param) {
+    var label = param.label, name = param.name, _value = param.value, onChange = param.onChange, zIndexOverride = param.zIndexOverride, _param_presetColors = param.presetColors, presetColors = _param_presetColors === void 0 ? [] : _param_presetColors, _param_variant = param.variant, variant = _param_variant === void 0 ? "default" : _param_variant, placeholder = param.placeholder, helpText = param.helpText, error = param.error, disabled = param.disabled;
+    var value = (_value === null || _value === void 0 ? void 0 : _value.startsWith("var(--")) ? getComputedStyle(document.documentElement).getPropertyValue(_value.replace("var(", "").replace(")", "")).trim() : _value;
+    var containerRef = useRef(null);
     var _useState = _sliced_to_array(useState(false), 2), displayColorPicker = _useState[0], setDisplayColorPicker = _useState[1];
+    var _useState1 = _sliced_to_array(useState({
+        top: 0,
+        left: 0
+    }), 2), popoverPosition = _useState1[0], setPopoverPosition = _useState1[1];
     var toggleDisplayColorPicker = function() {
-        return setDisplayColorPicker(!displayColorPicker);
+        if (!displayColorPicker && containerRef.current) {
+            var rect = containerRef.current.getBoundingClientRect();
+            setPopoverPosition({
+                top: rect.top,
+                left: rect.left
+            });
+        }
+        setDisplayColorPicker(!displayColorPicker);
     };
+    var colorPickerPopover = /*#__PURE__*/ _jsxs(_Fragment, {
+        children: [
+            displayColorPicker && /*#__PURE__*/ _jsx("div", {
+                className: "Litho-ColorField__Activator fixed inset-0",
+                onClick: toggleDisplayColorPicker
+            }),
+            displayColorPicker && /*#__PURE__*/ _jsx("div", {
+                className: "Litho-ColorField__Popover fixed",
+                style: _object_spread({
+                    top: popoverPosition.top,
+                    left: popoverPosition.left
+                }, zIndexOverride ? {
+                    zIndex: zIndexOverride
+                } : {}),
+                children: /*#__PURE__*/ _jsx(Sketch, {
+                    color: value,
+                    onChange: function(param) {
+                        var hex = param.hex;
+                        return onChange(hex);
+                    },
+                    disableAlpha: true,
+                    presetColors: presetColors
+                }, name)
+            })
+        ]
+    });
+    if (variant === "textfield") {
+        var openPicker = function() {
+            if (!displayColorPicker && containerRef.current) {
+                var rect = containerRef.current.getBoundingClientRect();
+                setPopoverPosition({
+                    top: rect.bottom + 4,
+                    left: rect.left
+                });
+            }
+            setDisplayColorPicker(true);
+        };
+        return /*#__PURE__*/ _jsxs("div", {
+            ref: containerRef,
+            className: "Litho-ColorField",
+            children: [
+                /*#__PURE__*/ _jsx(TextField, {
+                    label: label,
+                    name: name,
+                    value: value ? value.toUpperCase() : "",
+                    onChange: onChange,
+                    onFocus: openPicker,
+                    placeholder: placeholder,
+                    helpText: helpText,
+                    error: error,
+                    disabled: disabled,
+                    suffix: /*#__PURE__*/ _jsx("span", {
+                        className: "relative left-1.5 block w-5 h-5 rounded border border-tint-5 cursor-pointer pointer-events-auto",
+                        style: {
+                            backgroundColor: value
+                        },
+                        onClick: function(e) {
+                            e.stopPropagation();
+                            toggleDisplayColorPicker();
+                        },
+                        role: "button",
+                        tabIndex: 0,
+                        "aria-label": "Open color picker",
+                        onKeyDown: function(e) {
+                            if (e.key === "Enter" || e.key === " ") {
+                                e.preventDefault();
+                                e.stopPropagation();
+                                toggleDisplayColorPicker();
+                            }
+                        }
+                    })
+                }),
+                colorPickerPopover
+            ]
+        });
+    }
     return /*#__PURE__*/ _jsxs("div", {
+        ref: containerRef,
         className: colorContainer({
             hoverable: true
         }),
@@ -124,25 +267,7 @@ var colorCell = tv({
                     })
                 ]
             }),
-            displayColorPicker && /*#__PURE__*/ _jsx("div", {
-                className: "Litho-ColorField__Activator fixed inset-0",
-                onClick: toggleDisplayColorPicker
-            }),
-            displayColorPicker && /*#__PURE__*/ _jsx("div", {
-                className: "Litho-ColorField__Popover absolute z-10 left-0 top-0",
-                style: zIndexOverride ? {
-                    zIndex: zIndexOverride
-                } : {},
-                children: /*#__PURE__*/ _jsx(Sketch, {
-                    color: value,
-                    onChange: function(param) {
-                        var hex = param.hex;
-                        return onChange(hex);
-                    },
-                    disableAlpha: true,
-                    presetColors: presetColors
-                }, name)
-            })
+            colorPickerPopover
         ]
     });
 };

package/dist/esm/components/ContextualSaveBar.js

@@ -2,14 +2,21 @@
 import { useContext, useEffect } from "react";
 import { FormContext } from "./AppProvider.js";
 /**
- * ContextualSaveBar Component
+ * @component ContextualSaveBar
  *
- * This component manages and displays a global contextual save bar with custom save and discard actions.
- * It uses the `FormContext` to control the visibility and configuration of the save bar.
- * When mounted, it sets the provided message, save action, and discard action.
- * When unmounted, it cleans up by resetting these values.
+ * @description A floating save bar that appears when a form has unsaved changes, providing save and discard actions.
+ *
+ * @usage
+ * - DO: Display at the top of a page when a form has unsaved changes with save/discard actions.
+ * - DON'T: Use inside a modal (use modal's own actions).
+ *
+ * @accessibility
+ * - Save bar should be keyboard accessible; ensure save and discard buttons have clear labels.
+ *
+ * @alternative
+ * - If you need a save bar integrated with the Frame layout, use `FrameSaveBar`.
+ * - If you need form-level submit, use `Form`.
  *
- * @component
  * @param {Object} props - Component properties.
  * @param {Object} [props.saveAction] - The action for the "Save" button. Contains `onAction`, `loading`, `accessibilityLabel`, and `disabled`.
  * @param {Object} [props.discardAction] - The action for the "Discard" button. Contains `onAction`, `loading`, `accessibilityLabel`, and `disabled`.

package/dist/esm/components/DatePicker.js

@@ -127,7 +127,52 @@ import TimePicker from "./TimePicker.js";
 import { CalendarMinor, CalendarTimeMinor, ChevronLeftMinor, ChevronRightMinor } from "@shopify/polaris-icons";
 import { enUS } from "date-fns/locale";
 import { NOW_TODAY, DAY_FORMAT, DAY_TIME_FORMAT, TIME_FORMAT, MONTHS, RANGE_PRESETS, HOURLY_RANGE_PRESETS, DATE_LOCALE_MAP, isValidDate } from "../utilities/dates.js";
-var calendarStyles = tv({
+/**
+ * @component DatePicker
+ *
+ * @description A date selection input with calendar popup, powered by react-datepicker, supporting single date and date range selection.
+ *
+ * @usage
+ * - DO: Use for selecting dates with a visual calendar interface.
+ * - DON'T: Use for time-only selection (use TimePicker).
+ *
+ * @accessibility
+ * - Supports keyboard navigation within the calendar; ensure the input has a descriptive label.
+ *
+ * @alternative
+ * - If you need time selection, use `TimePicker`. If you need a plain text date input, use `TextField` with date validation.
+ *
+ * @param {Object} props - Component properties.
+ * @param {string} [props.label] - Label for the DatePicker.
+ * @param {Object|null} [props.labelAction] - Action button for the label.
+ * @param {function} [props.onBlur] - Callback function for when the field loses focus.
+ * @param {string} [props.placeholder="Select date..."] - Placeholder text.
+ * @param {string} [props.displayFormat] - Date format for displaying the value.
+ * @param {string} [props.helpText] - Help text displayed under the field.
+ * @param {JSX.Element|null} [props.suffix=null] - Icon or text displayed at the end of the input.
+ * @param {boolean} [props.isClearable=false] - Whether the input can be cleared.
+ * @param {string|null} [props.tooltip] - Tooltip text for the field.
+ * @param {string} [props.locale="en-US"] - Locale used for formatting.
+ * @param {Object|string|Date|null} [props.value] - Current value of the DatePicker.
+ * @param {boolean} [props.allowRange=false] - Whether date range selection is enabled.
+ * @param {JSX.Element|null} [props.activator] - Custom activator for the popover.
+ * @param {Date|string|null} [props.disableDatesAfter] - Dates after this value are disabled.
+ * @param {Date|string|null} [props.disableDatesBefore] - Dates before this value are disabled.
+ * @param {function} [props.onChange] - Callback function called when the date changes.
+ * @param {boolean} [props.multiMonth=false] - Whether multiple months are shown.
+ * @param {boolean} [props.disabled=false] - Whether the DatePicker is disabled.
+ * @param {boolean} [props.showTimePicker=false] - Whether a time picker is displayed.
+ * @param {boolean} [props.autoFocus=false] - Whether the input is focused automatically.
+ * @param {Date|null} [props.maxDate] - Maximum selectable date.
+ * @param {Date|null} [props.minDate] - Minimum selectable date.
+ * @param {boolean} [props.inline=false] - Whether the calendar is displayed inline.
+ * @param {string} [props.preferredAlignment="left"] - Alignment of the popover.
+ * @param {string} [props.preferredPosition="below"] - Position of the popover.
+ * @param {boolean} [props.includeHourlyPresets=false] - Whether hourly (last 30 minutes, last hour) presets are included.
+ * @param {Array} [props.customPresets=[]] - Custom presets to include.
+ * @param {JSX.Element|null} [props.footer] - An optional footer component to display at the bottom of the DatePicker.
+ * @returns {JSX.Element} The rendered DatePicker component.
+ */ var calendarStyles = tv({
     base: "Litho-DatePicker__Calendar relative"
 });
 var dayStyles = tv({
@@ -227,8 +272,7 @@ var getDateRange = function(param) {
     var start = dayjs(startDate);
     var end = dayjs(endDate);
     return _to_consumable_array(RANGE_PRESETS).concat(_to_consumable_array(HOURLY_RANGE_PRESETS)).find(function(preset) {
-        var _preset_value = preset.value, presetStart = _preset_value.start, presetEnd = _preset_value.end;
-        return start.isSame(presetStart, "day") && end.isSame(presetEnd, "day") && dateRange === preset.id;
+        return dateRange === preset.id;
     }) || {
         id: "custom",
         value: {
@@ -237,40 +281,7 @@ var getDateRange = function(param) {
         }
     };
 };
-/**
- * DatePicker component for selecting dates and date ranges.
- *
- * @param {Object} props - Component properties.
- * @param {string} [props.label] - Label for the DatePicker.
- * @param {Object|null} [props.labelAction] - Action button for the label.
- * @param {function} [props.onBlur] - Callback function for when the field loses focus.
- * @param {string} [props.placeholder="Select date..."] - Placeholder text.
- * @param {string} [props.displayFormat] - Date format for displaying the value.
- * @param {string} [props.helpText] - Help text displayed under the field.
- * @param {JSX.Element|null} [props.suffix=null] - Icon or text displayed at the end of the input.
- * @param {boolean} [props.isClearable=false] - Whether the input can be cleared.
- * @param {string|null} [props.tooltip] - Tooltip text for the field.
- * @param {string} [props.locale="en-US"] - Locale used for formatting.
- * @param {Object|string|Date|null} [props.value] - Current value of the DatePicker.
- * @param {boolean} [props.allowRange=false] - Whether date range selection is enabled.
- * @param {JSX.Element|null} [props.activator] - Custom activator for the popover.
- * @param {Date|string|null} [props.disableDatesAfter] - Dates after this value are disabled.
- * @param {Date|string|null} [props.disableDatesBefore] - Dates before this value are disabled.
- * @param {function} [props.onChange] - Callback function called when the date changes.
- * @param {boolean} [props.multiMonth=false] - Whether multiple months are shown.
- * @param {boolean} [props.disabled=false] - Whether the DatePicker is disabled.
- * @param {boolean} [props.showTimePicker=false] - Whether a time picker is displayed.
- * @param {boolean} [props.autoFocus=false] - Whether the input is focused automatically.
- * @param {Date|null} [props.maxDate] - Maximum selectable date.
- * @param {Date|null} [props.minDate] - Minimum selectable date.
- * @param {boolean} [props.inline=false] - Whether the calendar is displayed inline.
- * @param {string} [props.preferredAlignment="left"] - Alignment of the popover.
- * @param {string} [props.preferredPosition="below"] - Position of the popover.
- * @param {boolean} [props.includeHourlyPresets=false] - Whether hourly (last 30 minutes, last hour) presets are included.
- * @param {Array} [props.customPresets=[]] - Custom presets to include.
- * @param {JSX.Element|null} [props.footer] - An optional footer component to display at the bottom of the DatePicker.
- * @returns {JSX.Element} The rendered DatePicker component.
- */ function DatePicker() {
+function DatePicker() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var label = props.label, _props_labelAction = props.labelAction, labelAction = _props_labelAction === void 0 ? null : _props_labelAction, onBlur = props.onBlur, _props_placeholder = props.placeholder, placeholder = _props_placeholder === void 0 ? "Select date..." : _props_placeholder, _props_displayFormat = props.displayFormat, displayFormat = _props_displayFormat === void 0 ? props.showTimePicker && !props.allowRange ? DAY_TIME_FORMAT : DAY_FORMAT : _props_displayFormat, helpText = props.helpText, _props_suffix = props.suffix, suffix = _props_suffix === void 0 ? null : _props_suffix, isClearable = props.isClearable, tooltip = props.tooltip, tmp = props.locale, _locale = tmp === void 0 ? "en-US" : tmp, _value = props.value, _props_allowRange = props.allowRange, allowRange = _props_allowRange === void 0 ? false : _props_allowRange, activator = props.activator, disableDatesAfter = props.disableDatesAfter, disableDatesBefore = props.disableDatesBefore, onChange = props.onChange, multiMonth = props.multiMonth, disabled = props.disabled, showTimePicker = props.showTimePicker, autoFocus = props.autoFocus, _maxDate = props.maxDate, _minDate = props.minDate, _props_inline = props.inline, inline = _props_inline === void 0 ? false : _props_inline, _props_closeAfterDateSelection = props.closeAfterDateSelection, closeAfterDateSelection = _props_closeAfterDateSelection === void 0 ? true : _props_closeAfterDateSelection, _props_preferredAlignment = props.preferredAlignment, preferredAlignment = _props_preferredAlignment === void 0 ? "left" : _props_preferredAlignment, _props_preferredPosition = props.preferredPosition, preferredPosition = _props_preferredPosition === void 0 ? "below" : _props_preferredPosition, _props_includeHourlyPresets = props.includeHourlyPresets, includeHourlyPresets = _props_includeHourlyPresets === void 0 ? false : _props_includeHourlyPresets, _props_customPresets = props.customPresets, customPresets = _props_customPresets === void 0 ? [] : _props_customPresets, footer = props.footer;
     var _useState = _sliced_to_array(useState(false), 2), showPopover = _useState[0], setShowPopover = _useState[1];

package/dist/esm/components/Disclosure.js

@@ -1,6 +1,39 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
+/**
+ * @component Disclosure
+ *
+ * @description A styled container with a vertical border indicator, used to visually denote expandable or nested content sections.
+ *
+ * @usage
+ * - DO: Use to wrap expandable content sections with a consistent bordered container style.
+ * - DON'T: Use as a generic container; use `Box` or `Card` for non-disclosure content.
+ *
+ * @accessibility
+ * - Disclosure is a styled container only; the toggle mechanism must be implemented separately with proper `aria-expanded` attributes.
+ * - Pair with `Collapsible` for animated show/hide behavior with accessible state management.
+ *
+ * @alternative
+ * - If you need animated expand/collapse behavior, wrap content in `Collapsible` instead.
+ * - If you need a general-purpose container, use `Card` or `Box` instead.
+ *
+ * @param {Object} props - Component properties.
+ * @param {React.ReactNode} props.children - The content to display within the disclosure.
+ * @param {string} [props.className] - Additional CSS classes to apply to the disclosure.
+ * @returns {JSX.Element} A styled `<div>` element serving as a disclosure container.
+ *
+ * @example
+ * // Renders disclosure content
+ * <Disclosure>
+ *   <Text>This is disclosure content</Text>
+ * </Disclosure>
+ *
+ * @example
+ * // Renders disclosure content with additional classes
+ * <Disclosure className="mt-4">
+ *   <Text>This is disclosure content with margin</Text>
+ * </Disclosure>
+ */ var styles = tv({
     base: "Litho-Disclosure relative",
     variants: {
         flush: {
@@ -24,27 +57,7 @@ var borderStyles = tv({
         flush: false
     }
 });
-/**
- * Renders a Disclosure component that displays content with disclosure styling.
- *
- * @component
- * @param {Object} props - Component properties.
- * @param {React.ReactNode} props.children - The content to display within the disclosure.
- * @param {string} [props.className] - Additional CSS classes to apply to the disclosure.
- * @returns {JSX.Element} A styled `<div>` element serving as a disclosure container.
- *
- * @example
- * // Renders disclosure content
- * <Disclosure>
- *   <Text>This is disclosure content</Text>
- * </Disclosure>
- *
- * @example
- * // Renders disclosure content with additional classes
- * <Disclosure className="mt-4">
- *   <Text>This is disclosure content with margin</Text>
- * </Disclosure>
- */ function Disclosure() {
+function Disclosure() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, className = props.className, _props_flush = props.flush, flush = _props_flush === void 0 ? false : _props_flush;
     var classes = styles({

package/dist/esm/components/Divider.js

@@ -1,23 +1,26 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
-    base: "Litho-Divider h-px",
-    variants: {
-        color: {
-            default: "bg-edge-default",
-            subdued: "bg-edge-subdued"
-        }
-    },
-    defaultVariants: {
-        color: "default"
-    }
-});
+import Text from "./Text.js";
 /**
- * Renders a divider element with customizable color variants.
+ * @component Divider
+ *
+ * @description A visual separator that creates a horizontal line between content sections, with optional label text and color variants.
+ *
+ * @usage
+ * - DO: Use to visually separate sections of content within a page or card.
+ * - DON'T: Use as a decorative border; prefer CSS border utilities for non-semantic separation.
+ *
+ * @accessibility
+ * - Renders as a `<div>` with a visual line; does not convey semantic meaning to screen readers.
+ * - When using with a label, ensure the label text provides meaningful context for sighted users.
+ *
+ * @alternative
+ * - If you need spacing without a visible line, use `Stack` with gap instead.
  *
- * @component
  * @param {Object} props - Component properties.
  * @param {'default' | 'subdued'} [props.color='default'] - The color variant to apply to the divider.
+ * @param {string} [props.label] - Optional label to display in the divider.
+ * @param {'left' | 'center' | 'right'} [props.labelAlignment='center'] - The alignment of the label.
  * @returns {JSX.Element} A styled `<div>` element serving as a divider.
  *
  * @example
@@ -27,15 +30,70 @@ var styles = tv({
  * @example
  * // Renders a subdued color divider
  * <Divider color="subdued" />
- */ function Divider() {
+ *
+ * @example
+ * // Renders a divider with a centered label
+ * <Divider label="Or continue with" />
+ */ var styles = tv({
+    base: "Litho-Divider h-px",
+    variants: {
+        color: {
+            default: "bg-edge-default",
+            subdued: "bg-edge-subdued"
+        }
+    },
+    defaultVariants: {
+        color: "default",
+        labelAlignment: "center"
+    }
+});
+var containerStyles = tv({
+    base: "Litho-Divider flex items-center gap-3"
+});
+function Divider() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
-    var color = props.color;
-    var classes = styles({
+    var color = props.color, label = props.label, _props_labelAlignment = props.labelAlignment, labelAlignment = _props_labelAlignment === void 0 ? "center" : _props_labelAlignment, className = props.className;
+    var lineClasses = styles({
         color: color
     });
+    var containerClasses = containerStyles();
+    if (label) {
+        if (labelAlignment === "left") {
+            return /*#__PURE__*/ _jsxs("div", {
+                className: "".concat(containerClasses).concat(className ? " ".concat(className) : ""),
+                children: [
+                    /*#__PURE__*/ _jsx(Text, {
+                        as: "span",
+                        variant: "bodySm",
+                        color: "subdued",
+                        children: label
+                    }),
+                    /*#__PURE__*/ _jsx("div", {
+                        className: "".concat(lineClasses, " flex-1")
+                    })
+                ]
+            });
+        }
+        return /*#__PURE__*/ _jsxs("div", {
+            className: "".concat(containerClasses).concat(className ? " ".concat(className) : ""),
+            children: [
+                /*#__PURE__*/ _jsx("div", {
+                    className: "".concat(lineClasses, " flex-1")
+                }),
+                /*#__PURE__*/ _jsx(Text, {
+                    as: "span",
+                    variant: "bodySm",
+                    color: "subdued",
+                    children: label
+                }),
+                /*#__PURE__*/ _jsx("div", {
+                    className: "".concat(lineClasses, " flex-1")
+                })
+            ]
+        });
+    }
     return /*#__PURE__*/ _jsx("div", {
-        className: classes
+        className: lineClasses
     });
 }
-;
 export default Divider;