@7shifts/sous-chef 4.11.0 → 4.12.0

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

@@ -1,20 +1,95 @@
+<!-- AUTO-GENERATED by scripts/build-llms-guidelines.js. Do not edit manually. Run `yarn build-llms-guidelines` to regenerate. -->
+
 ## When to Use
 
--   When the user needs to select from a list of options that is loaded dynamically from an API or other async source — employees, roles, locations, etc.
--   When the full list of options is too large to load upfront and should be fetched on demand or filtered server-side
--   When the available options depend on another field's value (e.g. employees filtered by location)
+-   When options come from an API and the full list is too large to load at once (employees, locations, roles, etc.).
+-   When results should be narrowed by what the user types — search-as-you-type against a backend.
+-   When the option list is dynamic — it changes based on server state or another field's value.
 
 ## When Not to Use
 
--   When the list of options is fixed and known at render time — use `SelectField` instead
--   When the user must be able to select more than one option — use `MultiSelectField` instead
--   When the options are few and benefit from being fully visible — use `RadioGroupField` or `PillSelectField` instead
--   When the user needs to enter free-form text — use `TextField` instead
+-   When the option list is small and static — use `SelectField` instead; it takes a plain `options` array and has no loading overhead.
+-   When options are already available in memory — pass them directly to `SelectField` or filter them client-side.
+-   When the user needs to pick from a fixed set of weekdays — use `WeekSelectField`.
 
 ## Usage
 
-### Copy
+### The `loadOptions` Callback
+
+`loadOptions` is the only required prop unique to this component. It receives two arguments and must return a Promise:
+
+```ts
+loadOptions: (
+    inputValue: string, // current search text (empty string on initial load)
+    cursor?: string | null // pagination cursor, null on the first call
+) =>
+    Promise<{
+        options: SelectOption<T>[]; // the page of options to display
+        hasMore: boolean; // whether more pages exist
+        nextCursor?: string | null; // opaque cursor for the next page (omit or null if none)
+    }>;
+```
+
+The component calls `loadOptions('', null)` automatically on mount to populate the initial list. There is no need to trigger a manual fetch.
+
+### Pagination and Scroll-to-Load-More
+
+When a `nextCursor` is returned, a spinner appears at the bottom of the menu as the user scrolls down. When the user reaches the bottom, the next page is fetched using that cursor and its options are **appended** to the current list — the previous options are not replaced.
+
+```ts
+// Page 1 response — signals more pages exist
+{ options: firstPageOptions, hasMore: true, nextCursor: '20' }
+
+// Page 2 response — called with cursor='20', no further pages
+{ options: secondPageOptions, hasMore: false }
+```
+
+If `nextCursor` is omitted or `null`, or if `hasMore` is `false`, no further fetches are triggered on scroll. Omitting `nextCursor` entirely is the same as returning `null` — the component treats both as "no next page".
+
+### Search Behavior
+
+When the user types, `loadOptions` is called with the current input text and `null` as the cursor — pagination always resets to the first page on a new search. Accumulated options from previous scroll-loads are discarded and replaced with the fresh results.
+
+**Client-side search optimisation:** If the very first `loadOptions` call returns `hasMore: false`, the component caches the full option list and all subsequent searches are filtered client-side — no further network calls are made regardless of what the user types. This makes single-page datasets feel instant without any extra code on the caller's side.
+
+### Dependent Fields
+
+Use the `key` prop to force a full reload whenever an external value changes — for example when a Location field controls which employees are shown:
+
+```tsx
+<AsyncSelectField
+    loadOptions={(inputValue, cursor) =>
+        fetchEmployees(inputValue, cursor, location.value)
+    }
+    name="employee"
+    label="Employee"
+    key={location.value} // remounts (and re-fetches) when location changes
+/>
+```
+
+When `key` changes, React unmounts and remounts the component, which resets all accumulated options, the cursor, and the search input.
+
+### Label, Caption, and Error
+
+Always provide a `label` — it identifies the field and is linked to the input for screen readers. Use `caption` for supplementary guidance such as what the user should search for. Use `error` to surface validation messages; the field is marked as invalid for screen readers when an error is present.
+
+### No Options and Loading States
+
+The component handles loading and empty states automatically. A "Loading..." indicator appears while options are being fetched on initial load or after typing. When `loadOptions` resolves with an empty array and `hasMore: false`, react-select's default "No options" message is shown — this can be customised via the `noOptionsMessage` prop.
+
+## Tips & Tricks
+
+-   If your API doesn't paginate, simply return `hasMore: false` and omit `nextCursor` — the scroll-load-more behaviour is disabled and the component behaves like a plain async select.
+-   The `cursor` parameter passed to `loadOptions` is whatever string you returned as `nextCursor` on the previous call. It is opaque to the component — you can use an offset, a page number, a keyset value, or any server-issued token. The component never inspects or modifies it.
+-   Debouncing is built in (500 ms, leading edge). There is no need to debounce `loadOptions` at the call site.
+-   Avoid returning `hasMore: true` without a `nextCursor`. The component uses the cursor to guard against duplicate fetches — if `hasMore` is `true` but `nextCursor` is `null`, scroll-to-load-more is silently disabled for that page.
+-   The `key` pattern is more reliable than updating `loadOptions` in a `useEffect`. React's remount guarantee means state is always fully reset, whereas updating the callback while keeping the component mounted may not clear accumulated options.
+
+## Additional Rules
 
