@7shifts/sous-chef 4.4.1 → 4.6.0-beta.0

package/dist/layout/LayoutFrame/LayoutFrame.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { DataProps } from '../../foundation/types';
+type SideNavState = 'expanded' | 'collapsed';
+type SideNavProps = {
+    isExpanded?: boolean;
+    onToggleExpand?: (state: SideNavState) => void;
+};
+type Props = {
+    /** Side navigation, typically a `PrimaryNav`. LayoutFrame manages its expanded state. */
+    sideNav?: React.ReactElement<SideNavProps>;
+    /** Top navigation bar, typically a `TopBar`. */
+    topBar?: React.ReactNode;
+    /** Main page content. Scrolls independently of the nav and top bar. */
+    children: React.ReactNode;
+    /** Whether the side nav starts expanded. Defaults to `true`. */
+    defaultSideNavExpanded?: boolean;
+    /** Called when the side nav is toggled. */
+    onSideNavToggle?: (state: SideNavState) => void;
+    testId?: string;
+} & DataProps;
+/**
+ * Top-level application skeleton with three slots: a side navigation, a top
+ * navigation bar, and the main content area. The side nav and top bar fill the
+ * viewport edges while the content scrolls independently. LayoutFrame owns the
+ * side nav's expanded/collapsed state and wires it into the `sideNav` slot,
+ * unless that slot is already controlled by the consumer.
+ */
+declare const LayoutFrame: ({ sideNav, topBar, children, defaultSideNavExpanded, onSideNavToggle, testId, ...rest }: Props) => React.JSX.Element;
+export default LayoutFrame;

package/dist/layout/LayoutFrame/index.d.ts

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

package/dist/layout/NavButton/NavButton.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { DataProps } from '../../foundation/types';
+type Props = {
+    /** The icon (or any content) rendered inside the button. */
+    children: React.ReactNode;
+    /** Text shown in the tooltip when hovering the button. */
+    tooltipContent: string;
+    onClick: () => void;
+    /** Any node rendered in the top-right corner of the button, e.g. a `<Badge>`. */
+    badge?: React.ReactNode;
+    testId?: string;
+} & DataProps;
+/**
+ * An icon button used inside the `TopBar`. Wraps its content in a tooltip and
+ * supports an optional badge positioned in the top-right corner.
+ */
+declare const NavButton: ({ children, tooltipContent, onClick, badge, testId, ...rest }: Props) => React.JSX.Element;
+export default NavButton;

package/dist/layout/NavButton/index.d.ts

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

package/dist/layout/TopBar/TopBar.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { DataProps } from '../../foundation/types';
+type Props = {
+    /** Content for the left region. Defaults to the 7shifts logo when omitted. */
+    logo?: React.ReactNode;
+    /** Content for the center region, e.g. a banner. */
+    center?: React.ReactNode;
+    /** A search bar rendered in the right region, before the actions. */
+    search?: React.ReactNode;
+    /** Buttons rendered in the right region, typically `NavButton`s. */
+    actions?: React.ReactNode;
+    /** The account menu rendered at the far right, e.g. a `Dropdown` with an `Avatar`. */
+    accountMenu?: React.ReactNode;
+    testId?: string;
+} & DataProps;
+/**
+ * Top navigation bar with three regions: a left region for the logo, a center
+ * region for banners, and a right region for a search bar, action buttons and
+ * an account menu. Every region is an optional slot, making the bar flexible.
+ */
+declare const TopBar: ({ logo, center, search, actions, accountMenu, testId, ...rest }: Props) => React.JSX.Element;
+export default TopBar;

package/dist/layout/TopBar/index.d.ts

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

package/dist/layout/index.d.ts

@@ -4,6 +4,9 @@ import Inline from './Inline';
 import Stack from './Stack';
 import Page from './Page';
 import PageLayout from './PageLayout';
-export { CalloutCard, Card, Inline, Stack, Page, PageLayout };
+import TopBar from './TopBar';
+import NavButton from './NavButton';
+import LayoutFrame from './LayoutFrame';
+export { CalloutCard, Card, Inline, Stack, Page, PageLayout, TopBar, NavButton, LayoutFrame };
 export type { AlignItems, FlexWrap, JustifyContent } from './Flex/types';
 export type { PageLayoutMenu } from './PageLayout/types';

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

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

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

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

package/dist/overlay/DropdownContext/SubmenuFocusContext.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+type SubmenuFocusContextType = {
+    isSubmenuFocused: boolean;
+    setSubmenuFocused: (focused: boolean) => void;
+};
+export declare const SubmenuFocusProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+export declare const useSubmenuFocus: () => SubmenuFocusContextType;
+export {};

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`.