@heymantle/litho 0.0.14 → 0.0.16

package/dist/cjs/components/Image.js

@@ -107,28 +107,23 @@ function _object_without_properties_loose(source, excluded) {
     }
     return target;
 }
-var styles = (0, _tailwindvariants.tv)({
-    base: "Litho-Image",
-    variants: {
-        borderRadius: {
-            default: "",
-            none: "rounded-none",
-            xs: "rounded-xs",
-            sm: "rounded-sm",
-            md: "rounded-md",
-            lg: "rounded-lg",
-            full: "rounded-full",
-            max: "rounded-max"
-        },
-        rounded: {
-            true: "rounded-md"
-        }
-    }
-});
 /**
- * Image component that renders an image with optional styling and behavior.
+ * @component Image
+ *
+ * @description Displays a responsive content image with optional rounded corners, srcset support, and load callbacks.
+ *
+ * @usage
+ * - DO: Use for content images with descriptive `alt` text and optional responsive `sourceSet`.
+ * - DON'T: Use for small avatars or product thumbnails; use `Thumbnail` for those cases.
+ *
+ * @accessibility
+ * - Always provide meaningful `alt` text describing the image content; use empty string for purely decorative images.
+ * - When using `sourceSet`, ensure all sources serve the same visual content at different resolutions.
+ *
+ * @alternative
+ * - If you need a small, fixed-size preview image, use `Thumbnail` instead.
+ * - If you need an icon graphic, use `Icon` with a Polaris icon source instead.
  *
- * @component
  * @param {Object} props - Properties passed to the Image component.
  * @param {string} [props.alt] - Alternative text for the image.
  * @param {Array<{source: string, descriptor: string}>} [props.sourceSet] - Array of image sources and descriptors for responsive images.
@@ -139,7 +134,7 @@ var styles = (0, _tailwindvariants.tv)({
  * @param {string} [props.className] - Additional classes to apply to the image.
  * @param {('default'|'none'|'xs'|'sm'|'md'|'lg'|'full'|'max')} [props.borderRadius='default'] - The border radius variant for the image.
  * @param {Object} [rest] - Any additional props passed to the underlying `<img>` element.
- * 
+ *
  * @example
  * <Image
  *   alt="Sample Image"
@@ -154,7 +149,25 @@ var styles = (0, _tailwindvariants.tv)({
  * />
  *
  * @returns {JSX.Element} A styled image component with optional responsive support.
- */ function Image() {
+ */ var styles = (0, _tailwindvariants.tv)({
+    base: "Litho-Image",
+    variants: {
+        borderRadius: {
+            default: "",
+            none: "rounded-none",
+            xs: "rounded-xs",
+            sm: "rounded-sm",
+            md: "rounded-md",
+            lg: "rounded-lg",
+            full: "rounded-full",
+            max: "rounded-max"
+        },
+        rounded: {
+            true: "rounded-md"
+        }
+    }
+});
+function Image() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var alt = props.alt, sourceSet = props.sourceSet, source = props.source, crossOrigin = props.crossOrigin, onLoad = props.onLoad, rounded = props.rounded, className = props.className, borderRadius = props.borderRadius, rest = _object_without_properties(props, [
         "alt",

package/dist/cjs/components/InlineError.js

@@ -17,25 +17,34 @@ function _interop_require_default(obj) {
         default: obj
     };
 }
-var styles = (0, _tailwindvariants.tv)({
-    base: "Litho-InlineError flex items-start justify-start gap-2"
-});
 /**
- * InlineError Component
- * 
- * Displays an inline error message with an icon, useful for indicating errors next to form fields.
+ * @component InlineError
+ *
+ * @description A small error message component displayed inline below a form field to indicate validation errors.
+ *
+ * @usage
+ * - DO: Display field-level validation errors below or near form inputs.
+ * - DON'T: Use for page-level alerts (use Banner).
+ *
+ * @accessibility
+ * - Error text should be associated with the input via `aria-describedby` for screen reader announcement.
+ *
+ * @alternative
+ * - If you need a page-level error message, use `Banner` with status="critical". If you need a tooltip hint, use `Tooltip`.
  *
- * @component
  * @param {Object} props - Component properties.
  * @param {string} props.message - The error message to display.
  * @param {string} props.fieldID - The ID of the field this error is associated with, used to generate an accessible ID for the error element.
  *
  * @returns {JSX.Element} A styled inline error message with an icon.
- * 
+ *
  * @example
  * <InlineError message="This field is required" fieldID="username" />
- * 
- */ function InlineError() {
+ *
+ */ var styles = (0, _tailwindvariants.tv)({
+    base: "Litho-InlineError flex items-start justify-start gap-2"
+});
+function InlineError() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var message = props.message, fieldID = props.fieldID, _props_icon = props.icon, icon = _props_icon === void 0 ? _polarisicons.CircleAlertMajor : _props_icon;
     var classes = styles();

package/dist/cjs/components/Label.js

@@ -17,19 +17,20 @@ function _interop_require_default(obj) {
         default: obj
     };
 }
-var styles = (0, _tailwindvariants.tv)({
-    base: "Litho-Label flex items-center gap-1 text-highest",
-    variants: {
-        hidden: {
-            true: "sr-only"
-        }
-    }
-});
 /**
- * Label component
+ * @component Label
+ *
+ * @description A form label component that renders a styled label element associated with a form input.
+ *
+ * @usage
+ * - DO: Use to label form inputs when building custom form controls.
+ * - DON'T: Use for standalone text (use Text).
  *
- * This component renders a customizable label element with optional required indicator styling.
- * It uses `tailwind-variants` to apply base styles and accepts various props for customization.
+ * @accessibility
+ * - Renders a `<label>` element with `htmlFor` association to its input; critical for screen reader input identification.
+ *
+ * @alternative
+ * - If you need standalone text, use `Text`. Most form components (TextField, Select) include labels built-in.
  *
  * @param {Object} props - The properties passed to the component.
  * @param {React.ReactNode} props.children - The content to be displayed within the label.
@@ -41,7 +42,15 @@ var styles = (0, _tailwindvariants.tv)({
  * @param {Object} [props.rest] - Additional props to be spread onto the label element.
  *
  * @returns {JSX.Element} The rendered label component with optional required indicator.
- */ function Label() {
+ */ var styles = (0, _tailwindvariants.tv)({
+    base: "Litho-Label flex items-center gap-1 text-highest",
+    variants: {
+        hidden: {
+            true: "sr-only"
+        }
+    }
+});
+function Label() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var tmp = props.color, _color = tmp === void 0 ? "subdued" : tmp, children = props.children, _props_variant = props.variant, variant = _props_variant === void 0 ? "bodyMd" : _props_variant, _props_fontWeight = props.fontWeight, fontWeight = _props_fontWeight === void 0 ? "normal" : _props_fontWeight, id = props.id, hidden = props.hidden, className = props.className, requiredIndicator = props.requiredIndicator, _props_as = props.as, as = _props_as === void 0 ? "label" : _props_as, disabled = props.disabled, tooltip = props.tooltip;
     var classes = styles({

package/dist/cjs/components/Layout.js

@@ -71,7 +71,7 @@ function _interop_require_wildcard(obj, nodeInterop) {
 }
 var LayoutContext = /*#__PURE__*/ (0, _react.createContext)();
 var styles = (0, _tailwindvariants.tv)({
-    base: "Litho-Layout flex gap-4 w-full max-w-full",
+    base: "Litho-Layout flex w-full max-w-full",
     variants: {
         hasSidebarSection: {
             true: ""
@@ -79,18 +79,36 @@ var styles = (0, _tailwindvariants.tv)({
         reverseOnMobile: {
             true: "flex-col-reverse @lg:flex-row",
             false: "flex-col"
+        },
+        scrollSectionsIndependently: {
+            true: "pl-4 @lg:pl-5",
+            false: ""
         }
     },
     compoundVariants: [
         {
             hasSidebarSection: true,
             embedded: false,
-            className: "@lg:flex-row @lg:gap-5"
+            scrollSectionsIndependently: false,
+            className: "gap-4 @lg:flex-row @lg:gap-5"
+        },
+        {
+            hasSidebarSection: true,
+            embedded: true,
+            scrollSectionsIndependently: false,
+            className: "gap-4 @lg-embed:flex-row @lg-embed:items-start @lg-embed:gap-5"
+        },
+        {
+            hasSidebarSection: true,
+            embedded: false,
+            scrollSectionsIndependently: true,
+            className: "@lg:flex-row"
         },
         {
             hasSidebarSection: true,
             embedded: true,
-            className: "@lg-embed:flex-row @lg-embed:items-start @lg-embed:gap-5"
+            scrollSectionsIndependently: true,
+            className: "@lg-embed:flex-row @lg-embed:items-start"
         },
         {
             reverseOnMobile: true,
@@ -101,24 +119,14 @@ var styles = (0, _tailwindvariants.tv)({
     defaultVariants: {
         hasSidebarSection: false,
         embedded: false,
-        reverseOnMobile: false
+        reverseOnMobile: false,
+        scrollSectionsIndependently: false
     }
 });
-/**
- * Layout component for structuring content.
- *
- * The `Layout` component organizes its children into a flexible and responsive layout.
- * If no `Layout.Section` or `Layout.AnnotatedSection` children are found, it wraps the
- * children inside a default `Layout.Section`.
- *
- * @param {Object} props - Component props.
- * @param {React.ReactNode} props.children - The content to render inside the layout.
- * @param {boolean} [props.reverseOnMobile] - If true, reverses the flex direction on mobile devices.
- * @returns {JSX.Element} The rendered layout component.
- */ function Layout() {
+function Layout() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var embedded = (0, _Frame.useFrame)().embedded;
-    var children = props.children, reverseOnMobile = props.reverseOnMobile;
+    var children = props.children, reverseOnMobile = props.reverseOnMobile, _props_scrollSectionsIndependently = props.scrollSectionsIndependently, scrollSectionsIndependently = _props_scrollSectionsIndependently === void 0 ? false : _props_scrollSectionsIndependently;
     var analyzeChildren = function(children) {
         var depth = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : 0;
         if (depth > 3) return {
@@ -165,17 +173,19 @@ var styles = (0, _tailwindvariants.tv)({
     var classes = styles({
         hasSidebarSection: hasSidebarSection,
         embedded: embedded,
-        reverseOnMobile: reverseOnMobile
+        reverseOnMobile: reverseOnMobile,
+        scrollSectionsIndependently: scrollSectionsIndependently
     });
     var wrappedChildren = hasSection ? children : /*#__PURE__*/ (0, _jsxruntime.jsx)(Layout.Section, {
         children: children
     });
     return /*#__PURE__*/ (0, _jsxruntime.jsx)(LayoutContext.Provider, {
         value: {
-            parentHasSidebar: parentHasSidebar
+            parentHasSidebar: parentHasSidebar,
+            scrollSectionsIndependently: scrollSectionsIndependently
         },
         children: /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-            className: classes,
+            className: "".concat(classes).concat(scrollSectionsIndependently ? " Litho-Layout--scrollSectionsIndependently".concat(embedded ? " @lg-embed:max-h-[calc(100vh-var(--litho-top-bar-height))]" : " @lg:max-h-[calc(100vh-var(--litho-top-bar-height))]") : ""),
             children: wrappedChildren
         })
     });
@@ -193,11 +203,10 @@ var annotatedSectionStyles = (0, _tailwindvariants.tv)({
     }
 });
 /**
- * AnnotatedSection component for displaying a titled section with optional description.
+ * @component Layout.AnnotatedSection
  *
- * The `AnnotatedSection` organizes content into two main areas:
- * - Annotation: Displays a title and description.
- * - Content: Displays the main content provided as children.
+ * @usage
+ * - DO: Use for settings pages where each section has a title and description alongside form content.
  *
  * @param {Object} props - Component props.
  * @param {React.ReactNode} props.children - The main content of the section.
@@ -211,11 +220,13 @@ var annotatedSectionStyles = (0, _tailwindvariants.tv)({
     var annotatedSectionClasses = annotatedSectionStyles({
         embedded: embedded
     });
+    var annotationColSpan = embedded ? "@md-embed:col-span-4" : "@md:col-span-4";
+    var contentColSpan = embedded ? "@md-embed:col-span-8" : "@md:col-span-8";
     return /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
         className: annotatedSectionClasses,
         children: [
             /*#__PURE__*/ (0, _jsxruntime.jsxs)("div", {
-                className: "Litho-Layout__Annotation flex flex-col gap-1 @md:col-span-4 py-2",
+                className: "Litho-Layout__Annotation flex flex-col gap-1 ".concat(annotationColSpan, " py-2"),
                 children: [
                     title && (typeof title === "string" ? /*#__PURE__*/ (0, _jsxruntime.jsx)(_Text.default, {
                         variant: "headingMd",
@@ -228,7 +239,7 @@ var annotatedSectionStyles = (0, _tailwindvariants.tv)({
                 ]
             }),
             /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
-                className: "Litho-Layout__AnnotationContent @md:col-span-8",
+                className: "Litho-Layout__AnnotationContent ".concat(contentColSpan),
                 children: children
             })
         ]

package/dist/cjs/components/LayoutSection.js

@@ -55,7 +55,30 @@ function _interop_require_wildcard(obj, nodeInterop) {
     }
     return newObj;
 }
-var sectionStyles = (0, _tailwindvariants.tv)({
+/**
+ * @component Layout.Section
+ *
+ * @description A direct child of Layout that defines a content column, supporting primary, secondary, and full-width configurations.
+ *
+ * @usage
+ * - DO: Use as a direct child of `Layout` to define content regions.
+ * - DON'T: Use outside of a `Layout` parent.
+ *
+ * @accessibility
+ * - LayoutSection renders a semantic section; content structure is preserved for assistive technology.
+ *
+ * @alternative
+ * - If you need a standalone content section, use `Card` or `Box` instead.
+ *
+ * @param {Object} props - Component props.
+ * @param {React.ReactNode} props.children - The content to render inside the section.
+ * @param {boolean|"slim"} [props.sidebar=false] - Configures the section layout:
+ *  - `true`: Makes it a sidebar with a 1/3 basis.
+ *  - `"slim"`: Makes it a slim sidebar with a max width of 320px.
+ *  - `false`: Allows it to grow.
+ * @params {boolean|integer} props.sticky - Specify whether the section becomes sticky or not
+ * @returns {JSX.Element} The rendered section component.
+ */ var sectionStyles = (0, _tailwindvariants.tv)({
     base: "Litho-Layout__Section",
     variants: {
         sidebar: {
@@ -65,58 +88,97 @@ var sectionStyles = (0, _tailwindvariants.tv)({
         sibling: {
             none: "w-full",
             sidebar: "flex-1 basis-0 min-w-0"
+        },
+        scrollSectionsIndependently: {
+            true: "pt-4 pr-4 @lg:pr-5 @lg:pb-5",
+            false: ""
         }
     },
     compoundVariants: [
+        {
+            scrollSectionsIndependently: true,
+            embedded: true,
+            className: "@lg-embed:overflow-y-auto pl-px"
+        },
+        {
+            scrollSectionsIndependently: true,
+            embedded: false,
+            className: "@lg:overflow-y-auto pl-px"
+        },
+        {
+            scrollSectionsIndependently: true,
+            sidebar: [
+                true,
+                "slim"
+            ],
+            className: "ml-4"
+        },
+        {
+            sidebar: true,
+            embedded: true,
+            scrollSectionsIndependently: false,
+            className: "@lg-embed:w-1/3 @lg-embed:max-w-120"
+        },
         {
             sidebar: true,
+            embedded: false,
+            scrollSectionsIndependently: false,
+            className: "@lg:w-1/3 @lg:max-w-80 @xl:max-w-120"
+        },
+        {
+            sidebar: "slim",
             embedded: true,
-            className: "@lg-embed:w-1/3 @lg-embed:max-w-80 @xl-embed:max-w-120 @lg-embed:w-1/3 @lg-embed:max-w-120"
+            scrollSectionsIndependently: false,
+            className: "@lg-embed:w-1/3 @lg-embed:max-w-80"
+        },
+        {
+            sidebar: "slim",
+            embedded: false,
+            scrollSectionsIndependently: false,
+            className: "@lg:w-1/3 @lg:max-w-80"
+        },
+        {
+            sidebar: true,
+            embedded: true,
+            scrollSectionsIndependently: true,
+            className: "@lg-embed:w-1/3 @lg-embed:max-w-85 @xl-embed:max-w-125"
         },
         {
             sidebar: true,
             embedded: false,
-            className: "@lg:w-1/3 @lg:max-w-80 @xl:max-w-120 @lg:w-1/3 @lg:max-w-120"
+            scrollSectionsIndependently: true,
+            className: "@lg:w-1/3 @lg:max-w-85 @xl:max-w-125"
         },
         {
             sidebar: "slim",
             embedded: true,
-            className: "@lg-embed:w-1/3 @lg-embed:max-w-80 @lg-embed:w-1/3 @lg-embed:max-w-80"
+            scrollSectionsIndependently: true,
+            className: "@lg-embed:w-1/3 @lg-embed:max-w-85"
         },
         {
             sidebar: "slim",
             embedded: false,
-            className: "@lg:w-1/3 @lg:max-w-80 @lg:w-1/3 @lg:max-w-80"
+            scrollSectionsIndependently: true,
+            className: "@lg:w-1/3 @lg:max-w-85"
         }
     ],
     defaultVariants: {
         sidebar: false,
-        embedded: false
+        embedded: false,
+        scrollSectionsIndependently: false
     }
 });
-/**
- * Section component for flexible content grouping.
- *
- * The `Section` allows for configuring its layout, supporting sidebar and slim variants.
- *
- * @param {Object} props - Component props.
- * @param {React.ReactNode} props.children - The content to render inside the section.
- * @param {boolean|"slim"} [props.sidebar=false] - Configures the section layout:
- *  - `true`: Makes it a sidebar with a 1/3 basis.
- *  - `"slim"`: Makes it a slim sidebar with a max width of 320px.
- *  - `false`: Allows it to grow.
- * @params {boolean|integer} props.sticky - Specify whether the section becomes sticky or not
- * @returns {JSX.Element} The rendered section component.
- */ function Section() {
+function Section() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, _props_sidebar = props.sidebar, sidebar = _props_sidebar === void 0 ? false : _props_sidebar, className = props.className, sticky = props.sticky;
     var embedded = (0, _Frame.useFrame)().embedded;
-    var parentHasSidebar = (0, _react.useContext)(_Layout.LayoutContext).parentHasSidebar;
+    var _useContext = (0, _react.useContext)(_Layout.LayoutContext), parentHasSidebar = _useContext.parentHasSidebar, scrollSectionsIndependently = _useContext.scrollSectionsIndependently;
     var sectionClasses = sectionStyles({
         sidebar: sidebar,
         sticky: sticky,
         sibling: sidebar ? undefined : parentHasSidebar ? "sidebar" : "none",
-        embedded: embedded
+        embedded: embedded,
+        scrollSectionsIndependently: scrollSectionsIndependently
     });
     return /*#__PURE__*/ (0, _jsxruntime.jsx)("div", {
         className: "".concat(sectionClasses).concat(className ? " ".concat(className) : ""),

package/dist/cjs/components/Link.js

@@ -16,7 +16,40 @@ function _interop_require_default(obj) {
         default: obj
     };
 }
-var styles = (0, _tailwindvariants.tv)({
+/**
+ * @component Link
+ *
+ * @description An inline navigation element that renders as an anchor tag for linking to internal or external URLs.
+ *
+ * @usage
+ * - DO: Use for inline text navigation to other pages or external URLs.
+ * - DON'T: Use for actions that don't navigate (use Button).
+ *
+ * @accessibility
+ * - Renders as `<a>` tag; ensure link text is descriptive. External links should indicate they open in a new tab.
+ *
+ * @alternative
+ * - If you need to trigger an action (not navigation), use `Button` with `link` variant.
+ * - If you need a button styled as a link, use `Button` with `plain` prop.
+ *
+ * @param {Object} props - Props for the Link component.
+ * @param {string} props.url - The URL the link points to.
+ * @param {React.ReactNode} props.children - Content to display within the link.
+ * @param {Function} [props.onClick] - Optional click event handler for the link.
+ * @param {boolean} [props.external=false] - If true, opens the link in a new tab.
+ * @param {boolean} [props.insight=false] - If true, set the color and iconColor to insight
+ * @param {string} [props.target] - Optional target attribute for specifying where to open the link.
+ * @param {string} [props.id] - Optional id attribute for the link.
+ * @param {boolean} [props.monochrome=false] - If true, applies monochrome color scheme.
+ * @param {boolean} [props.removeUnderline=false] - If true, removes underline from the link.
+ * @param {string} [props.accessibilityLabel] - Optional aria-label for accessibility.
+ * @param {string} [props.dataPrimaryLink] - Optional data attribute for custom tracking.
+ * @param {Function} [props.onMouseEnter] - Optional mouse enter event handler for the link.
+ * @param {Function} [props.onMouseLeave] - Optional mouse leave event handler for the link.
+ * @param {React.ReactNode} [props.icon] - Optional icon to display within the link.
+ *
+ * @returns {JSX.Element} Rendered link element.
+ */ var styles = (0, _tailwindvariants.tv)({
     base: "Litho-Link cursor-pointer hover:underline",
     variants: {
         monochrome: {
@@ -103,27 +136,7 @@ var styles = (0, _tailwindvariants.tv)({
         color: "link"
     }
 });
-/**
- * Renders an accessible link with customizable styling based on variants.
- *
- * @param {Object} props - Props for the Link component.
- * @param {string} props.url - The URL the link points to.
- * @param {React.ReactNode} props.children - Content to display within the link.
- * @param {Function} [props.onClick] - Optional click event handler for the link.
- * @param {boolean} [props.external=false] - If true, opens the link in a new tab.
- * @param {boolean} [props.insight=false] - If true, set the color and iconColor to insight
- * @param {string} [props.target] - Optional target attribute for specifying where to open the link.
- * @param {string} [props.id] - Optional id attribute for the link.
- * @param {boolean} [props.monochrome=false] - If true, applies monochrome color scheme.
- * @param {boolean} [props.removeUnderline=false] - If true, removes underline from the link.
- * @param {string} [props.accessibilityLabel] - Optional aria-label for accessibility.
- * @param {string} [props.dataPrimaryLink] - Optional data attribute for custom tracking.
- * @param {Function} [props.onMouseEnter] - Optional mouse enter event handler for the link.
- * @param {Function} [props.onMouseLeave] - Optional mouse leave event handler for the link.
- * @param {React.ReactNode} [props.icon] - Optional icon to display within the link.
- *
- * @returns {JSX.Element} Rendered link element.
- */ function Link() {
+function Link() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var url = props.url, children = props.children, onClick = props.onClick, external = props.external, target = props.target, _props_bold = props.bold, bold = _props_bold === void 0 ? false : _props_bold, _props_disabled = props.disabled, disabled = _props_disabled === void 0 ? false : _props_disabled, _props_insight = props.insight, insight = _props_insight === void 0 ? false : _props_insight, id = props.id, monochrome = props.monochrome, removeUnderline = props.removeUnderline, accessibilityLabel = props.accessibilityLabel, dataPrimaryLink = props.dataPrimaryLink, _color = props.color, className = props.className, onMouseEnter = props.onMouseEnter, onMouseLeave = props.onMouseLeave, icon = props.icon, _iconColor = props.iconColor, _props_iconSize = props.iconSize, iconSize = _props_iconSize === void 0 ? "sm" : _props_iconSize;
     var hasIcon = icon !== undefined;

package/dist/cjs/components/List.js

@@ -10,7 +10,29 @@ Object.defineProperty(exports, "default", {
 });
 var _jsxruntime = require("react/jsx-runtime");
 var _tailwindvariants = require("tailwind-variants");
-var styles = (0, _tailwindvariants.tv)({
+/**
+ * @component List
+ *
+ * @description A semantic list component that renders ordered or unordered lists with consistent spacing and bullet/number styling.
+ *
+ * @usage
+ * - DO: Display structured text content as bulleted or numbered lists.
+ * - DON'T: Use for interactive item lists (use ResourceList).
+ *
+ * @accessibility
+ * - Renders semantic `<ul>` or `<ol>` elements; screen readers announce list structure and item count.
+ *
+ * @alternative
+ * - If you need interactive items with actions, use `ResourceList`.
+ * - If you need a data table, use `Table`.
+ *
+ * @param {Object} props - Component props.
+ * @param {React.ReactNode} props.children - The list items to render inside the list.
+ * @param {'normal' | 'loose' | 'tight'} [props.spacing='normal'] - Controls vertical spacing between list items.
+ * @param {'bullet' | 'number'} [props.type='bullet'] - Determines list type: bullet (unordered) or number (ordered).
+ * @param {string} [props.className] - Additional class names to apply to the list container.
+ * @returns {JSX.Element} The rendered List component.
+ */ var styles = (0, _tailwindvariants.tv)({
     base: "Litho-List list-outside ml-5",
     variants: {
         type: {
@@ -25,16 +47,7 @@ var styles = (0, _tailwindvariants.tv)({
         }
     }
 });
-/**
- * List component for rendering unordered or ordered lists.
- *
- * @param {Object} props - Component props.
- * @param {React.ReactNode} props.children - The list items to render inside the list.
- * @param {'normal' | 'loose' | 'tight'} [props.spacing='normal'] - Controls vertical spacing between list items.
- * @param {'bullet' | 'number'} [props.type='bullet'] - Determines list type: bullet (unordered) or number (ordered).
- * @param {string} [props.className] - Additional class names to apply to the list container.
- * @returns {JSX.Element} The rendered List component.
- */ function List() {
+function List() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, _props_spacing = props.spacing, spacing = _props_spacing === void 0 ? 'normal' : _props_spacing, _props_type = props.type, type = _props_type === void 0 ? 'bullet' : _props_type, className = props.className;
     var classes = styles({
@@ -51,7 +64,10 @@ var itemStyles = (0, _tailwindvariants.tv)({
     base: "Litho-ListItem text-left leading-4"
 });
 /**
- * Item component for individual list items in the List component.
+ * @component List.Item
+ *
+ * @usage
+ * - DO: Use as direct children of List for each list entry.
  *
  * @param {Object} props - Component props.
  * @param {React.ReactNode} props.children - The content of the list item.