@7shifts/sous-chef 4.4.1 → 4.5.0

package/llms-instructions/guidelines/PersistentBanner.guidelines.md

@@ -0,0 +1,33 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   For global messages that apply to the entire application, not a specific page or section
+-   When the message must stay visible until the user dismisses it or the condition resolves
+-   For billing, subscription, or plan-level notices that affect access across the app
+-   App-wide service announcements, outages, or planned maintenance
+
+## When Not to Use
+
+-   For page- or section-specific messages — use `InlineBanner` instead
+-   For brief action confirmations — use `Toast` instead
+-   For compact, space-constrained contexts — use `MicroBanner` instead
+
+## Usage
+
+-   Choose a theme that is appropriate to the urgency and context of your message. See the `Themes` page for more information on using themes.
+-   Keep the message brief — PersistentBanner has no title, so the body text must stand alone and be scannable in one line
+-   For buttons use `hollow-contrast` for primary, `link-contrast` for secondary — do not override them
+-   You can make a banner dismissable. Use when the information is non-critical and users can reasonably acknowledge it later.
+-   One at a time — only one Persistent Banner should appear at a time. If multiple messages compete, show the most critical one.
+-   Reserve for app-wide scope — if the message applies only to a specific page or workflow, use Inline Banner instead.
+-   Lead with the issue — state what happened or what is needed before explaining why.
+
+## Additional Rules
+
+-   Use `onDismiss` to let the user close the banner. When provided, a close button appears automatically. Managing whether the banner re-appears is the responsibility of the caller.
+    `theme` defaults to "info". Always pass it explicitly.
+-   `theme` defaults to `"info"`. Always pass it explicitly.
+-   `primaryButton` and `secondaryButton` accept `Button` elements. The component forcefully applies `hollow-contrast` to the primary button and `link-contrast` to the secondary button — any `theme` passed on the button itself will be overridden.
+-   `onLoad` fires once on mount — use it to trigger analytics or logging when the banner becomes visible.
+-   `onDismiss` does not hide the banner automatically. The caller is responsible for conditionally rendering the component based on dismissed state.

package/llms-instructions/guidelines/Pill.guidelines.md

@@ -0,0 +1,55 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To show the status of a record — a shift, an employee, a request, an approval
+-   When a list or table row has a state that users need to scan quickly
+-   When status needs to be communicated without interrupting the reading flow of a label or title
+
+## When Not to Use
+
+-   To communicate system or product-level status (feature availability, release stage) — use `Chip` instead
+-   When the status requires more explanation than a short label can provide — use `InlineBanner` or `MicroBanner` or a tooltip alongside it
+-   As a decorative element — every Pill should correspond to a real, meaningful state
+
+## Usage
+
+### Chip or Pill?
+
+Pill and Chip are visually similar and often confused. Use this table to decide which one to reach for:
+
+| Question                                                       | Yes  | No   |
+| -------------------------------------------------------------- | ---- | ---- |
+| Is it in a DataTable?                                          | Pill | Chip |
+| Are there multiple items in a cluster that each have a status? | Pill | Chip |
+| Is the status related to a page, section, card, or menu item?  | Chip | Pill |
+| Is the status something the user can change through an action? | Pill | Chip |
+| Is the status promotional in nature?                           | Chip | Pill |
+| Can the item be created, edited, or deleted?                   | Pill | Chip |
+
+### Themes
+
+Pill's theme controls its colour and signals the nature of the status at a glance. Use themes consistently across the product so users learn to read them quickly:
+
+| Theme     | Use                                   | Examples                                        |
+| --------- | ------------------------------------- | ----------------------------------------------- |
+| `default` | Neutral or unclear state              | Pending, Unavailable, Inactive                  |
+| `success` | Positive or active state              | Active, Approved, Available, Connected, Enabled |
+| `danger`  | Critical or negative state            | Declined, Deleted, Closed, Errors               |
+| `warning` | Cautionary or at-risk state           | Expiring, Overdue, Needs Attention              |
+| `info`    | Something has changed or been updated | Modified, Updated                               |
+| `upsell`  | Premium or gated content              | Pro, Premium                                    |
+
+## Tips & Tricks
+
+-   Pill content is almost always a short status label — one to three words.
+-   Use themes consistently. If "Approved" is always `success` green in one part of the product, it should be everywhere. Inconsistent theme use erodes the visual language users learn to rely on.
+-   Pill and Chip look alike but mean different things. Ask: is this the state of a record in the system, or the state of a product feature? Record → Pill. Feature → Chip.
+-   Avoid using more than one Pill per row in a dense list unless each one describes a genuinely different dimension of that record. Multiple pills per row adds visual noise and competes for attention.
+-   Default (grey) is for genuinely neutral states — not a fallback when you're unsure which theme to use. If the state has a clear positive or negative valence, pick the right colour.
+
+## Additional Rules
+
+-   `theme` defaults to `default` if not specified.
+-   When `children` is a string or non-numeric value, an `alphabetical` style variant is applied automatically for appropriate letter-spacing and padding.
+-   Pill accepts a forwarded ref, making it usable as an anchor for tooltips or popovers when additional context is needed.

