docs: add stories for Availability

packages/docs/stories/_internals/Code.tsx

@@ -0,0 +1,3 @@
+export const Code: React.FC<{ children?: string }> = ({ children }) => {
+  return <code className='bg-gray-100 px-2'>{children}</code>
+}

packages/docs/stories/skus/Availability.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryFn, StoryObj } from '@storybook/react'
+import CommerceLayer from '../_internals/CommerceLayer'
+import { AvailabilityTemplate } from '#components/skus/AvailabilityTemplate'
+import { AvailabilityContainer } from '#components/skus/AvailabilityContainer'
+import PricesContainer from '#components/prices/PricesContainer'
+
+const setup: Meta<typeof AvailabilityTemplate> = {
+  title: 'Components/Skus/Availability',
+  component: AvailabilityTemplate,
+  argTypes: {
+    showShippingMethodName: {
+      control: 'boolean'
+    },
+    showShippingMethodPrice: {
+      control: 'boolean'
+    },
+    timeFormat: {
+      control: 'radio',
+      options: ['days', 'hours', undefined]
+    }
+  }
+}
+
+export default setup
+
+const Template: StoryFn<typeof AvailabilityTemplate> = (args) => {
+  return (
+    <CommerceLayer
+      accessToken='my-access-token'
+      endpoint='https://demo-store.commercelayer.io'
+    >
+      <AvailabilityContainer skuCode='BABYONBU000000E63E7412MX'>
+        <AvailabilityTemplate {...args} />
+      </AvailabilityContainer>
+    </CommerceLayer>
+  )
+}
+
+export const AvailableWithDeliveryTime = Template.bind({})
+AvailableWithDeliveryTime.args = {
+  timeFormat: 'days',
+  showShippingMethodName: true,
+  showShippingMethodPrice: true
+}
+
+/**
+ * You can customize the text displayed in case of `available`, `outOfStock` or `negativeStock`, using custom `labels`.
+ */
+export const WithCustomLabel = Template.bind({})
+WithCustomLabel.args = {
+  labels: {
+    available: 'Item is available'
+  }
+}
+
+/**
+ * When `sku` is not available, the `delivery_lead_time` will not be displayed.
+ */
+export const NotAvailable: StoryFn<typeof AvailabilityTemplate> = (args) => {
+  return (
+    <CommerceLayer
+      accessToken='my-access-token'
+      endpoint='https://demo-store.commercelayer.io'
+    >
+      <AvailabilityContainer skuCode='BABYONBU000000FFFFFFNBXX'>
+        <AvailabilityTemplate
+          timeFormat='days'
+          showShippingMethodName
+          showShippingMethodPrice
+        />
+      </AvailabilityContainer>
+    </CommerceLayer>
+  )
+}
+
+/**
+ * You can access the `delivery_lead_times` object using the children props.
+ * In this way you will be able to apply your own logic when displaying the availability info.
+ * <span type='info'>
+ * Check the `delivery_lead_times` resource from our [Core API documentation](https://docs.commercelayer.io/core/v/api-reference/delivery_lead_times/object).
+ * </span>
+ */
+export const ChildrenProps: StoryObj = () => {
+  return (
+    <CommerceLayer
+      accessToken='my-access-token'
+      endpoint='https://demo-store.commercelayer.io'
+    >
+      <AvailabilityContainer skuCode='BABYONBU000000E63E7412MX'>
+        <AvailabilityTemplate>
+          {(childrenProps) => {
+            return (
+              <div>
+                <p className='font-bold'>Custom logic:</p>
+                <p className='mb-8'>
+                  {childrenProps.quantity} items available delivered in{' '}
+                  {childrenProps.min?.hours} hours
+                </p>
+                <p className='font-bold'>The delivery_lead_times object</p>
+                <pre key={childrenProps.id}>
+                  {JSON.stringify(childrenProps, null, 2)}
+                </pre>
+              </div>
+            )
+          }}
+        </AvailabilityTemplate>
+      </AvailabilityContainer>
+    </CommerceLayer>
+  )
+}
+ChildrenProps.decorators = [
+  (Story) => {
+    return (
+      <CommerceLayer
+        accessToken='my-access-token'
+        endpoint='https://demo-store.commercelayer.io'
+      >
+        <PricesContainer>
+          <Story />
+        </PricesContainer>
+      </CommerceLayer>
+    )
+  }
+]
+ChildrenProps.parameters = {
+  docs: {
+    source: {
+      type: 'code'
+    }
+  }
+}