--   Use sentence case for labels, captions, and placeholder text
--   Write placeholder text as a concrete search prompt ("Search for an employee") rather than a generic instruction ("Select something")
--   Keep labels short — one to three words is ideal
+-   `loadOptions` and `name` are required. All other props are inherited from `SelectField` (`label`, `onChange`, `value`, `caption`, `error`, `prefix`, etc.).
+-   `loadOptions` is called with `('', null)` on mount — the initial call always receives an empty string and a null cursor.
+-   The `cursor` argument is `string | null` — always `null` on the first call per search query, and the opaque `nextCursor` string on subsequent scroll-load calls.
+-   `nextCursor` in the response is optional and typed as `string | null`. Returning `undefined`, `null`, or omitting the field are all treated identically — no next page.
+-   `hasMore: false` stops all further scroll-triggered fetches for the current search, even if a `nextCursor` was returned (it is discarded).
+-   `filterOption` is set to `null` internally — react-select's built-in client-side filtering is disabled because the component manages the option list directly. Do not pass a `filterOption` prop.

package/llms-instructions/llms-components.md

@@ -98,7 +98,7 @@ Form components are used to collect user input and data.
 
 ### AsyncSelectField
 
-A variation of select field that loads a dynamic list of options from a source rather than a fixed set of options. Use when you need to select from a dynamic list that can change such as roles, employees, locations, etc. Instead of passing a `options` props, this component requires a `loadOptions` prop.
+A select field that fetches its options from an async source — an API, a search endpoint, or any function that returns a Promise. Use it when the option list is too large to load upfront or when options change based on server-side data. Supports scroll-to-load-more pagination: when the user scrolls to the bottom of the open menu and more results exist, the next page is fetched and appended automatically.
 
 ### CheckboxField
 

package/llms-instructions/llms-tokens.md

@@ -413,6 +413,7 @@ Most of the time you won't need to use these tokens because it is baked into Sou
 | ------------------- | ----- |
 | --border-radius-300 | 4px   |
 | --border-radius-400 | 8px   |
+| --border-radius-500 | 12px  |
 | --border-radius-600 | 20px  |
 
 ## Z-index

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@7shifts/sous-chef",
-    "version": "4.11.0",
+    "version": "4.12.0",
     "description": "7shifts component library",
     "author": "7shifts",
     "license": "MIT",