@7shifts/sous-chef 4.2.0 → 4.3.0

package/dist/navigation/PrimaryNav/PrimaryNav.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+type Props = {
+    children: React.ReactNode;
+    isExpanded?: boolean;
+    onToggleExpand?: (state: 'expanded' | 'collapsed') => void;
+    footer?: React.ReactNode;
+    /** This is the logo displayed when the navigation is collapsed. By default it uses the 7shifts short logo */
+    shortLogo?: React.ReactNode;
+    /** This is the logo displayed when the navigation is expanded. By default it uses the 7shifts logo */
+    longLogo?: React.ReactNode;
+};
+declare const PrimaryNav: ({ children, isExpanded, onToggleExpand, footer, shortLogo, longLogo }: Props) => React.JSX.Element;
+export default PrimaryNav;

package/dist/navigation/PrimaryNav/PrimaryNavContext.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+export type PrimaryNavContextType = {
+    isNavExpanded: boolean;
+    setIsNavExpanded: (isExpanded: boolean) => void;
+    isHoveringNav: boolean;
+    setIsHoveringNav: (isHovering: boolean) => void;
+    isOpen: boolean;
+    contentRef: React.RefObject<HTMLDivElement>;
+};
+export declare const usePrimaryNavContext: () => PrimaryNavContextType;
+type Props = {
+    children: React.ReactNode;
+    isExpanded?: boolean;
+};
+export declare function PrimaryNavContextProvider({ children, isExpanded: externalIsExpanded }: Props): React.JSX.Element;
+export {};

package/dist/navigation/PrimaryNav/PrimaryNavHeader/PrimaryNavHeader.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+type Props = {
+    onToggleExpand?: (state: 'expanded' | 'collapsed') => void;
+    shortLogo?: React.ReactNode;
+    longLogo?: React.ReactNode;
+};
+declare const PrimaryNavHeader: ({ onToggleExpand, shortLogo, longLogo }: Props) => React.JSX.Element;
+export default PrimaryNavHeader;

package/dist/navigation/PrimaryNav/PrimaryNavHeader/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PrimaryNavHeader';

package/dist/navigation/PrimaryNav/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PrimaryNav';

package/dist/navigation/PrimaryNavDivider/PrimaryNavDivider.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+declare const PrimaryNavDivider: () => React.JSX.Element;
+export default PrimaryNavDivider;

package/dist/navigation/PrimaryNavDivider/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PrimaryNavDivider';

package/dist/navigation/PrimaryNavFooter/PrimaryNavFooter.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+type Props = {
+    children: React.ReactNode;
+};
+declare const PrimaryNavFooter: ({ children }: Props) => React.JSX.Element;
+export default PrimaryNavFooter;

package/dist/navigation/PrimaryNavFooter/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PrimaryNavFooter';

package/dist/navigation/PrimaryNavItem/PrimaryNavItem.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { DataProps } from '../../foundation/types';
+type Props = {
+    children?: React.ReactNode;
+    icon: React.ReactNode;
+    isActive?: boolean;
+    label: string;
+    badge?: string | number;
+    onClick: (e: React.MouseEvent<HTMLElement>) => void;
+} & DataProps;
+declare const PrimaryNavItem: ({ children, icon, isActive, label, badge, onClick, ...rest }: Props) => React.JSX.Element;
+export default PrimaryNavItem;

package/dist/navigation/PrimaryNavItem/PrimaryNavItemBadge/PrimaryNavItemBadge.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+type Props = {
+    badge?: string | number;
+    hasSubItems: boolean;
+    hasActiveSubItem: boolean;
+    sumOfSubItemsBadges: number;
+};
+declare const PrimaryNavItemBadge: ({ badge, hasSubItems, hasActiveSubItem, sumOfSubItemsBadges }: Props) => React.JSX.Element | null;
+export default PrimaryNavItemBadge;

