@7shifts/sous-chef 4.7.1 → 4.8.0

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

@@ -0,0 +1,23 @@
+## When to Use
+
+-   When the user needs to select a specific time of day — clock-in/clock-out, shift start/end, appointment scheduling, or any similar time-entry scenario
+-   When you want to offer preset time options at a configurable interval while still allowing the user to type a time directly
+-   When time display format must match user locale or account preference (12-hour AM/PM vs. 24-hour)
+
+## When Not to Use
+
+-   When the user needs to select both a start and end time together — use `TimeRangeField` instead
+-   When the user needs to pick a date as well as a time — combine `DateField` with `TimeField` rather than overloading one field
+-   When the value is a duration or elapsed time rather than a clock time — use a `NumberField` or `TextField` with explicit unit labeling instead
+-   When the user must choose from a small, fixed set of named options — use `SelectField` instead
+
+## Usage
+
+> Note: The component formats the raw input on blur but does **not** parse or validate it for you. You are responsible for validating the string value and converting it to whatever representation your application needs.
+
+### Copy
+
+-   Use sentence case for labels and captions
+-   Keep labels short and specific to the time being captured — "Start time", "Clocked in", "Appointment" are all good examples
+-   Write captions as clarifying context, not as instructions — prefer "The time you clocked in at work" over "Enter your clock-in time"
+-   Do not use placeholder text as a label substitute

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

@@ -0,0 +1,19 @@
+## When to Use
+
+-   When the user needs to select both a start time and an end time as a single input — for example, scheduling a shift, booking a meeting room, or defining an availability window
+-   When the time range must be captured as a pair (start + end) rather than two independent time fields
+-   When you want the component to automatically calculate and display the duration between the two selected times
+
+## When Not to Use
+
+-   When only a single point in time is needed — use `TimeField` instead
+-   When the user needs to select a range of dates, not times — use `DateRangeField` instead
+-   When start and end times are logically independent and do not form a range — use two separate `TimeField` instances instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels and captions
+-   Keep labels short and descriptive of what the range represents — e.g. "Shift time", "Meeting hours", "Availability window"
+-   Use caption text to clarify the purpose or constraints — e.g. "Set the start and end of the shift"

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

@@ -0,0 +1,20 @@
+## When to Use
+
+-   When the user must select a single week (always 7 consecutive days) from a calendar widget
+-   When the week boundary matters — e.g. pay periods, schedule weeks, billing cycles — and the selection must snap to a whole week rather than an arbitrary date range
+-   When the start day of the week is configurable (e.g. Sunday vs. Monday) to match business rules
+
+## When Not to Use
+
+-   When the user needs to pick a single day — use `DateField` instead
+-   When the user needs an arbitrary start and end date that do not have to align with week boundaries — use `DateRangeField` instead
+-   When the user needs to pick a specific time — use `TimeField` or `TimeRangeField` instead
+-   When the selectable unit is a month or a custom period rather than a week — use `DateField` and enforce the constraint in application logic instead
+
+## Usage
+
+### Copy
+
+-   Use sentence case for labels, captions, and placeholder text
+-   Keep labels concise and specific to the week-selection context — e.g. "Schedule week", "Pay period", "Billing week"
+-   Captions should explain what selecting a week will affect — e.g. "Select the week you want to schedule shifts for"

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

@@ -10,6 +10,7 @@
 -   When no specific calendar week is involved and only weekday names matter — use `PillSelectField` with day-of-week options instead
 -   When users need to pick dates across multiple weeks or a date range — use `DateRangeField`
 -   When the user needs to see the full calendar for additional context.
+-   When the user needs to select an entire week, instead of individual days within a week - use `WeekField` instead.
 
 ## Usage
 

package/llms-instructions/llms-components.md

@@ -96,10 +96,30 @@ Toasts are used to inform the user about an action that happened.
 
 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.
+
+### CheckboxField
+
+A simple check box with an option beside it. Allows the user to confirm a statement or enable an option with a simple boolean action. Use for things like agreeing to terms, or enabling one or more options in a list (where multiple selections are allowed).
+
 ### ColorField
 
 Color fields allow users to select a color from a predefined set of options, or pick a custom color via the native color picker. They are ideal for settings or configurations where color selection is necessary.
 
