@cdx-ui/components 0.2.3 → 0.2.5

package/docs/components/select/design.md

@@ -0,0 +1,301 @@
+# Select — Design (https://design.candescent.com/docs/components/select)
+
+## Usage
+
+**Example**
+
+**Common alternative names**: Dropdown, selector, selection menu
+
+---
+
+## **Anatomy**
+
+Select is an input field, similar to the Input Field component. However, the Select field contains a Menu component that is hidden until the user clicks to open it.
+
+1. **Label**: Text describing what the input field is asking for.
+2. **Value**: The currently selected value.
+3. **Helper text**: An optional line of assistive text attached to the bottom of the field.
+4. **Dropdown indicator**: Icon indicating that the field has a menu of options. Icon is flipped when the menu is open.
+5. **Menu**: The list of options available to select from.
+6. **Selected option**: The currently selected option, highlighted in the menu.
+
+### **Size**
+
+Select fields are available in 2 sizes: **Default** and **Small**. These sizes give you flexibility when building layouts, but a consistent size should be used for all input fields on the same page.
+
+- **size: default**
+
+  The default size and the most commonly used size. Has a height of 44px when used without helper text.
+
+### **Required**
+
+A select field can be designated as a required input. The user will be required to make a selection before continuing or submitting the form.
+
+- **required: true**
+
+  An asterisk is displayed next to the label. It is not part of the label text.
+
+### **Helper text**
+
+Helper text is an optional line of assistive text attached to the bottom of an input field. It can provide critical information, instructions, acceptance criteria, or other important information that will help users complete the input. It can also be used to provide an explanation when the field is in an error state.
+
+- **Show Helper Text?: true**
+
+  A line of small text is shown below the field. This variant increases the field height.
+
+### **Hidden label**
+
+When absolutely necessary, the label of a select field can be hidden. There are very, very few places where hiding the field’s label is recommended, so avoid using this variant whenever possible.
+
+- **Show Label?: false**
+
+  The field label is hidden.
+
+---
+
+**Usage**
+
+### **When to use**
+
+> [!TIP]
+>
+> **When the user needs to choose one option from a finite list**
+>
+> - ex: Select a state in a shipping address form
+> - ex: Select an account to use in a money transfer form
+> - ex: Select a sorting option when viewing a list of transactions
+
+> [!TIP]
+>
+> **When the user may choose multiple options from a finite list**
+>
+> - ex: Select a few transaction categories to filter by when viewing a list of transactions
+> - ex: Select multiple family members when assigning authorized users of a credit card
+
+> [!TIP]
+>
+> **When the list of options is easy to navigate without search functionality**
+>
+> - ex: When selecting a state in a shipping address form, the user is generally familiar with the options, and they are typically sorted alphabetically.
+> - ex. When selecting an account in a money transfer form, the user is familiar with all of their accounts.
+
+> [!TIP]
+>
+> **To reduce the potential for errors in form data**
+>
+> - ex: Selecting a state from a menu avoids users having to spell the name of the state correctly
+> - ex: Selecting an account from a menu avoids users having to remember their exact account name or account number
+
+### **When not to use**
+
+> [!CAUTION]
+>
+> **Large, undefined, or unique data sets**
+>
+> - ex: ZIP code in a shipping address form
+> - ex: Dollar amount in a money transfer form
+> - Instead, consider a [Input Field](https://design.candescent.com/docs/components/input/content.md) or Autocomplete.
+
+> [!CAUTION]
+>
+> **For long lists of options that should have a search functionality**
+>
+> - ex: Select your favorite movie from a list of the top 100 highest-grossing movies
+> - ex: Select a recipient from your contacts to send a text message
+
+### **Select field vs. radio buttons**
+
+When there are 5 or less options to choose from, a select field and a Form Control with radio buttons are mostly interchangeable. Use your best judgement to choose which component is best for your form’s layout and context.
+
+- **Do:** Choose a select field over a Form Control when it will help maintain a consistent look and flow in the form.
+- **Caution:** Avoid using a Form Control if it will disrupt the flow or consistent look of the form.
+
+### **Layout and placement**
+
+Select fields are typically found on forms. When placing the component, make sure it is appropriately spaced from other form fields to prevent confusion. It should be placed in a location that does not block other important information on the page when the field is active and the menu has dropped down.
+
+When using a select field in a form, please see the Form Pattern for additional guidance about layout and placement.
+
+### **Using helper text**
+
+Helper text is an optional line of assistive text attached to the bottom of an input. It can provide instructions, acceptance criteria, or other important information that will help the user make a selection.
+
+#### **When to use helper text**
+
+Helper text should only be used when necessary. Too much helper text will clutter the screen, and may overload the user. Use these guidelines to decide if helper text would be beneficial for your select field:
+
+- Will most users need additional information to understand what the input is asking for?
+- Will most users need an explanation of what their selection represents?
+- Will users want to know why, how, or where their response will be used? Will they hesitate to answer without that info?
+
+Addressing these needs will help the user complete the input more quickly and with less errors.
+
+- **Do:** Include helper text when the user needs additional info to understand exactly what the input is asking for.
+- **Do:** Include helper text when the user needs additional info to understand how their response will be used.
+
+#### **When not to use helper text**
+
+Do not use helper text in place of a label, or to indicate that the input is required.
+
+- **Don't:** Don’t use helper text to indicate that an input is required.
+- **Don't:** Don’t use helper text in place of an input label.
+
+---
+
+## **Behavior**
+
+### **Interaction states**
+
+The default state of a select field is clickable. The appearance of the field will respond as the user interacts with it.
+
+- **Resting**
+
+  Default state. User is not interacting with the select field, and the menu is not open.
+- **Hover**
+
+  When the user’s cursor is hovering over the Select field.
+- **Focus**
+
+  When a keyboard user is focused on the select field using tab navigation controls.
+- **open: true**
+
+  When the select field’s menu is open, showing the selectable options. In this state, the user can select an option from the menu.
+
+### **Disabled**
+
+The select field can be disabled, which prevents the user from clicking on or interacting with the field in any way, including editing the current value. Using disabled fields can cause accessibility issues, so avoid using this state wherever possible.
+
+In this state, the user cannot interact with the field or change its current value. The background color and the value appear greyed out.
+
+### **Read only**
+
+The select component can be set to read only mode, which prevents the user from changing the value of the field. Unlike the disabled state, the user can still interact with this field through hover and keyboard focus, allowing screen readers to read out the current value of the field.
+
+In this state, the user cannot open the menu or edit the value of the field. However, the value remains fully visible, and the user can hover over or focus on the field.
+
+### **Error state**
+
+When the user doesn’t select an option for a required Select field, the Select component should collapse, the helper text should show an error message, and the input field should highlight red. The display of new helper text pushes down the content below.
+
+When the user selects an invalid option or otherwise makes a mistake.
+
+#### **Showing error helper text**
+
+Helper text is **required** when the input is in an error state. If the input already had helper text before the error state, the helper text should change. If no helper text was present before the error, the error helper text should push down any content below the field.
+
+See the Writing error helper text section for details on how error helper text should be phrased.
+
+### **Selection states**
+
+The select field is empty when no value is selected, and filled when a value is selected. A default value can be filled in if desired.
+
+- **Show Value?: false (default)**
+
+  No value is currently selected. The field is empty and no item in the menu is selected.
+- **Show Value?: true**
+
+  A value is currently selected. The value is shown in the field and selected in the menu.
+
+### **Menu opening**
+
+The menu within the select component should be collapsed by default. The menu can be opened by clicking inside the field, or by shifting the focus to the field using tab navigation and pressing `Space`.
+
+- **behavior\_menu\_01-ex**
+- **behavior\_menu\_02-ex**
+
+When the menu is open, it appears on top of any other UI elements. If the field has no value selected, the first option in the list is in focus and highlighted when the menu opens. If a value is selected, that value will be in focus and highlighted.
+
+### **Selecting an option**
+
+Once the menu is open, the user can select an option by clicking on it. Additionally, the user can use the arrow keys to move up and down in the menu, and select an option by pressing enter. Once an option is selected, the menu is closed.
+
+- **behavior\_selecting\_01-ex**
+- **behavior\_selecting\_02-ex**
+
+Additionally, when the user clicks outside of the Select component or hits the `Esc` key, the menu closes.
+
+_behavior\_selecting\_03-ex_
+
+## Content
+
+## **Label**
+
+Every input field in a form should have a corresponding label that helps the user understand what the input means. Labels should clearly and concisely describe the value or response requested from the user.
+
+Use these guidelines when writing labels:
+
+- Use between 1 to 3 words when possible
+- Labels should be written in sentence case (aside from proper nouns)
+- Don’t include a colon (:) after the label
+
+* **Do:** Do use clear and concise labels.
+* **Don't:** Don’t be ambiguous.
+
+## **Number of options**
+
+Keep the number of options reasonable and easy to navigate. If you have 8 or fewer options, the Select component is a good choice. A Select is able to contain a large number of options, but scrolling through a long list can be overwhelming for users.
+
+If you have more than 8 options, consider using an Autocomplete instead, since the user is able to use the keyboard to search the list for options. If using an Autocomplete is not appropriate, do not display more than 8 options at a time in the Select’s menu to help prevent cognitive overload.
+
+- **Do:** Do display 8 or fewer options at once. If more than 8 are available, consider an autocomplete before providing a scroll bar.
+- **Don't:** Don’t display more than 8 options at a time. Consider using the Autocomplete component or rethink the content.
+
+## **Sorting options**
+
+The sort order in which the options are displayed can be set to a desired configuration, depending on the content within the Select and your product’s needs. Consider your use case when determining how each Select should be sorted.
+
+Below are some common sorting methods, with examples.
+
+### **Numerically**
+
+- **Ascending**: 1, 2, 3, …
+- **Descending**: 100, 99, 98, …
+
+### **Alphabetically**
+
+- **Ascending**: Apples, Bananas, Carrots, Dates, Eggs, Flour, …
+- **Descending**: Zucchini, Yogurt, Watermelon, Vinegar, Tomatoes, Spinach, …
+
+### **Lexicographically**
+
+Lexicographic sorting is like the dictionary. When sorting text, words are first sorted by their first letter, then by their second, and so on. When sorting numbers, it compares them digit by digit in the same way. In the below examples, 1001 and 10 come after before 201 and 2 (respectively) because 1 is less than 2.
+
+- Stock keeping units: SKU-1001, SKU-1002, SKU-101, SKU-201, SKU-3005
+- Item quantities or pack sizes: 1, 10, 2, 24, 3, 39, etc.
+
+### **By relevance**
+
+- Recently ordered items
+- Recent transactions
+- Favorited menu item
+- Nearest store
+
+### **By popularity**
+
+- Trending restaurants or dishes
+- Products based on sales data
+- Popular dishes
+- Frequently used recipient names and account numbers
+
+**Helper text**
+
+Helper text should be short and concise, and only provide information that is crucial to helping the user complete the form. Use these guidelines when writing helper text:
+
+- Aim for 1 line of text
+- Longer helper text should wrap to the next line, and not go too far past the longest option label
+- Helper text should be written in sentence case (aside from proper nouns)
+
+* **Do:** When writing helper text, aim for a single line of text. If the text must be longer, it should wrap down to a second line.
+* **Don't:** Helper text should not be longer than the input area. Wrap longer text down to a second line.
+
+### **Error helper text**
+
+Helper text must always be included when the input is an an error state. The combination of the icon, red color, and text must help the user understand:
+
+1. The field has an error
+2. What the error is
+3. How the user can correct their input and resolve the error
+
+- **Do:** This example concisely tells the user that there is an error, what the error is, and what they can do to resolve it.
+- **Caution:** Avoid vague explanations. This example tells the user that there is an error, but is not specific enough about why the value is invalid.
+- **Don't:** Don’t write unnecessarily long helper text. This example meets all the criteria listed above, but it is too long.

package/docs/components/skeleton/content.md

@@ -0,0 +1,104 @@
+# Skeleton (https://design.candescent.com/docs/components/skeleton)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=11476-16576), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/feedback-skeleton--default)
+
+A loading placeholder with no intrinsic dimensions — size and shape come entirely from `className`. Pulses opacity via Reanimated.
+
+```tsx
+import { Skeleton } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { Skeleton } from '@cdx-ui/components';
+
+export default function SkeletonBasicDemo() {
+  return <Skeleton className="h-5 w-50" />;
+}
+```
+
+## Text lines
+
+Staggered widths suggest a block of body copy.
+
+```tsx
+import { Box, Skeleton } from '@cdx-ui/components';
+
+export default function SkeletonTextLinesDemo() {
+  return (
+    <Box className="w-70 gap-2">
+      <Skeleton className="h-4 w-full" />
+      <Skeleton className="h-4 w-4/5" />
+      <Skeleton className="h-4 w-3/5" />
+    </Box>
+  );
+}
+```
+
+## Avatar
+
+Circular placeholder with name lines.
+
+```tsx
+import { HStack, Skeleton, VStack } from '@cdx-ui/components';
+
+export default function SkeletonAvatarDemo() {
+  return (
+    <HStack space="md" className="items-center">
+      <Skeleton className="h-10 w-10 rounded-full" />
+      <VStack space="sm">
+        <Skeleton className="h-3.5 w-30" />
+        <Skeleton className="h-3 w-20" />
+      </VStack>
+    </HStack>
+  );
+}
+```
+
+## Card
+
+Skeleton placeholders composed inside `Card`.
+
+```tsx
+import { Card, HStack, Skeleton, VStack } from '@cdx-ui/components';
+
+export default function SkeletonCardDemo() {
+  return (
+    <Card className="w-full max-w-md">
+      <Card.Header>
+        <HStack space="md" className="items-center">
+          <Skeleton className="h-12 w-12 rounded-full" />
+          <VStack space="sm" className="flex-1">
+            <Skeleton className="h-3.5 w-3/5" />
+            <Skeleton className="h-3 w-2/5" />
+          </VStack>
+        </HStack>
+      </Card.Header>
+      <Card.Content className="gap-3">
+        <Skeleton className="h-3.5 w-full" />
+        <Skeleton className="h-3.5 w-9/10" />
+        <Skeleton className="h-3.5 w-7/10" />
+      </Card.Content>
+      <Card.Footer>
+        {/* TODO(forge-ui): Skeleton has no button shape that follows the theme's button radius; using the default radius. */}
+        <Skeleton className="h-11 w-full" />
+      </Card.Footer>
+    </Card>
+  );
+}
+```
+
+## API
+
+### Skeleton
+
+`duration` is the half-cycle length in milliseconds (opacity `1` → `0.35`); a full pulse is approximately `duration × 2`. The ref targets `Animated.View` from `react-native-reanimated`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | Size and shape classes for the placeholder, such as `h-4 w-32 rounded-md`. |
+| `children?` | `React.ReactNode` | — | Optional content to render inside the placeholder. |
+| `duration?` | `number` | `1000` | Half-cycle of the opacity pulse (`1` → `0.35`) in milliseconds. A full pulse takes `duration × 2`. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).