package/llms-instructions/guidelines/Popover.guidelines.md

@@ -0,0 +1,42 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When a short task is directly tied to a specific element — editing contact details on a profile row, configuring an option on a widget
+-   When a user needs to interact with content, not just read it — buttons, forms, or selections that relate to the trigger
+-   When a modal would feel like overkill — the task is lightweight and doesn't require the user's full, undivided attention
+-   For micro-flows of one or two steps that are part of a larger workflow
+
+## When Not to Use
+
+-   For complex multi-step flows — if the task has more than a couple of steps or requires significant decision-making, use a `Modal`
+-   For read-only information with no interaction needed — use a `Tooltip` instead
+-   As a replacement for a `Dropdown` when the content is simply a list of actions — `Dropdown` is the right tool for action menus
+-   When the content is so large it obscures a significant portion of the page
+
+## Usage
+
+### Content
+
+Popover is an intentionally open canvas — it doesn't prescribe a structure the way Modal or Dropdown does. You build the content yourself using whatever layout and components the task requires. Keep the content focused on a single task or piece of information. If you find yourself adding tabs or multiple distinct sections, the task has outgrown the Popover.
+
+### Trigger behaviour
+
+Like Dropdown, Popover accepts a `trigger` element and opens on click or hover. Click is strongly preferred for interactive content — hover triggers are difficult to use on touch devices and can be accidentally triggered.
+
+### Placement and alignment
+
+The popover panel positions itself relative to the trigger. Use `alignment` to control which side it opens on when the default causes overflow or covers adjacent content.
+
+## Tips & Tricks
+
+-   Think of Popover as the middle ground on the disruption scale: more capable than a Tooltip, lighter than a Modal. If your content is purely informational, reach for Tooltip. If it needs a decision, reach for Modal. If it needs light interaction in context, Popover is the right fit.
+-   Popovers work best when they feel attached to what triggered them — keep content tightly focused on the element the user clicked.
+-   Never chain Popovers — opening a second Popover from inside a Popover adds complexity that's hard for users to navigate. If a task has branching paths, escalate to a Modal.
+-   If you're unsure whether to use a Dropdown or a Popover: Dropdown is for lists of actions. Popover is for everything richer than that.
+
+## Additional Rules
+
+-   `trigger` is required and must accept a forwarded ref.
+-   Popover and Dropdown share the same underlying positioning API — the distinction is in what goes inside, not how they open.
+-   Content is rendered as an open `children` slot — use layout components like `Stack` and `Inline` to structure the panel contents.

package/llms-instructions/guidelines/ProgressBar.guidelines.md

