@7shifts/sous-chef 4.4.1 → 4.5.0

package/dist/overlay/DropdownListItem/DropdownListItem.d.ts

@@ -17,6 +17,8 @@ type Props = {
     reloadDocument?: boolean;
     submenu?: React.ReactNode;
     onSubmenuOpen?: () => void;
+    /** When true, and a suffix is provided, clicking the suffix will open the submenu instead of the default chevron behavior. */
+    openSubmenuOnSuffixClick?: boolean;
 };
-declare const DropdownListItem: ({ onClick, prefix, suffix, caption, selected, disabled, testId, children, href, target, reloadDocument, submenu, onSubmenuOpen: onSubmenuOpenCallback, isSelectable }: Props) => React.JSX.Element;
+declare const DropdownListItem: ({ onClick, prefix, suffix, caption, selected, disabled, testId, children, href, target, reloadDocument, submenu, onSubmenuOpen: onSubmenuOpenCallback, isSelectable, openSubmenuOnSuffixClick }: Props) => React.JSX.Element;
 export default DropdownListItem;

package/dist/overlay/hooks/useSubmenu.d.ts

@@ -11,6 +11,7 @@ export declare const useSubmenu: ({ hasSubmenu, disabled }: Config) => {
     submenuDirection: SubmenuDirection;
     closeSubmenu: () => void;
     openSubmenu: () => void;
+    closePreviouslyOpenSubmenus: () => void;
     itemRef: import("react").RefObject<HTMLDivElement>;
     submenuRef: import("react").RefObject<HTMLDivElement>;
     isOpen: boolean;

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

@@ -0,0 +1,36 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When you have multiple sections of related content that don't all need to be visible at once
+-   To reduce page length and visual noise by letting users expand only what they need
+-   For FAQ-style content where each item has a question and a detailed answer
+-   When secondary or supporting information would clutter the layout if always shown
+
+## When Not to Use
+
+-   When users are likely to need to compare content across multiple sections — showing everything at once works better
+-   When there are only one or two items — collapsing a single piece of content adds friction without benefit
+-   When the content inside is short enough to always display inline without overwhelming the layout
+
+## Usage
+
+### Content
+
+-   Keep titles short and scannable — users read the title to decide whether to expand. Front-load the most meaningful word.
+-   Content inside each section can be customizable with rich content like: text, links, lists and components.
+-   Titles can also be React nodes, which is useful for adding a visual indicator like a pill or badge alongside the label.
+
+### Behaviour
+
+-   Only one section can be open at a time. Opening a new section closes the current one - This behaviour cannot be overridden, however, an alternative solution is to create multiple single item accordions in a list. This should only be considered in niche cases, but can be useful for things like FAQ sections.
+-   You may define an accordion item to be open by default when a page loads.
+-   Individual items can be targeted via URL hash by passing a unique `id` to that item. When the page loads with a matching anchor in the URL, that section opens automatically. Use this when you need to link directly to a specific accordion item from elsewhere in the app.
+
+## Additional Rules
+
+-   Only one section can be open at a time. Opening a new section closes the current one — this is not configurable.
+-   If `items` is an empty array, the component renders nothing.
+-   Item `id` defaults to the item's index if not provided. Provide an explicit `id` when using anchor linking to ensure stable URLs.
+-   `onExpand` fires when an item is opened, receiving the full item object. It does not fire when an item is closed.
+-   `defaultOpenId` must match an item's `id` value (or its index as a string) to have any effect.

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

@@ -0,0 +1,59 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To surface a set of tasks or recommended actions the user should complete — such as an onboarding checklist, daily tasks in an action center, steps to set up a new product or workflow, or any other to-do list.
+-   When each item in the list has a distinct status or urgency that can be communicated with a theme
+-   When items have individual actions that are separate from navigating to the item
+-   For items that can be completed and cleared by users.
+
+## When Not to Use
+
+-   For general navigation menus — use a `Dropdown` or sidebar navigation instead
+-   For tabular data where rows represent records — use `DataTable` instead
+-   For a simple list of options the user picks from — use `SelectField` or `RadioGroupField` instead
+-   For static non-interactive lists - use a standard bulleted or numbered list instead.
+
+## Usage
+
+### Best Practices
+
+-   `ActionListItem` ALWAYS requires a title and an icon.
+-   `ActionListItem` can be disabled if they are not currently available. Use this to hint at a task a user may need to complete in the future but can’t yet, or for tasks that have already been completed.
+-   You can include supplementary metadata between the item text and its action buttons using the suffix prop. Use this for things such as an estimated time, a count, or a status indicator.
+-   In some cases, you may want to show an empty action list, instead of hiding the list completely. For example, a daily to-do list on a dashboard where there are no more tasks to complete today, but more may appear tomorrow. Keeping an `empty state` here protects the space, and reassures the user that they are not missing any important tasks. It's also OK to hide a list when completed. Designers can choose based on the context of the experience.
+-   Each item can be made interactive in two ways and both can coexist at the same time:
+    -   Single action — The entire row is clickable. A chevron appears on the right to indicate it's navigable. (pass `onAction` to use)
+    -   Multiple actions — Instead of the entire item being interactive, you can include multiple separate actions (pass an `actions` array to do so). Each action can be shown as a button (of any theme) or tucked into a kebab menu using `showInKebab`. Use this when there are multiple paths the user can take from the task, or if the task is optional and can be completed or dismissed.
+
+### ActionList as a checklist
+
+If you are using `ActionList` as a basic checklist, do the following:
+
+-   Incomplete `ActionListItems` should be the `info` theme (use neutral once neutral has been added) and use `IconCheckCircleIncomplete` as the icon.
+-   Complete `ActionListItems` should be the `success` theme and use `IconCheck` as the icon.
+
+![ActionList checklist example](/images/checklist.png)
+
+### Themes
+
+-   Each `ActionListItem` has a `theme` prop that controls the icon color. Use themes to communicate the nature or urgency of the item.
+-   The theme will default to `info` if not specified otherwise.
+
+| Theme     | Use                                            |
+| --------- | ---------------------------------------------- |
+| `info`    | Default. Neutral informational tasks.          |
+| `success` | Completed or positive status items.            |
+| `warning` | Items that need attention but aren't blocking. |
+| `danger`  | Urgent or error-state items.                   |
+| `upsell`  | Items promoting a feature or upgrade.          |
+| `neutral` | De-emphasized items with no specific status.   |
+
+## Additional Rules
+
+-   `disabled` on an `ActionListItem` suppresses `onAction`, grays out the icon, and prevents hover interaction. Action buttons are also disabled.
+-   Each action in the `actions` array requires a unique `action` key for proper indexing.
+-   `showInKebab: false` on an action renders it as an inline button. Actions without this flag (or with `showInKebab: true`) appear in a kebab menu.
+-   `buttonProps` on an individual action accepts a subset of `Button` props (`theme`, `disabled`, `loading`, `title`, `testId`) to customize that button's appearance.
+-   The `ActionList` itself accepts an optional `title` prop for a header above the list. This can be any React node, making it easy to pair a heading with a secondary action (e.g. a "Show more" button) using `Inline`.
+-   When no `ActionListItem` children are passed, the component renders an empty state automatically. Provide a custom `emptyState` with a `title` and optional `caption` and `actions` to tailor the message to the specific context.

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

@@ -0,0 +1,51 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To represent a person in a list, table row, or header — such as an employee name, a shift assignee, or a message sender
+-   To represent an entity such as a role, department, location, or company alongside its name
+-   When a profile photo or brand image is available and adds recognition value
+-   As an indicator of the current logged in user or account being viewed
+
+## When Not to Use
+
+-   As a decorative element with no connection to a real person or entity
+-   In place of an icon when the context has nothing to do with identity
+
+## Usage
+
+### Content
+
+Avatars can display different kinds of content. Within 7shifts, the entity being displayed defines the content displayed:
+
+-   **For people** - Uses a photo if available. If not, fallback to the `default`
+-   **For Roles** - Uses a single initial
+-   **For Departments** - Use an icon
+
+### Sizes
+
+Avatars come in four sizes: `small`, `medium`, `large`, and `extra-large`. Choose the size based on how prominent the identity needs to be and what works in your layout.
+
+### Colour
+
+When showing initials or an icon, a background colour can be applied to the avatar. For entities like roles and departments that already have an assigned colour in the system, use that colour here to reinforce the visual identity and aid quick recognition. `default` avatars for users who have not added a photo are random.
+
+### Badge
+
+A badge can be overlaid on the avatar to surface supplementary information — an action, a status indicator, or a count. The badge sits in the bottom-right corner of the avatar. Badges are not shown on `small` avatars as there is not enough space.
+
+## Tips & Tricks
+
+-   When representing entities like roles or departments, using the entity's assigned colour as the avatar background creates immediate visual continuity with how that entity appears elsewhere in the product.
+-   Avoid using avatars on their own without a label if possible. In most cases an avatar on its own is not enough detail to identify a person or entity.
+-   The `extra-large` size is best reserved for dedicated profile or detail contexts — a settings page, an employee profile, a company detail view. Using it in a list or table will overpower the surrounding content.
+-   When pairing an avatar with a name in a row or list, the avatar should always sit to the left of the text. Use `Inline` with `alignItems="center"` to keep them vertically centred.
+-   Always pass an `alt` prop when using a photo or image URL — use the person's name or entity name so screen readers can identify what is shown.
+
+## Additional Rules
+
+-   `size` defaults to `medium` if not specified.
+-   `children` takes priority over `url` — if both are provided, the children render and the image is ignored.
+-   Badges do not render when `size="small"`. This is intentional and cannot be overridden.
+-   Images are lazy-loaded and only fetched when the avatar enters the viewport.
+-   If the image URL returns an error, the avatar falls back to a generated illustrated placeholder — not a broken image.

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

@@ -0,0 +1,40 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To show a count or quantity associated with an element — unread notifications, pending items, or a number of things requiring attention
+-   To surface a quick action on an avatar or icon — such as an edit button overlaid on a profile photo
+-   To signal a status on an element where a full label would take up too much space
+
+## When Not to Use
+
+-   As a standalone element — Badge is always paired with something it annotates
+-   When the information is important enough to need a label or explanation — use `Chip` or `Pill` for labelled status indicators instead
+-   When you need to communicate a full message or category — `Chip`, `Pill` or `InlineBanner` are better suited
+
+## Usage
+
+### Content
+
+Badge accepts any content — a number, an icon, or short text. Numbers are the most common use case, typically showing a count of items. Icons work well when the badge represents an action rather than a quantity, such as an edit or alert indicator. Keep content minimal — the badge is small and dense content becomes illegible quickly.
+
+### Themes
+
+Badge supports 5 themes that change its background colour: `default`, `success`, `danger`, `warning`, and `info`. Use these to reinforce the meaning of what the badge is communicating.
+
+### Tooltip
+
+When a badge contains only an icon or a number that may not be self-explanatory, a tooltip should be added to clarify what it means.
+
+## Tips & Tricks
+
+-   Badges with numbers work best for counts under 100 — if the count can go higher, consider capping the display at "99+" to prevent the badge from growing too wide.
+-   Icon badges are ideal for edit or camera actions on avatars — they communicate "you can change this" without needing any text.
+-   Badge is intentionally minimal — resist the urge to put too much inside it. If you need more than a number or a single icon, you probably want a `Pill` or `chip` instead.
+
+## Additional Rules
+
+-   When `children` is a finite number, a `badge--numeric` style is applied automatically for appropriate sizing.
+-   When `children` is a React element (e.g. an icon), the badge height is set to match its width to keep it circular.
+-   `theme` is optional — without it the badge renders in its default neutral colour.
+-   `title` renders as a `Tooltip` overlay on hover. It does not render any visible label at rest.

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

@@ -0,0 +1,41 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When a page is nested within a parent section and the user may need to navigate back — for example, an employee detail page nested under the Employees list
+-   When the navigation path has two or more levels and the parent context is meaningful
+-   When the user arrived at the current page by drilling down from a list or overview
+
+## When Not to Use
+
+-   On top-level pages that have no meaningful parent to navigate back to
+-   When there is only one level of depth — a single back link adds little value over the browser's back button
+-   As a way to show full site hierarchy for its own sake — only include levels the user genuinely needs to navigate back through
+
+## Usage
+
+### Structure
+
+Each item is a clickable link with a back chevron, representing one level in the navigation path. The last item in the list represents the most immediate parent — the page the user would go back to. Each `BreadcrumbItem` requires an `href` and a label.
+
+### How Many Items to Show
+
+Include only the levels that are genuinely navigable and useful as context. A single item pointing to the immediate parent is the most common case. Multiple items are appropriate when the page is several levels deep and each level is a meaningful destination in its own right — for example, Company Settings → Billing when on a billing detail page.
+
+### Labels
+
+Use the name of the destination page as the label — the same name that appears as the heading on that page. Keep labels short and consistent with how the section is named elsewhere in the product.
+
+## Tips & Tricks
+
+-   Breadcrumbs work best when there is only one logical parent. If a page can be reached from multiple places, choose the most common or expected parent as the breadcrumb destination rather than trying to show all paths.
+-   The current page should never appear as a breadcrumb item — only the pages above it in the hierarchy. The page heading already tells the user where they are.
+-   Breadcrumbs are a secondary navigation aid, not a primary one. Don't rely on them as the only way to get back — make sure the parent page is also reachable from the main navigation.
+-   When in doubt about whether to show one breadcrumb item or two, lean toward fewer. One clear "back to X" link is almost always more useful than a full ancestry trail.
+
+## Additional Rules
+
+-   `Breadcrumbs` requires `react-router-dom`'s `Router` to be present higher in the component tree.
+-   Breadcrumbs are built from a `Breadcrumbs` wrapper containing one or more `BreadcrumbItem` components.
+-   Each `BreadcrumbItem` renders as a `react-router-dom` `Link` by default, using client-side routing. Pass `reloadDocument` to force a full browser navigation instead — use this when linking to a page outside the current router context.
+-   The back chevron icon is rendered automatically by `BreadcrumbItem` — do not add one manually in the label.

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

@@ -0,0 +1,41 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To submit a form or confirm a decision — "Save Changes", "Publish Schedule", "Confirm Swap"
+-   To trigger an in-page action such as creating, updating, or removing a record
+-   To execute a command with an immediate, visible consequence
+-   To launch a new flow or complete a flow
+
+## When Not to Use
+
+-   When the action is purely navigational — use `Link` instead
+-   When the action lives inline inside a sentence or body copy — use `Link` instead
+-   When the user is choosing between options rather than triggering something — use `Select`, a radio group, or `SegmentedControl` instead
+
+## Usage
+
+### Best Practices
+
+-   Prioritize the most important actions. Too many calls to action can cause confusion and make users unsure of what to do next.
+-   Use established themes appropriately. For example, use the danger theme for an action that will result in the removal of something which cannot be undone.
+
+### Copy
+
+-   Use sentence case with the exception being proper nouns use title case (E.g. a person, feature name, location)
+-   Aim to be clear, concise, predictable and lead with a strong, actionable verb
+-   Be concise. When possible refrain from using more than three words.
+-   If your button copy ends up being a sentence, pull the rest of the copy out of the button and just keep the verb.
+-   Be clear and predictable. Users should be able to anticipate what will happen when they select a button.
+
+### Layout
+
+-   Buttons in a button group have 12px spacing between them, with the exception being icon-link themed buttons which have 0px spacing.
+-   Position buttons in consistent places depending on the context they are in (e.g. side card, form or modal footer, toolbar page actions)
+-   In a ButtonGroup, primary actions should always be the right-most button.
+-   Buttons with text should always have a minimum width of 100px. This does not apply to `link-icon` buttons
+
+## Additional Rules
+
+-   Icon-only buttons (link-icon) must always have a tooltip so the action is clear to all users.
+-   Only one theme="primary" button should appear per view, modal, or drawer at a time.

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

@@ -0,0 +1,40 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   When you need a date picker that sits outside a standard form — for example, a date selector in a toolbar or a scheduling interface
+-   When the trigger element is custom and can't use the built-in `DateField` input
+-   When you need week-based selection rather than a single day
+
+## When Not to Use
+
+-   Inside a form alongside other fields — use `DateField` or `DateRangeField` instead, which handle the input, label, and validation together
+-   When users need to select a date range — Calendar selects a single day or week; use `DateRangeField` for ranges
+-   As a persistent visible element — Calendar is an overlay and should open and close in response to a trigger
+
+## Usage
+
+### Modes
+
+Calendar supports two selection modes. In `day` mode (the default), the user picks a single date. In `week` mode, clicking any day selects the entire week — always anchored to the first day of the week based on the `weekStart` setting. Use week mode in scheduling and shift-planning contexts where the user is thinking in weekly increments.
+
+### Anchoring
+
+Calendar positions itself relative to the trigger element. It opens below the anchor by default, but will reposition to the top automatically if there isn't enough space below. The `position` prop lets you express a preference, but the component may override it to keep the picker on screen.
+
+### Disabled days
+
+Use `disabledDays` to prevent selection of dates that aren't valid choices — past dates, dates outside a booking window, or dates already taken.
+
+## Tips & Tricks
+
+-   Use `initialMonth` to open the calendar at a relevant month when the context implies one — for example, opening at the month of the currently selected date rather than always defaulting to today.
+-   Disabled days should feel visually obvious. Don't rely solely on click prevention — ensure the styling makes it clear which dates are selectable at a glance.
+
+## Additional Rules
+
+-   `anchorRef` is required — Calendar uses it to position the overlay relative to the trigger element.
+-   `onSelect` and `onClickOutside` are both required; Calendar does not manage its own visibility.
+-   `mode` defaults to `"day"` if not specified.
+-   `position` defaults to `"bottom"` but will be overridden if the calendar doesn't fit in the chosen direction.
+-   In `week` mode, `onSelect` always receives the first day of the selected week, adjusted for `weekStart`.

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

@@ -0,0 +1,58 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To visually group a related piece of content or a selectable option
+-   When content needs to be visually separated from the surrounding layout without using a modal or drawer
+-   Selectable cards: when presenting a number of items cards the user can choose between. We should only use selection cards in this way when:
+    -   There are a small number of options
+    -   We need significant visual emphasis on the choice.
+    -   The content is too robust for a drop down or radio - maybe it needs supporting images or longer content.
+
+## When Not to Use
+
+-   As a general-purpose layout wrapper — use `Stack`, `Inline`, or a plain `div` for structural spacing
+-   When the content is purely informational and doesn't benefit from a bordered container
+-   As a substitute for a table row when data is tabular — use `DataTable` instead
+-   To communicate a single message/action to the user such as an error or success state - use `InlineBanner` or `MicroBanner` instead
+
+## Usage
+
+### General Use
+
+-   In general, cards are simple container components. They can hold any content or components the designer needs them to, while providing a consistent visual treatment including a border, padding and corner radius.
+-   Cards may be freely stacked vertically or put in a row horizontally as needed.
+-   You may use a card within a card, but do so with caution. Too many nested cards can confuse the layout.
+-   You can modify cards by making them: interactive, selectable, dismissible or by adding an action menu.
+    `Card` expands to fill its parent container. Control its size by constraining the parent — do not set width directly on the Card.
+-   Several other components can use the `as card` prop, which automatically puts them inside a card such as `EmptyState` and `Paywall`. These items should use the `as card`, and not be placed inside a card manually.
+
+### Interactive Cards
+
+-   Use this when you want the whole card to be a single selectable action.
+-   A `Card` becomes interactive when passed an `onClick` prop. This renders the card body as a `<button>` element, making it keyboard accessible and giving it hover and focus styles.
+
+### Selectable Cards
+
+When presenting a group of options the user can pick from, pair `onClick` with `isSelected` to track and reflect the chosen state. Only one card in a group should be selected at a time unless multiple selections are intentionally supported.
+
+### Actions Menu
+
+-   You can include an action menu on a card.
+-   This adds a kebab icon to the top right corner that triggers a `Dropdown` overlay component on click. This acts as a menu for the specific cards and can contain any actions or options needed to control the card and its content - such as hide, delete, duplicate, share, etc.
+-   See `Dropdown` for guidelines on how to design and build the menu.
+
+### Dismissible Cards
+
+-   Adds an `X` to dismiss the card. When clicked this will remove the card from the interface.
+-   If a card needs to be both dismissible and have an action menu, then by default a “Dismiss” action will be added to the action menu.
+
+## Additional Rules
+
+-   Pass the actions prop to add a kebab menu to the top-right corner of the card. Each action requires an action key, a label, and an onAction callback. Use this when the card has secondary actions that shouldn't be triggered by clicking the card itself.
+    `onClick` is required to make the card interactive. Without it, the card renders as a `div` with no interactive behavior.
+-   `isSelected` has no effect unless `onClick` is also provided.
+-   When both `actions` and `onClose` are passed, the "Dismiss" option is injected into the actions menu — a separate close button will not appear.
+-   `disabled` suppresses both `onClick` and the actions menu visually and functionally.
+-   Individual actions within the `actions` array can be conditionally hidden by passing `hidden: true` on that action object.
+-   Pass `onClose` to add a close button to the card. If `actions` is also present, the dismiss option is appended to the actions menu automatically rather than showing a separate close button.

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

@@ -0,0 +1,64 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To flag that a feature is new, in beta, or recently changed — "New", "Beta", "Updated"
+-   To indicate that a feature requires an add-on or upgrade — "Add-on", "Pro", "Premium"
+-   To mark AI-powered features or content
+-   To surface a system-level state associated with a UI element, not a data record
+
+## When Not to Use
+
+-   To show the status of a data record (an employee's status, a shift state, an approval) — use `Pill` instead
+-   When the label needs to be longer than a word or two — Chip is designed for very short labels
+-   As a standalone element without a clear connection to the thing it describes
+
+## 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
+
+Chip's theme controls its colour and communicates the nature of the label. Choose the theme that matches the intent:
+
+| Theme       | Use                                                                   |
+| ----------- | --------------------------------------------------------------------- |
+| `marketing` | Default. New features, beta releases, callouts — "New", "Beta"        |
+| `success`   | Positive system state — feature active, enabled, or working           |
+| `warning`   | Pending or cautionary system state                                    |
+| `danger`    | Critical or negative system state — inactive, deprecated, broken      |
+| `info`      | Informational — something has changed or is worth noting              |
+| `upsell`    | Add-on or upgrade opportunity — "Pro", "Add-on", "Premium"            |
+| `ai`        | AI-powered feature or content — automatically prepends a sparkle icon |
+
+### Icons
+
+An icon can be included alongside the chip's text to reinforce its meaning. Icons passed as children are automatically resized to `small` to fit the chip's compact form. The `ai` theme adds a sparkle icon automatically — no need to add one manually.
+
+### Placement
+
+Chips are always placed in close proximity to the element they describe — typically inline next to a feature name, a nav item, or a section heading. They should feel attached to the thing they annotate, not floating independently.
+
+## Tips & Tricks
+
+-   Keep chip labels to one or two words maximum. "New", "Beta", "Add-on", "AI" — anything longer starts to feel like a tag rather than a status.
+-   The `marketing` theme is the default and the most commonly used. Reserve the other themes for situations where colour carries real meaning — don't use `danger` just for visual variety.
+-   Chip and Pill look similar but mean different things. A quick test: is this describing the state of a product feature, or the state of a data record? Feature → Chip. Record → Pill.
+-   The `upsell` theme is specifically for upgrade prompts. Don't use it just because a feature is valuable — reserve it for features the current user doesn't have access to yet.
+
+## Additional Rules
+
+-   `theme` defaults to `marketing` if not specified.
+-   Any icon passed as a child has its `size` prop overridden to `small` automatically.
+-   The `ai` theme automatically prepends an `IconSparkle` — do not add a second sparkle icon manually when using this theme.

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

@@ -0,0 +1,28 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To show how many items in a set have been completed — tasks finished, steps checked off, items reviewed
+-   When the compact circular format fits the layout better than a horizontal bar
+-   When displaying a count alongside the visual indicator adds clarity
+
+## When Not to Use
+
+-   When progress is linear and benefits from step labels — use `ProgressBar` instead
+-   When there is no fixed total to measure against — CircularProgress requires a defined `maxValue`
+
+## Usage
+
+-   This component lacks context when used on its own. It should always be in context and with a close relationship to whatever it is the CircularProgress is counting.
+-   If there is an action the user can take to change the count, it should be placed close to it so there is a clear visual relationship between the progress and the action.
+-   If the CircularProgress is showing a statistic — like on a dashboard — give it a clear label of what stat it is displaying. If more context is needed, consider adding a description in a tooltip either attached to the CircularProgress or its label
+-   The label will default to 100, but you can change this value or create a custom label inside the ring.
+-   Keep custom labels short — the label area is small and long strings will overflow.
+-   CircularProgress is fairly simplistic and does not have any additional states or label when the bar is empty or complete.
+
+## Additional Rules
+
+-   `maxValue` defaults to `100`, making `progress` a percentage by default. Pass a custom `maxValue` to work with raw counts (e.g. `progress={1}` out of `maxValue={4}`)
+-   `progress` is required.
+-   `children` replaces the default `progress/maxValue` label entirely — if you want to show something alongside the default, build a composite string and pass it as `children`.
+-   `progress` should never exceed `maxValue`.

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

@@ -0,0 +1,88 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
+## When to Use
+
+-   To display a list of records where users need to scan, compare, or act on individual rows
+-   When data has multiple attributes that benefit from column alignment
+-   When users need to sort, paginate, or take actions on individual items
+-   When the number of items may grow and needs scroll or pagination to manage
+
+## When Not to Use
+
+-   For task lists where items require completion — use `ActionList` instead
+-   For a small number of items that don't benefit from column structure — a simpler list or `Stack` may be cleaner
+-   For navigation menus or option pickers — use `Dropdown` or `SelectField` instead
+
+## Usage
+
+### Columns
+
+Each column in a DataTable has a label that appears in the header row, and maps to a key in the row data. Columns can be customised in a number of ways:
+
+-   **Width** — columns can be given proportional sizes so some columns take up more space than others. For example, an employee name column might be twice as wide as a status column.
+-   **Alignment** — numeric data like hours or amounts reads more naturally when right-aligned. Columns can be set to right-align both the header and cell content.
+-   **Sorting** — columns can be made sortable, letting users click the column header to reorder the entire table by that data. Use this for columns where ordering adds value — dates, names, numeric values. Use `isSortable: true` to enable it.
+-   **Toggling visibility** — columns can be shown or hidden without removing them from the data. This is useful for "customise columns" features where users control what they see. Use `hidden: true` on a column to hide it.
+-   **Header tooltips** — a short description can be added to a column header to explain what the data means, shown as a tooltip on hover.
+
+### Sorting
+
+When a column is sortable, clicking its header cycles through ascending, descending, and unsorted states. The sort direction is reflected visually in the column header. You control which column is currently sorted and in what direction — this lets sorting work whether the data is sorted on the front end or fetched pre-sorted from the server.
+
+### Row Content
+
+By default, the table renders each row as plain text using the item's data. For richer rows (avatars, statuses pills, stacked lines, etc) — you can provide a custom row template that fully controls how each cell is rendered while still respecting the column layout.
+
+### Selectable Rows
+
+Rows can be made selectable, highlighting the chosen row with a visual selection state. This is useful when selecting a row opens a detail panel or triggers a contextual action.
+
+### Row Actions
+
+Rows can have per-row actions — things like Edit, Delete, or Approve that apply to that specific record. Actions appear in a kebab menu. Frequently used or high-priority actions can be pulled out of the menu and shown as inline icon buttons instead, keeping them one click away without cluttering the row at rest.
+
+Different rows can have different actions — for example, only showing "Approve" on rows that haven't been approved yet.
+
+### Editable Cells
+
+Individual cells can be made editable inline, turning a read-only table into a lightweight data entry surface. This is useful for things like adjusting hours or tip amounts directly in the table without opening a separate form. Editable cells validate input and support specialised formats like currency.
+
+### Footer
+
+A footer row can be pinned to the bottom of the table to show totals or summaries — useful when the column data is numeric and a running total adds context. The footer stays visible as content scrolls above it, and only appears when there is data to summarise.
+
+### Loading
+
+While data is loading for the first time, the table shows a skeleton animation in place of rows, giving users a sense of the layout before content arrives. On subsequent table updates the content stays visible with a subtle spinner overlay instead of flashing to empty. You can customise the skeleton to match the expected shape of your rows.
+
+### Pagination
+
+When a table contains more records than can be shown at once, pagination controls appear below the table to let users move between pages. The previous and next buttons enable or disable automatically based on whether more pages exist in each direction.
+
+### Scroll
+
+When a table needs to fit inside a constrained space — like a modal or a fixed-height panel — it can be set to scroll vertically within that space. The column headers remain pinned at the top as rows scroll beneath them, so users always know what column they're reading.
+
+### Sticky Columns
+
+For tables with many columns that scroll horizontally, the first and/or last column can be pinned in place. This keeps important context — like an employee name or a row's action buttons — always visible as the user scrolls through the data. Use `stickyColumns` to pin the left, right, or both edges.
+
+## Tips & Tricks
+
+-   The leftmost column should generally act as the label for the row — the thing that identifies what the row is about (an employee name, a date, a record title). Everything else is detail about that thing.
+-   Right-align numeric columns. Numbers are much easier to scan and compare when they share a right edge — hours, amounts, counts, and percentages all benefit from this.
+-   Column widths should reflect the expected content, not split evenly. A short "Status" column doesn't need the same space as a long "Employee Name" column. Use proportional sizes to reflect real content.
+-   Only make a column sortable if sorting by it is actually useful. Sorting by a status or a short code is rarely helpful — sorting by date, name, or a numeric value usually is.
+-   If you find yourself needing sticky columns, it's worth asking whether the table has too many columns. Consider whether some columns can be hidden by default and made available via a "customise columns" control.
+-   The footer is for meaningful aggregates only — totals, averages, counts. Don't add a footer row just to fill the space or repeat a label.
+
+## Additional Rules
+
+-   `columns` is optional. Without it, no header row renders and items are displayed using their raw data keys.
+-   `showActionMenu` must be set on the `DataTable` to reserve the action column's space — even if only some rows have actions.
+-   When using a custom `itemComponent`, wrap each cell in `DataTableCell` so hidden columns are respected. `DataTableCell`'s `columnIndex` must match the column's position in the `columns` array.
+-   Items can include a `key` property to control React reconciliation. If absent, the array index is used.
+-   During `isLoading`, the footer does not render even if `footerComponent` is provided.
+-   Sticky columns prevent text wrapping — cell content will stretch the column rather than wrap to a new line.
+-   Sorting state is owned by the consumer. Use `onSort` to receive the active column and direction, then update items accordingly.
+-   `reverseSortOrder: true` on a column makes the first click sort ascending rather than descending.

package/llms-instructions/guidelines/DateFilter.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 page content (a list, table, or schedule view) needs to be scoped to a specific day, week, or month
+-   When the user needs to step forward and backward through time incrementally
+-   When a single selected date drives what is shown on the page
+
+## When Not to Use
+
+-   When the user is picking a date as input to a form field — use `DateField` instead
+-   When the user needs to select a date range with a start and end — use a date range picker instead
+-   When no filtering or scoping of page content is involved — use `DateField` or a plain calendar overlay instead
+
+## Usage
+
+-   Match `mode` to the granularity of the content being filtered. Use `day` when the view is hourly or daily, `week` when the view spans a full week, and `month` when showing a monthly summary.
+-   Place DateFilter in the page toolbar or at the top of the content it controls, so the relationship between the control and the filtered content is clear
+-   Always keep the filter visible while the filtered content is shown — don't hide it once a date is selected
+
+## Additional Rules
+
+-   `mode` defaults to `"day"`. Always pass it explicitly so the intent is clear at the call site.
+-   In `week` mode, `onChange` receives the first day of the selected week, not the day the user clicked. Account for this when updating state or fetching data.
+-   `weekStart` accepts a day-of-week integer (0 = Sunday, 1 = Monday, etc.). Pass it when the product context uses a non-Sunday week start.
+-   In `month` mode, the calendar popover uses `CalendarMonth` rather than the standard day/week `Calendar`. Direct date selection within the month is not available — only month-level selection.
+
+| Mode    | Display                               | Calendar selection                                                  |
+| ------- | ------------------------------------- | ------------------------------------------------------------------- |
+| `day`   | Single date (e.g. "Sun, Dec 25")      | Day picker                                                          |
+| `week`  | Week range (e.g. "Dec 19 – Dec 25")   | Week picker — `onChange` returns the first day of the selected week |
+| `month` | Month and year (e.g. "December 2022") | Month picker — uses `CalendarMonth`, not the standard day calendar  |