@heymantle/litho 0.0.15 → 0.0.16

package/dist/esm/components/Grid.js

@@ -50,7 +50,31 @@ function _unsupported_iterable_to_array(o, minLen) {
 }
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-// Map semantic gap values to numeric Tailwind values
+/**
+ * @component Grid
+ *
+ * @description A CSS grid layout component for arranging children in a two-dimensional grid with configurable columns and gap.
+ *
+ * @usage
+ * - DO: Use for two-dimensional layouts with rows and columns.
+ * - DON'T: Use for simple linear stacking (use `Stack` instead).
+ *
+ * @accessibility
+ * - Grid is a layout utility; ensure grid items maintain a logical tab and reading order.
+ *
+ * @alternative
+ * - If you need one-dimensional flex layout, use `Stack` instead.
+ * - If you need a simple two-column layout, use `Layout`.
+ *
+ * @param {object} [props={}] - Props for the Grid component.
+ * @param {React.ReactNode} [props.children] - Content to render inside the Grid.
+ * @param {number|object} [props.columns] - Defines the number of columns in the grid. Can be a single number or an object with breakpoints as keys.
+ * @param {(number|'none'|'xs'|'sm'|'md'|'lg'|object)} [props.gap] - Defines the gap between grid items. Can be a number, semantic value ('none', 'xs', 'sm', 'md', 'lg'), or an object with breakpoints as keys. Semantic values: 'none' (0), 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8).
+ * @param {"stretch"|"start"|"end"|"center"} [props.justify="stretch"] - Horizontal alignment of the grid items.
+ * @param {"stretch"|"start"|"end"|"center"} [props.align="stretch"] - Vertical alignment of the grid items.
+ * @param {string} [props.className] - Additional class names to apply to the grid.
+ * @returns {JSX.Element} A div element representing the grid container.
+ */ // Map semantic gap values to numeric Tailwind values
 var gapMap = {
     none: "0",
     xs: "1",
@@ -79,18 +103,7 @@ var styles = tv({
         align: "stretch"
     }
 });