@@ -0,0 +1,35 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To show progress through a multi-step flow — onboarding, setup wizards, form sequences
+-   File uploads or processing operations where percentage completion is quantifiable
+-   Stepped checkout or configuration flows that benefit from named checkpoints (e.g. "Step 1", "Invite Team")
+-   When a horizontal format fits the layout better than a circular indicator
+
+## When Not to Use
+
+-   When progress is circular or needs to be displayed compactly — use `CircularProgress` instead
+-   When there is no meaningful progress to communicate — do not use as a decorative element
+-   When the total amount of work/steps is unknown
+-   When communicating pass/fail or complete/incomplete status
+
+## Usage
+
+Supports two modes: Simple and Stepped
+
+### Simple
+
+A continuously filling bar. Progress is treated as a percentage by default, or against a custom max value.
+
+### Stepped
+
+The bar fills to the center of the active step, anchoring the indicator to a discrete position. With step labels enabled, text labels render below the bar — one per step, evenly distributed across the full width.
+
+### Best Practices
+
+-   Use `maxValue` without `steps` when progress is a raw number rather than a step index — for example, `progress={35}` out of `maxValue={100}` for a percentage.
+-   Keep step labels short so they fit evenly below the bar without wrapping.
+-   Step labels should be short noun phrases: "Step 1", "Account Setup", "Invite Team". Avoid full sentences.
+-   Keep label style consistent across all steps in a given bar — do not mix "Step N" style labels with verbose descriptive labels in the same instance.
+-   Labels use sentence case.

package/llms-instructions/guidelines/SegmentedControl.guidelines.md

@@ -0,0 +1,21 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   In a toolbar to switch between two or three distinct views of the same content (e.g. Day / Week / Month)
+-   When the options are mutually exclusive and switching between them is immediate
+-   When all available options should be visible at a glance rather than hidden in a dropdown
+
+## When Not to Use
+
+-   When you are switching between sub-pages - use a tab instead.
+-   When the entire content of the page is switching - use a tab instead.
+-   When there are too many options to comfortably fit in the frame.
+-   When the user is submitting a value as part of a form — use a radio group instead.
+-   When the options trigger an action rather than change a view — use a `Button` group instead
+
+## Usage
+
+-   You may include as many items as necessary and will fit in your frame, however the SegmentedControl should never be longer than the component it is controlling.
+-   Keep option labels short — one or two words. The control is sized to its content, so long labels create an unbalanced layout.
+-   Use nouns or short noun phrases that describe the view, not verbs — "Day", "Week", "Month", not "Show Day", "Show Week".

package/llms-instructions/guidelines/Skeleton.guidelines.md

@@ -0,0 +1,30 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When loading a page, list, table, or card where the layout is known in advance
+-   When the loading duration is long enough that a blank area would feel broken
+-   To prevent layout shift — match the skeleton dimensions closely to the content that will replace it
+
+## When Not to Use
+
+-   For short, unpredictable loading operations — use `Spinner` instead
+-   As a permanent placeholder — it should always be replaced by real content once loading is complete.
+-   When the layout of the loading content is unknown — a rough skeleton is better than no skeleton, but if the shape would be misleading, use `Spinner`
+
+## Usage
+
+-   Use `as` to match a specific Sous Chef component shape. When no preset fits, use `height` and `width` to size it manually.
+    -   `avatar` - Circular avatar at various sizes
+    -   `button` - Button-shaped rectangle
+    -   `pill` - Pill/badge shape
+    -   _(none)_ - Plain rectangle — size with `height` and `width`
+
+*   Build skeleton layouts that closely match the structure of the real content — a row of skeletons for a list, a wide block for a heading, narrower blocks for body text
+*   The loading animation is intentionally delayed by 3.5 seconds to avoid a flash on fast loads
+
+## Additional Rules
+
+-   When `as` is not provided, `height` and `width` must be set manually — an unsized skeleton collapses to zero height.
+-   `height` and `width` accept a number (pixels) or a string with units (e.g. `"75%"`, `"2rem"`).
+-   `as` and manual sizing can be combined — `as` sets the shape, and `height`/`width` override the default dimensions of that shape if needed.