package/dist/navigation/PrimaryNavItem/PrimaryNavItemBadge/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PrimaryNavItemBadge';

package/dist/navigation/PrimaryNavItem/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PrimaryNavItem';

package/dist/navigation/PrimaryNavSubItem/PrimaryNavSubItem.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import { DataProps } from '../../foundation/types';
+type Props = {
+    children: React.ReactNode;
+    isActive?: boolean;
+    badge?: string | number;
+    onClick: (e: React.MouseEvent<HTMLElement>) => void;
+    isPaywalled?: boolean;
+} & DataProps;
+declare const PrimaryNavSubItem: ({ children, isActive, badge, onClick, isPaywalled, ...rest }: Props) => React.JSX.Element;
+export default PrimaryNavSubItem;

package/dist/navigation/PrimaryNavSubItem/index.d.ts

@@ -0,0 +1 @@
+export { default } from './PrimaryNavSubItem';

package/dist/navigation/index.d.ts

@@ -1,3 +1,8 @@
 import Breadcrumbs from './Breadcrumbs';
 import BreadcrumbItem from './BreadcrumbItem';
-export { Breadcrumbs, BreadcrumbItem };
+import PrimaryNav from './PrimaryNav';
+import PrimaryNavItem from './PrimaryNavItem';
+import PrimaryNavSubItem from './PrimaryNavSubItem';
+import PrimaryNavDivider from './PrimaryNavDivider';
+import PrimaryNavFooter from './PrimaryNavFooter';
+export { Breadcrumbs, BreadcrumbItem, PrimaryNav, PrimaryNavItem, PrimaryNavSubItem, PrimaryNavDivider, PrimaryNavFooter };

package/dist/utils/actions.d.ts

@@ -1,2 +1,2 @@
 import React from 'react';
-export declare const updateButtonProps: (button: React.ReactElement | undefined, newProps: Object) => React.ReactElement | null;
+export declare const updateButtonProps: (button: React.ReactElement | undefined, newProps: Record<string, unknown>) => React.ReactElement | null;

package/llms-instructions/llms-components.md