-/**
- * Tailwind-based Grid component with customizable columns, gaps, alignment, and justification.
- *
- * @param {object} [props={}] - Props for the Grid component.
- * @param {React.ReactNode} [props.children] - Content to render inside the Grid.
- * @param {number|object} [props.columns] - Defines the number of columns in the grid. Can be a single number or an object with breakpoints as keys.
- * @param {(number|'none'|'xs'|'sm'|'md'|'lg'|object)} [props.gap] - Defines the gap between grid items. Can be a number, semantic value ('none', 'xs', 'sm', 'md', 'lg'), or an object with breakpoints as keys. Semantic values: 'none' (0), 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8).
- * @param {"stretch"|"start"|"end"|"center"} [props.justify="stretch"] - Horizontal alignment of the grid items.
- * @param {"stretch"|"start"|"end"|"center"} [props.align="stretch"] - Vertical alignment of the grid items.
- * @param {string} [props.className] - Additional class names to apply to the grid.
- * @returns {JSX.Element} A div element representing the grid container.
- */ function Grid() {
+function Grid() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var children = props.children, columns = props.columns, _props_gap = props.gap, gap = _props_gap === void 0 ? "md" : _props_gap, _props_justify = props.justify, justify = _props_justify === void 0 ? "stretch" : _props_justify, _props_align = props.align, align = _props_align === void 0 ? "stretch" : _props_align, className = props.className;
     var columnClasses;
@@ -128,8 +141,11 @@ var styles = tv({
 }
 ;
 /**
- * Cell component for the Grid, allowing column span customization.
- * 
+ * @component Grid.Cell
+ *
+ * @usage
+ * - DO: Wrap grid children to control column/row span.
+ *
  * @param {object} [props={}] - Props for the Cell component.
  * @param {number|object} [props.columnSpan] - Defines the column span for the cell. Can be a single number or an object with breakpoints as keys.
  * @param {React.ReactNode} [props.children] - Content to render inside the cell.

package/dist/esm/components/HorizontalStack.js

@@ -79,7 +79,43 @@ function _object_without_properties_loose(source, excluded) {
 }
 import { jsx as _jsx } from "react/jsx-runtime";
 import { tv } from "tailwind-variants";
-var styles = tv({
+/**
+ * @component HorizontalStack
+ *
+ * @description A horizontal flex layout component for arranging children in a row with consistent spacing and alignment.
+ *
+ * @deprecated Use `Stack` with `horizontal` boolean prop set to true instead. This component will be removed in a future release.
+ *
+ * @usage
+ * - DO: Arrange elements horizontally with consistent spacing.
+ * - DON'T: Use for vertical stacking (use `VerticalStack` or `Stack` instead).
+ *
+ * @accessibility
+ * - Ensure content order in the DOM matches the visual horizontal order for screen readers.
+ *
+ * @alternative
+ * - If you need vertical stacking, use `VerticalStack`.
+ * - If you need flexible direction, use `Stack`.
+ *
+ * @param {Object} [props={}] - Component props.
+ * @param {string} [props.as='div'] - The HTML element to render. Defaults to `div`.
+ * @param {React.ReactNode} [props.children] - Child elements to render inside the stack.
+ * @param {('none'|'xs'|'sm'|'md'|'lg'|'0'|'px'|'0.5'|'1'|'2'|'3'|'4'|'5'|'6'|'8'|'10')} [props.gap] - Spacing between children. Semantic options: 'none', 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8). Numeric options: '0', 'px', '0.5', '1', '2', '3', '4', '5', '6', '8', '10'.
+ * @param {string} [props.id] - Optional ID for the component.
+ * @param {string} [props.className] - Additional custom class names to apply to the component.
+ * @param {string} [props.align='start'] - Horizontal alignment of children. Options: 'start', 'center', 'end'.
+ * @param {string} [props.blockAlign='start'] - Vertical alignment of children. Options: 'start', 'center', 'end'.
+ * @param {boolean} [props.wrap=true] - Whether children should wrap to the next line if necessary. Defaults to `true`.
+ * @param {Object} [restProps] - Additional props passed to the root element.
+ *
+ * @returns {JSX.Element} The rendered HorizontalStack component.
+ *
+ * @example
+ * <HorizontalStack gap="2" align="center" blockAlign="start">
+ *   <div>Item 1</div>
+ *   <div>Item 2</div>
+ * </HorizontalStack>
+ */ var styles = tv({
     base: "Litho-HorizontalStack flex flex-row",
     variants: {
         gap: {
@@ -125,30 +161,7 @@ var styles = tv({
         blockAlign: "start"
     }
 });
-/**
- * HorizontalStack Component
- *
- * A flexible horizontal stack component with customizable spacing, alignment, and wrapping.
- *
- * @param {Object} [props={}] - Component props.
- * @param {string} [props.as='div'] - The HTML element to render. Defaults to `div`.
- * @param {React.ReactNode} [props.children] - Child elements to render inside the stack.
- * @param {('none'|'xs'|'sm'|'md'|'lg'|'0'|'px'|'0.5'|'1'|'2'|'3'|'4'|'5'|'6'|'8'|'10')} [props.gap] - Spacing between children. Semantic options: 'none', 'xs' (1), 'sm' (2), 'md' (4), 'lg' (8). Numeric options: '0', 'px', '0.5', '1', '2', '3', '4', '5', '6', '8', '10'.
- * @param {string} [props.id] - Optional ID for the component.
- * @param {string} [props.className] - Additional custom class names to apply to the component.
- * @param {string} [props.align='start'] - Horizontal alignment of children. Options: 'start', 'center', 'end'.
- * @param {string} [props.blockAlign='start'] - Vertical alignment of children. Options: 'start', 'center', 'end'.
- * @param {boolean} [props.wrap=true] - Whether children should wrap to the next line if necessary. Defaults to `true`.
- * @param {Object} [restProps] - Additional props passed to the root element.
- *
- * @returns {JSX.Element} The rendered HorizontalStack component.
- *
- * @example
- * <HorizontalStack gap="2" align="center" blockAlign="start" wrap={false}>
- *   <div>Item 1</div>
- *   <div>Item 2</div>
- * </HorizontalStack>
- */ function HorizontalStack() {
+function HorizontalStack() {
     var props = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
     var _props_as = props.as, as = _props_as === void 0 ? 'div' : _props_as, children = props.children, gap = props.gap, id = props.id, className = props.className, align = props.align, blockAlign = props.blockAlign, _props_wrap = props.wrap, wrap = _props_wrap === void 0 ? true : _props_wrap, restProps = _object_without_properties(props, [
         "as",