+### CurrencyField
+
+A variation of a TextField, but it only accepts numbers, and will auto format the number into a currency format when the user leaves the field. Use anytime the user must enter a currency value and nothing else. **You are in charge of validating the value and parsing it back to a value that you can use on your application**.
+
+### DateField
+
+A dropdown style field for selecting a single specific date. It will load a calendar widget when activated allowing the user to find and pick a day.
+
+### DateRangeField
+
+A dropdown style field with 2 inputs. It allows the user to select a specific start date and end date separately to create a range of dates. .
+
 ### FormFeedback
 
 FormFeedback is used to indicate an error within a form, for example when there is invalid or missing data in a form field.
@@ -108,14 +128,70 @@ FormFeedback is used to indicate an error within a form, for example when there
 
 `FormFooter` contains the CTAs for a `Form` and handles all the `Button` styling when the `actions` prop is used.
 
+### FormRow
+
+Easily add form fields side by side with equal size.
+
 ### FormSection
 
 `FormSection` provides visual seperation between sections within a `Form` and can have a title and subtitle.
 
+### MultiSelectField
+
+A dropdown style field that lets you select and input more than one option within the field. Uses removable chips to represent selected items.
+
+### NumberField
+
+A special text input field that only accepts numbers. It has validation and formatting in place to properly display number values. In its default state it only allows whole numbers, but it can be configured to allow decimals and negative values.
+
+### PasswordField
+
+A field used for passwords. It obfuscates the input by default, but has the option to reveal the input. Can also include required password criteria.
+
+### PercentageField
+
+A special text input field that only accepts numbers. Comes with validation and formatting in place to properly display percentage values. In its default state it only allows integers between 0 and 100, but it can be configured to allow decimals and negative values.
+
 ### PhoneField
 
 A field for entering phone numbers. It includes a selection field for country code and can validate phone numbers.
 
+### PillSelectField
+
+A field where the user can select one or more from a vertical line of pills. Can also be made fully reactive allowing users to add and delete their own options. Use this to select from a more visual list with a limited number of options, like selecting the day of the week.
+
+### RadioGroupField
+
+A list of radio options appearing either as an input or box. Use when the user can only select one option from a visual list and the user needs to be able to see all the options to make an informed decision.
+
+### RadioGroupOption
+
+RadioGroupField form element.
+
+### SelectField
+
+Simple dropdown field where the user chooses one option from a predefined list.
+
+### TextAreaField
+
+A basic open input field used to get text from the user, with options to add a prefix or suffix element if necessary. Accepts any characters, so do not use it if you want to limit the format of the input to numbers only.
+
+### TextField
+
+TextField is a basic open input field used to get text from the user, with options to add a prefix or suffix element if necessary. Accepts any characters, so do not use it if you want to limit the format of the input to numbers only.
+
+### TimeField
+
+A special field design for selecting a specific time of the day. Users can choose from a dropdown of preset time intervals, or type directly into the field. When the user leaves the field, the input is automatically formatted into either AM/PM time or 24h time. **You are in charge of validating the value and parsing it back to a value that you can use on your application**.
+
+### TimeRangeField
+
+A special input field for selecting a time range. Comprised of 2 individual time fields, the user selects a start time and an end time individually to.
+
+### WeekField
+
+A special dropdown style field used to select a single week from a calendar widget. Selections must always be 7 consecutive days, but you may customize the day of the week the selectable range starts on.
+
 ### WeekSelectField
 
 A week-scoped day selector. Pass an array of 7 dates representing a week and let users pick which days apply. Each pill displays the 3-letter weekday abbreviation and the calendar date.
@@ -160,6 +236,10 @@ Layout component to easily line elements up in a row.
 
 The Page component is used to control the elements within a page. It can be full width or restricted using the `size` prop. To better see it, open this example on a full page.
 
+### PageLayout
+
+PageLayouts are responsible for grouping multiple pages. It will usually render a bunch of routes on its children.
+
 ### Stack
 
 Layout component to easily stack elements up in a column.

package/package.json

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