@@ -0,0 +1,425 @@
+# @7shifts/sous-chef — Component Reference
+
+All component APIs and use cases are defined in the Storybook MCP. You can get detailed information about any specific component.
+
+In this document, you will find additional information on how to use components in specific situations.
+
+## Actions
+
+Components available:
+
+### Button
+
+When using a button with an icon and text, you don't need to use the `Inline` component to align the elements:
+
+```tsx
+<Button>
+    <IconPencil />
+    Edit
+</Button>
+```
+
+Also, the icon size is inferred by the `Button` component.
+
+### Link
+
+### PaginationControls
+
+Only use this component if you need to control pagination outside of the `DataTable` component. If you are using `DataTable`, it already provides props for controlling pagination.
+
+### Toggle
+
+It should be used outside of a form. If it is inside a form, then you should use a `CheckboxField` instead.
+The `Toggle` component is used when there is no `Save` button to persist the data, so when the user changes its value, it is automatically persisted, usually in settings.
+
+## Controls
+
+Controls contains the components that are usually used in toolbars, for example in a list filter.
+
+Components available:
+
+### DateFilter
+
+Use this component to filter content on the page by date, whether by day, week, or month.
+DON'T use it in a form with a submit button. Inside a form, you should use the `DateField`, `DateRangeField`, or `WeekField` components for picking a date.
+
+### SegmentedControl
+
+Segmented control is typically used in a toolbar to switch between different views. It can have two or three options.
+DON'T use it as tabs. Sous Chef does not have a `Tab` component yet, so if you need one, check whether there is an application-specific `Tab` component to use. If not, then you need to create one.
+
+### ToolbarSelect
+
+This component is used to select options (similar to `SelectField`). However, this is meant to be used outside of a Form, more specifically in toolbars where there is no need for a label.
+
+## Empty States
+
+Components available:
+
+### EmptyState
+
+This component should be used outside the context of a list because list components already handle the empty state. For example, `DataTable` handles the empty state when `items` is an empty array.
+Use this component when you want to show an empty state inside a modal or for a first-time user experience.
+
+### Paywall
+
+It is similar to the `EmptyState` component, but it is designed for conversion flows with proper upsell theming on headers and other features.
+
+## Feedback
+
+Feedback components bring information to the user's attention.
+
+Components available:
+
+### CircularProgress
+
+It is a circular bar that shows the progress. Use this component when you want a small indicator of progress. If you want something bigger, use the `ProgressBar`.
+
+### InlineBanner
+
+It is the most commonly used banner for displaying information. It fills all the space available in the container where it is placed.
+If you want a smaller banner, then use the `MicroBanner` component.
+
+When rendering it in a page using the `Page` component, you can place it in the `banner` prop.
+
+### MicroBanner
+
+It is a small banner that does not take all the space available in the container. It can be used where space is limited, for example, in top bars.
+
+### PersistentBanner
+
+It should be used for something that needs a lot of attention, for example, a failed subscription payment. Usually, it is placed above the top bar.
+
+### ProgressBar
+
+It is a bar that takes all the space available on the container it is placed. It is usually used inside a modal as the progress tracker of a wizard, for example.
+
+### Skeleton
+
+Used for building skeleton loading states. The `DataTable` already handles the loading state.
+Use this component when you want to create a loading state for some view, for example a card, or something else.
+
+### Spinner
+
+This is the classic loading state. Skeleton brings a more modern loading state.
+
+### Toast
+
+It is a simple function that shows a small pop-up at the bottom of the page. It should be used to show the user that an action has completed or that something failed.
+
+```
+toast('User updated')
+```
+
+## Forms
+
+For common form composition examples, refer to the [Composing components](llms-composing-components.md) document.
+
+Components available:
+
+### AsyncSelectField
+
+It is similar to the `SelectField`; however, it has a `loadOptions` prop that returns a `Promise` to load the data. With `SelectField`, you need to pass the `options` prop directly.
+Use this component when you DON'T have all the options upfront and you need to fetch data from an API, or when your endpoint is paginated.
+
+### CheckboxField
+
+Simple checkbox field.
+
+### ColorField
+
+Used when you need to pick a color. It gives all the sequention color tokens as options.
+
+### CurrencyField
+
+Used when the user needs to type a currency value.
+
+### DateField
+
+Used when the user needs to pick up a SINGLE date. If the user needs a range then use the `DateRangeField`. If the user needs a week, then use the `WeekField`.
+
+### DateRangeField
+
+Used when the user wants to pick a range of dates (start and end).
+
+### Form
+
+This is the component that holds the form state, usually through the `formik` prop, and is responsible for submitting the data.
+
+### FormFeedback
+
+Used to show a form validation error at the form-wide level. Individual form fields already handle their own error state.
+
+### FormFooter
+
+It is responsible for holding the submit button and other form actions. It takes the `actions` prop and automatically positions the buttons properly.
+
+### FormRow
+
+Used when you need to place form fields on the same row. It distributes the space evenly between the form fields.
+For forms, give preference to `FormRow` instead of the `Inline` component.
+
+### FormSection
+
+Used when you need to group some form fields together. It handles the title and subtitle of the section.
+You can also use it as a card with the `as="card"` prop. In forms, if you see form fields inside a card, it is usually a `FormSection` component with the `as="card"` prop.
+
+### MultiSelectField
+
+Similar to the `SelectField` but for selecting multiple options.
+
+### NumberField
+
+Form field for informing numbers.
+
+### PasswordField
+
+Used for entering passwords. Unlike the other form fields, this component does not have a `caption` prop. Instead, it handles the configured password criteria in the caption, for example when the password is too weak.
+
+### PercentageField
+
+Used for informing a percentage number.
+
+### PhoneField
+
+Used for entering a phone number. By default, it uses the `country` passed to the `SousChefProvider`, but it can be overridden by passing the `defaultCountry` prop.
+
+### PillSelectField
+
+It is similar to the `SelectField` but all the options are shown side-by-side in the screen. Use this component when you have just a few options to display.
+
+### RadioGroupField
+
+Used when the user needs to select only one option. Options can also be displayed as cards when using the `RadioGroupBoxOption` as children.
+
+Subcomponents:
+
+-   RadioGroupOption
+-   RadioGroupBoxOption
+
+### SelectField
+
+Used when you need to select only one option from the dropdown.
+
+### TextAreaField
+
+Similar to the `TextField` but it can have multiple lines and can also have toolbar at the bottom where you can place some buttons.
+
+### TextField
+
+This is the main component for typing a text in a form.
+
+### TimeField
+
+Used for pick a specific time. If you need a range of times then use the `TimeRangeField`.
+
+### TimeRangeField
+
+Used when you need to select a start time and an end time.
+
+### WeekField
+
+Used when you need to select a week. This component will give you the start of the week to be saved in the form state.
+
+## Media
+
+Available components
+
+### Avatar
+
+By default, the `Avatar` component already handles a user illustration with an appropriate background color, so you don't need to pass the `color` prop for this use case.
+You can also pass letters as children, usually initials. In that case, you can set the `color` prop if you want a specific color.
+You can also show a user image passing the `url` prop.
+
+### Badge
+
+It is a circle that is usually used to show a counter, for example, the number of unseen notifications. It can also be used with an icon.
+
+### Chip
+
+A chip is similar looking to pill, but is instead used to convey system status such as "New", "Beta", or "Add-on".
+
+### Pill
+
+A Pill is used to inform users on the status of a nearby object or of an action that’s been taken. It is bigger than a Chip.
+
+## Layout
+
+Available components:
+
+### Card
+
+It is a simple container with a border (and border radius) and some content in it. It is a flexible component meant to render everything the user passes as children.
+When using it inside a form, check whether it is more suitable to use a `FormSection` component instead.
+
+### Inline
+
+Used to align elements side by side. It uses CSS `flex` concepts for its props. For complex use cases where you need to control how each item grows, you can use the `flex` prop.
+Pay special attention to the `flex` prop. It is an array of elements, each of which can be a string or number, where each element sets the `flex` prop for a child element. For example:
+
+```tsx
+<Inline flex={['0 1 auto', 1]}>
+    <div>item 1</div>
+    <div>item 2</div>
+</Inline>
+```
+
+It is literally setting the CSS `flex: 0 1 auto;` to the first element and `flex: 1` to the second element.
+
+### Page
+
+It is used to create a single page with slots to place all page elements, such as title, subtitle, banner, filter bar, actions, and children.
+IMPORTANT: It should not be used for high-level app layout, such as the nav bar and top bar. Also, if it has a small left menu, it is probably a `PageLayout` component.
+
+For examples of how to set up a page layout, refer to the [Composing components](llms-composing-components.md) document.
+
+### PageLayout
+
+It should be used to hold a group of pages where there is a left side menu (using the `menu` prop). Usually, when the user clicks on a menu item it should navigate to some specific route.
+In its children, it should contain a router where each route renders a component that uses a `Page` component.
+
+For examples of how to set up a page layout, refer to the [Composing components](llms-composing-components.md) document.
+
+### Stack
+
+Used to align elements vertically. It is similar to the `Inline` component. It uses CSS `flex` concepts for its props. For complex use cases where you need to control how each item grows, you can use the `flex` prop.
+Pay special attention to the `flex` prop. It is an array of elements, each of which can be a string or number, where each element sets the `flex` prop for a child element. For example:
+
+```tsx
+<Inline flex={['0 1 auto', 1]}>
+    <div>item 1</div>
+    <div>item 2</div>
+</Inline>
+```
+
+It is literally setting the CSS `flex: 0 1 auto;` to the first element and `flex: 1` to the second element.
+
+## Lists
+
+Components used to display a list of data.
+
+Available components:
+
+### Accordion
+
+Accordions are lists used to group information into collapsible sections. Only one section can be open at a time.
+Don't use this component if you have columns, in that case, use the `DataTable` component instead.
+
+### ActionList
+
+It is similar to the `Accordion` but it does not collapse items. It is a more rich data display that should be used for displaying a list of actions that the user needs to take.
+It is usually used on dashboard pages.
+
+Subcomponents:
+
+-   ActionListItem
+
+### DataTable
+
+This is the main component used to display a dynamic list of data (usually coming from an endpoint).
+With this component, you can build simple tables by passing an array of `items`, but you can also build more complex use cases, such as sortable columns, pagination, and editable cells.
+
+Subcomponents:
+
+-   DataTableRow
+-   DataTableCell
+-   DataTableEditableCell
+
+For examples of how to compose tables, refer to the [Composing components](llms-composing-components.md) document.
+
+## Navigation
+
+Available components
+
+### Breadcrumbs
+
+The `Page` component already handles breadcrumbs. However, if you need to render breadcrumbs outside of the page component then you can use this component.
+
+## Overlay
+
+Overlays are components that render on top of the main page.
+
+Available components:
+
+### Calendar
+
+It is a standalone calendar that needs an `anchorRef` from a trigger, for example, a button created with React `useRef`.
+Use this component outside of a Form context. If you are in a form, then use the form fields for picking a date.
+
+### Dropdown
+
+A Dropdown is where you can have menu options that are hidden until the user clicks or hovers on a trigger element.
+If you want to render a more complex interaction or content within a dropdown, consider using a Popover instead.
+
+Subcomponents:
+
+-   DropdownList
+-   DropdownListItem
+-   DropdownListItemSelectable
+-   DropdownListItemDivider
+
+### HintModal
+
+HintModal can be used to provide tips or guidance to users on a page. It is not typically triggered by a button. Instead, it should be rendered when a user navigates to a page where they might require additional guidance.
+It shows on the bottom-right side of the screen.
+For larger information or forms, use the `Modal` component instead.
+
+### Modal
+
+Used to interrupt the page flow and show a container to display some information, such as a paywall, a set of steps in a wizard, or a form.
+It already handles the `header` and `subHeader`.
+
+Subcomponents:
+
+-   ModalBody
+-   ModalFooter
+
+When using a form inside a modal, refer to the [Composing components](llms-composing-components.md) document, as it has some special configuration to work well in a modal.
+
+### Popover
+
+Similar to a `Dropdown` but, instead of options, you have the flexibility to render anything you want in the children. It will be placed in the overlay.
+For small overlays, like a text with a title, use the `Tooltip` instead.
+
+### Tooltip
+
+Used to show small overlays, usually it is triggered on hover. If you need to render more complex things use the `Popover` component instead.
+
+## Typography
+
+### Text
+
+This is the atomic component for rendering text and headings. You can use the `as` prop to set how it will be displayed:
+
+Example:
+
+```tsx
+<Text as="h1">Title</Text>
+```
+
+You can give emphasis to a text using the `emphasis` prop:
+
+Example:
+
+```tsx
+<Text emphasis="bold">Title</Text>
+<Text emphasis=["bold", "italic"]>Title</Text> // with multiple emphasis
+```
+
+If you want to give emphasis just to some parts of the text you can use the sub components:
+
+Example:
+
+```tsx
+<Text>
+    Example of a <Bold>bold</Bold> text and <Italic>italic</Italic> text.
+</Text>
+```
+
+The subcomponents use a `span` tag under the hood, so they do not break the DOM structure.
+
+Subcomponents:
+
+-   Italic
+-   Bold
+-   Underline