packages/docs/stories/skus/AvailabilityContainer.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryFn } from '@storybook/react'
+import CommerceLayer from '../_internals/CommerceLayer'
+import { AvailabilityContainer } from '#components/skus/AvailabilityContainer'
+import { Code } from '../_internals/Code'
+
+const setup: Meta<typeof AvailabilityContainer> = {
+  title: 'Components/Skus/AvailabilityContainer',
+  component: AvailabilityContainer
+}
+
+export default setup
+
+const Template: StoryFn<typeof AvailabilityContainer> = (args) => {
+  return (
+    <CommerceLayer
+      accessToken='my-access-token'
+      endpoint='https://demo-store.commercelayer.io'
+    >
+      <AvailabilityContainer {...args}>
+        <div>
+          I am the availability container, responsible to fetch <Code>sku</Code>{' '}
+          availability and <Code>delivery_lead_time</Code>
+        </div>
+      </AvailabilityContainer>
+    </CommerceLayer>
+  )
+}
+
+export const Default = Template.bind({})
+Default.args = {
+  skuCode: 'BABYONBU000000E63E7412MX',
+  getQuantity: (quantity) => {
+    console.log('quantity', quantity)
+  }
+}

packages/react-components/src/components/skus/AvailabilityContainer.tsx

@@ -21,6 +21,18 @@ interface Props {
   getQuantity?: (quantity: number) => void
 }
 
+/**
+ * Main container for the Availability components.
+ * It stores - in its context - the sku quantity returned from the `inventory_model` and the `delivery_lead_time` for the first shipping method found in the inventory model.
+ *
+ * It can be used to fetch the quantities for a specific `sku_code` passed as prop.
+ * <span title='Requirements' type='warning'>
+ * Must be a child of the `<CommerceLayer>` component.
+ * </span>
+ * <span title='Children' type='info'>
+ * `<AvailabilityTemplate>`
+ * </span>
+ */
 export function AvailabilityContainer({
   children,
   skuCode,

packages/react-components/src/components/skus/AvailabilityTemplate.tsx

@@ -14,15 +14,16 @@ interface AvailabilityTemplateChildrenProps
 type FormatRules =
   | {
       /**
-       * Set time format for shipping method
+       * Set time format for shipping method. When not set, ``delivery_lead_times`` will not be displayed.
+       * When set, `delivery_lead_times` for the first shipping method found in the inventory model, will be displayed in the format specified.
        */
       timeFormat?: TimeFormat
       /**
-       * Show shipping method name
+       * Show shipping method name. Requires `timeFormat` to be set.
        */
       showShippingMethodName?: false
       /**
-       * Show shipping method price
+       * Show shipping method price. Requires `timeFormat` to be set.
        */
       showShippingMethodPrice?: false
     }
@@ -47,6 +48,18 @@ type Props = {
 } & Omit<JSX.IntrinsicElements['span'], 'children'> &
   FormatRules
 
+/**
+ * The AvailabilityTemplate component displays the availability of the SKU specified
+ * in the parent `<AvailabilityContainer>` component.
+ *
+ * It is possible to customize the text displayed in case of `available`, `outOfStock` or `negativeStock.
+ * It is also possible to show delivery lead time and either shipping method name and/or price.
+ * This information will be retrieve from the first shipping method found in the inventory model.
+ *
+ * <span type="Requirement" type="info">
+ * It must to be used inside the `<AvailabilityContainer>` component.
+ * </span>
+ */
 export function AvailabilityTemplate(props: Props): JSX.Element {
   const {
     timeFormat,