package/llms-instructions/guidelines/Spinner.guidelines.md

@@ -0,0 +1,32 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When an operation is in progress and the user must wait — submitting a form, fetching data, processing a request
+-   As a loading state inside a `Button` (handled automatically by `Button`'s `loading` prop)
+
+## When Not to Use
+
+-   When loading a page or a structured list of content — use `Skeleton` instead, which reduces layout shift and sets better expectations
+-   When no async operation is happening — never show a spinner for decorative purposes
+-   loading times are expected to be more than a few seconds. If a spinner is used for a longer load time it can appear to be "stuck" even when its not.
+-   If load times are going to be more than a few seconds we should communicate how long the expected wait time will be.
+
+## Usage
+
+-   The default `size` of 28px suits most contexts. Increase it only when the spinner needs to fill a large empty area.
+-   Spinners have their own unique set of themes. These differ from the semantic themes that apply to other components like banners.
+
+| Theme      | When to use                                                              |
+| ---------- | ------------------------------------------------------------------------ |
+| `mint`     | Standard backgrounds (default)                                           |
+| `contrast` | Inverse-coloured surfaces that require more visual contrast              |
+| `disabled` | Inside a disabled element such as a disabled `Button` in a loading state |
+| `pride`    | Seasonal spinner that is active during pride month (June 1-30)           |
+
+## Additional Rules
+
+-   `Button` manages its own spinner internally via the `loading` prop — do not place a `Spinner` inside a `Button` manually.
+-   `theme` defaults to `"mint"`
+-   `block` defaults to `false`. Pass `block={true}` when centring in a container, rather than wrapping the spinner in a custom centering div.
+-   `size` is in pixels and defaults to `28`. Do not pass fractional values.

package/llms-instructions/guidelines/Toast.guidelines.md

@@ -0,0 +1,34 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To confirm that an action completed successfully — "Schedule published", "Changes saved"
+-   To notify the user of an error that occurred as a result of an action they just took
+-   When the message is transient and the user does not need to act on it
+-   When an optional follow-up action (like "Undo") is available
+
+## When Not to Use
+
+-   When the message requires the user to read and respond before continuing — use a modal or `InlineBanner` instead
+-   When the message is persistent and must remain visible — use `InlineBanner` or `PersistentBanner` instead
+-   When the message is not triggered by a user action — use a banner instead
+-   For validation errors on a form — show errors inline on the field instead
+
+## Usage
+
+### Behaviour
+
+-   Toast dismisses on its own — the user does not need to interact with it.
+-   Toasts are automatically always placed 32px from the bottom of the screen, and are centred left and right.
+-   If an action is easily undoable, then provide the user the option to undo.
+
+### Best Practices
+
+-   Use `theme="default"` for confirmations and neutral notifications. Use `theme="danger"` for errors.
+-   Toasts should be fired after an action has occurred, such as clicking a submit button in a form.
+-   Make sure to call toast at least one component level below the `<SousChefProvider>`.
+
+### Copy Writing
+
+-   Keep toast messages to one short sentence — the user only has a few seconds to read it
+-   Write in past tense for confirmations ("Schedule published") and plain present tense for errors ("Something went wrong")

package/llms-instructions/guidelines/Toggle.guidelines.md

@@ -0,0 +1,19 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To enable or disable a feature or preference that takes effect immediately
+-   When the on/off state is clear and the consequence is easily reversible
+-   When a single boolean setting needs to stand on its own outside of a form
+
+## When Not to Use
+
+-   Inside a form that requires a submit action to save — use a `Checkbox` instead
+-   When the user is selecting one option from a group of mutually exclusive choices — use a radio group instead
+-   When more than two states are needed — use a `Select` or `SegmentedControl` instead
+
+## Usage
+
+-   The label should describe the feature or setting being controlled, not the state — "Email notifications", not "Turn on email notifications"
+-   Use `caption` to add a short supporting sentence when the label alone may not be enough to communicate the consequence of toggling
+-   Avoid using Toggle for settings where the effect is delayed or requires confirmation — the visual design implies immediate action

package/llms-instructions/guidelines/ToolbarSelect.guidelines.md

@@ -0,0 +1,22 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   In a page toolbar or a component toolbar to filter content by a single dimension — location, role, status, etc.
+-   When the option list is too long for a `SegmentedControl`
+-   When options need to be grouped or some options need to be individually disabled
+
+## When Not to Use
+
+-   Inside a form — use `SelectField` instead
+-   When the selection should trigger an action rather than filter content — use a `Button` or `DropdownButton` instead
+-   When the user needs to select multiple values — use a multi-select form field instead
+-   When there are only 2 or 3 static ungrouped actions - use a `SegmentedControl` instead
+
+## Usage
+
+-   Always place ToolbarSelect in a toolbar alongside other filters and controls, not inline within page content
+-   Use `prefix` to add an icon before the selected value, which helps identify what the filter controls at a glance — especially useful when multiple ToolbarSelects appear in the same toolbar
+-   Use `placeholder` to indicate what the filter represents when no selection has been made — e.g. "All locations", "All roles"
+-   Use grouped options (`WithDropdownGroups`) when the option list has a natural category structure that helps the user scan and find the right choice faster
+-   Use `creatableButton` sparingly — only when the user legitimately needs to add new options on the fly as part of their workflow

package/llms-instructions/guidelines/Tooltip.guidelines.md

@@ -0,0 +1,45 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To label an icon-only button or control where the action isn't immediately obvious
+-   To define an unfamiliar term, metric, or abbreviation — things like "SPLH" that not every user will know on sight
+-   To show additional metadata that is helpful but not essential to the main task
+-   To provide extra context for a truncated label or condensed data point
+
+## When Not to Use
+
+-   For critical information the user must see to complete a task — don't hide required context behind a hover
+-   When the content needs buttons, links, or any interactive element — use a `Popover` instead
+-   When the explanation is more than one or two lines — if it takes a paragraph, it belongs in a help article or inline copy
+-   As a workaround for unclear UI copy — if something needs a tooltip to be understood, first ask whether the label itself can be improved
+
+## Usage
+
+### Content
+
+Keep it short — one line is ideal, two is the limit. Write in plain, direct language. If you need a heading alongside the content, the `header` prop adds a bold label above the body text.
+
+### Themes
+
+Tooltip always use the inverse theme the product is using. If the product is in `light mode` the tooltip will be dark. If the product is in `dark mode` the tooltip will be light. This helps give it enough contrast to stand out from the background.
+
+### Placement
+
+The tooltip appears above or below the trigger by default, and will reposition itself automatically based on available screen space. You can suggest a preferred `placement` (`top` or `bottom`), but the component may override it to keep the tooltip on screen.
+
+### Delays
+
+`delayOnOpen` adds a small pause before the tooltip appears — useful when a trigger is near other interactive elements and you want to avoid tooltips flashing as the user moves between them. `delayOnClose` keeps the tooltip open briefly after the user moves away, which is helpful when the overlay itself contains selectable text or a link (only relevant for the white theme with `delayOnClose`).
+
+## Tips & Tricks
+
+-   Every icon-only button should have a tooltip. "What does this button do?" is a question a tooltip can always answer.
+-   Don't rely on tooltips to rescue confusing UI. If every element on a page needs a tooltip to be understood, the interface needs redesigning, not more tooltips.
+-   Avoid putting the same text in both the visible label and the tooltip.
+
+## Additional Rules
+
+-   `overlay` is the content prop — it accepts text or JSX, but keep interactive elements out of tooltips unless you're using `delayOnClose` intentionally.
+-   Tooltip wraps its `children` as the trigger — whatever element is passed as children becomes the hover anchor.
+-   The component repositions automatically to stay on screen; the `placement` prop is a preference, not a guarantee.