@capra/core 1.11.1 → 1.13.0

package/docs/core-autocompletefield--usage.md

@@ -5,7 +5,7 @@ AutocompleteField combines a text field with a suggestions list. Consumers can s
 | Prop | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
 | `canClear` | `boolean` | No | `--` | Whether to show a clear button for the input. |
-| `children` | `React.ReactNode \| ((     values: T & {       defaultChildren: React.ReactNode \| undefined;     },   ) => React.ReactNode)` | No | `--` | The children to render in the dropdown. |
+| `children` | `ChildrenOrFunction` | No | `--` | The children to render in the dropdown. |
 | `itemFilter` | `(textValue: string, inputValue: string) => boolean` | No | `--` | A function that filters the items based on the input value. |
 | `onChange` | `(value: string) => void` | No | `--` | A callback function that is called when the input value changes. |
 | `onOpenChange` | `(isOpen: boolean) => void` | No | `--` | A callback function that is called when the dropdown is opened or closed. |

package/docs/core-menu--usage.md

@@ -14,5 +14,5 @@
 | `itemActiveAccentBar` | `boolean` | No | true | When `itemHoverAppearance` is `accent`, whether the active/selected row shows the inline-end accent bar (vertical TabNav indicator). Set to `false` for horizontal TabNav flyout menus where selection should not show that bar.<br>@default true |
 | `itemActiveLabelSemibold` | `boolean` | No | true | When `itemHoverAppearance` is `accent`, whether the active/selected row uses a semibold label. Set to `false` for TabNav horizontal submenus where the active item should match normal menu weight.<br>@default true |
 | `panelPadding` | `'default' \| 'none'` | No | 'default' | Inset of the menu panel (`role="menu"`). `none` uses a minimal inset so focus rings are not clipped under scroll/overflow; use for flyouts that should sit close to the popover edge (e.g. TabNav submenu).<br>@default 'default' |
-| `popoverOffset` | `number` | No | 0 | Gap along the main axis between the trigger and the menu panel (React Aria `Popover` `offset`).<br>Use a small value (e.g. 1) when the panel should clear a trigger underline/border (e.g. horizontal TabNav).<br>@default 0 |
+| `popoverOffset` | `number` | No | 2 | Gap along the main axis between the trigger and the menu panel (React Aria `Popover` `offset`).<br>Defaults to 2px to match `spacing.xs`; `Popover` positioning takes a number, so the token cannot be applied via CSS.<br>Use a smaller value (e.g. 1) when the panel should clear a trigger underline/border (e.g. horizontal TabNav).<br>@default 2 |
 | `trapFocus` | `boolean` | No | false | When `true`, focus is contained in the menu panel while it is open (Tab cycles within the panel; focus restores on close).<br>The popover stays non-modal so outside pointer dismiss still works. Use for patterns that must not move focus to sibling controls until the menu closes (e.g. horizontal TabNav flyouts).<br>@default false |

package/docs/core-selectfield--design.md

@@ -0,0 +1,66 @@
+# Core/SelectField - Design
+
+## Anatomy
+
+1. **Label**: describes the field and carries the required marker when needed.
+2. **Trigger**: matches Capra text-input sizing and state treatments.
+3. **Popover**: contains the option list and optional search field.
+4. **ListBox items**: support single-select rows or multi-select rows with checkmarks.
+5. **Sections**: optional grouped options with a non-selectable header label.
+
+## Properties
+
+### Layout
+
+Use `layout="vertical"` by default. Use `layout="horizontal"` only when space is constrained.
+
+### Multiple Selection
+
+For multi-select fields, selected options appear as removable tags inside the trigger. Tags wrap onto additional lines when they exceed the field width, and selected rows show a checkmark in the popover.
+
+### Search
+
+Enable `canSearch` for longer option lists. Search filters the visible options inside the popover without changing the trigger layout. When nothing matches, the popover shows "No results" so the list never appears empty.
+
+### Sections
+
+Larger option lists can be organized into smaller groups using sections. Each section has a header to label the grouping. Pass `items` with nested `children` to build sections from data, or wrap static options in `SelectField.Section` with a `SelectField.Header`.
+
+## States
+
+* Match the standard input states: default, hover, focus, disabled, placeholder, warning, and danger.
+* `appearance="danger"` drives the invalid visual state and helper text treatment.
+* Small and medium sizes align with `TextInput`.
+
+## Behavior
+
+* Use `SelectField` for fixed option sets, especially when the option count is greater than about five.
+* Prefer `RadioGroup` when the user should see all mutually exclusive choices at once.
+* Prefer `AutocompleteField` when freeform typing or custom values are required.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key                          | Function                                                                                                                                                                                                                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Tab` / `Shift + Tab`        | Moves focus into the multiselect TagGroup (first selected tag) or the open button, then to the next or previous focusable element. Remove buttons are not sequential tab stops. If the option list is open, these keys are ignored.                                                  |
+| `Left Arrow` / `Right Arrow` | In multiple-select mode with the TagGroup focused: moves focus between selected tags.                                                                                                                                                                                                |
+| `Delete` / `Backspace`       | In multiple-select mode with a selected tag focused: removes that tag.                                                                                                                                                                                                               |
+| `Down Arrow` / `Up Arrow`    | If the option list is closed and the open button has focus: opens the list and moves focus to the selected item (the first selected item in multiple-select mode), or the first/last item when nothing is selected. If the list is open: moves focus to the next or previous option. |
+| `Enter` / `Space`            | If the option list is closed: opens the option list (from the open button). If the list is open: selects the focused option. In single-select mode the list closes after selection; in multiple-select mode the list stays open.                                                     |
+| `Esc`                        | If the option list is open: closes the list and returns focus to the select trigger.                                                                                                                                                                                                 |
+
+While the option list is open, focus stays inside the popover in both selection modes.
+
+In multiple-select mode, selected values use React Aria’s `TagGroup` in the trigger (styled to match Capra Tag). Keyboard behavior follows TagGroup defaults: arrows move between tags; Delete/Backspace removes; clicking the remove control also removes.
+
+### Labeling
+
+All select fields require a label. Provide a visible `label` prop when possible. When a visible label is not spatially associated with the trigger, use `aria-label` or `aria-labelledby`.
+
+### Focus treatment
+
+* The trigger uses the Capra 2px focus outline (`token('border.focus')`).
+* List options show a keyboard focus ring on the active row; the popover container suppresses the browser default panel outline (same pattern as `Menu`).
+* Warning and danger icons in the trigger are decorative (`aria-hidden`); invalid state is conveyed with `aria-invalid` on the trigger.

package/docs/core-selectfield--usage.md

@@ -0,0 +1,145 @@
+# Core/SelectField - Usage
+
+## Basic usage
+
+```tsx
+import { SelectField } from '@private/core';
+
+const animals = [
+  { id: '1', label: 'Dog' },
+  { id: '2', label: 'Cat' },
+  { id: '3', label: 'Bird' },
+];
+
+function Example() {
+  return (
+    <SelectField label="Animal" placeholder="Select" items={animals} />
+  );
+}
+```
+
+## Props
+
+## Examples
+
+### Single select
+
+Pass `items` to render a list of options. Each item should have an `id` and a `label` property if using the default item renderer. You can also pass a custom item renderer to render each item as you need (see [Custom item renderer](#custom-item-renderer)).
+
+```tsx
+const animals = [
+  { id: '1', label: 'Dog' },
+  { id: '2', label: 'Cat' },
+  { id: '3', label: 'Bird' },
+];
+
+<SelectField label="Animal" placeholder="Select" items={animals} />
+```
+
+### Multiple select
+
+Set `selectionMode="multiple"` when more than one value can be selected. Selected options render as tags in the input.
+
+```tsx
+const states = [
+  { id: '1', label: 'California' },
+  { id: '2', label: 'New York' },
+  { id: '3', label: 'Texas' },
+];
+
+<SelectField label="States" selectionMode="multiple" defaultValue={['CA', 'NY']} items={states} />
+```
+
+### Custom item renderer
+
+When the default item renderer doesn't meet your needs, you can provide a custom item renderer. Each item **must** be a `SelectField.Item` or `SelectField.Section` component. `SelectField.Item` should be passed an `id` and `textValue` prop. `textValue` is used for typeahead and accessibility naming.
+
+:::warning
+
+For performance reasons, custom item renderers are cached on component mount. Custom item render functions should be pure functions that take only the passed item as an argument. Any reliance on external state or props will mostly likely cause unexpected and undesired behavior.
+
+:::
+
+```tsx
+const users = [
+  { id: '1', name: 'Malcolm Reynolds', email: 'malcolm.reynolds@example.com' },
+  { id: '2', name: 'Inara Serra', email: 'inara.serra@example.com' },
+  { id: '3', name: 'Kaylee Frye', email: 'kaylee.frye@example.com' },
+];
+
+<SelectField label="Users" selectionMode="multiple" defaultValue={['1', '2']} items={users}>
+  {(user) => (
+    <SelectField.Item id={user.id} textValue={user.name}>
+      <div>{user.name}</div>
+      <div>{user.email}</div>
+    </SelectField.Item>
+  )}
+</SelectField>
+```
+
+### Searchable options
+
+Enable `canSearch` for longer lists so users can filter options inside the popover.
+
+```tsx
+const categories = [
+  { id: '1', name: 'Electronics' },
+  { id: '2', name: 'Clothing' },
+  { id: '3', name: 'Books' },
+  // ...
+  { id: '100', name: 'Other' },
+];
+
+<SelectField label="Category" items={categories} canSearch searchPlaceholder="Search categories">
+  {(item) => (
+    <SelectField.Item id={item.id} textValue={item.name}>
+      {item.name}
+    </SelectField.Item>
+  )}
+</SelectField>
+```
+
+When a search matches none of the options, the popover shows "No results" in place of the option list.
+
+### Sections
+
+Organize larger option lists into labeled groups by passing `items` with nested `children`, using the default item renderer. If a section has no visible `label`, provide `aria-label` on the section.
+
+```tsx
+const items = [
+  {
+    id: 'fruit',
+    label: 'Fruit',
+    children: [
+      { id: 'apple', label: 'Apple' },
+      { id: 'banana', label: 'Banana' },
+    ],
+  },
+  {
+    id: 'veg',
+    label: 'Vegetable',
+    children: [
+      { id: 'broccoli', label: 'Broccoli' },
+      { id: 'carrots', label: 'Carrots' },
+    ],
+  },
+];
+
+<SelectField label="Healthy Snack" placeholder="Select an item" items={items} />
+```
+
+Sections can also be built with `SelectField.Section` and `SelectField.Header` JSX children when using static options instead of `items`.
+
+### Item icons
+
+When an item has an `icon`, it renders before the label in the list. Selecting that item also shows the icon in the trigger for single select, or in the tag for multiple select.
+
+```tsx
+const items = [
+  { id: '1', label: 'Favorites', icon: StarIcon },
+  { id: '2', label: 'Settings', icon: CogIcon },
+  { id: '3', label: 'Help', icon: HelpIcon },
+];
+
+<SelectField label="Menu" items={items} />
+```

package/docs/core-tabnav--design.md

@@ -71,6 +71,8 @@ TabNav uses link-based navigation. The following apply:
 * Active nav links have `aria-current="page"` set.
 * Tabs that contain a dropdown use a button with `aria-haspopup="menu"` and `aria-expanded` set.
 * Dropdown menu items use the Menu component with appropriate roles.
+* The tab bar does not add outer spacing for surrounding layout. Handle page-level spacing where `TabNav` is composed.
+* Interactive tabs and sub-items keep the `.tab` styles on the focusable element so hover, active, and focus treatments match the hit target.
 
 ### Orientation
 

package/docs/core-tabnav--usage.md

@@ -8,7 +8,8 @@ TabNav provides a horizontal or vertical navigation styled as tabs. Tab items ar
 | `style` | `never` | No | `--` | Inline styles are not supported; use component props or `FORCE__className`. |
 | `FORCE__className` | `string` | No | `--` | 🚨 This prop is meant to be an escape hatch. 🚨<br><br>If the desired style cannot be achieved using component props, use this as a last resort. The inner workings of Capra components are implementation details and this escape hatch gives one access to those implementation details. We cannot make any guarantees that styles will applied correctly across version updates. Please use it responsibly.<br><br>Add a CSS class to the component. |
 | `activeKey` | `string` | No | `--` | Key of the currently active tab (for visual styling). Typically derived from the current URL. |
-| `onTabClick` | `(key: string, event: React.MouseEvent) => void` | No | `--` | Callback when a tab link is clicked (before navigation). |
+| `onTabPress` | `(key: string) => void` | No | `--` | Callback when a tab link is pressed (before navigation). |
+| `onTabClick` | `(key: string, event: React.MouseEvent) => void` | No | `--` | Callback when a tab link is clicked (before navigation).<br>@deprecated Use `onTabPress` instead. |
 | `items` | `TabNavItemType[]` | Yes | `--` | Tab items configuration. |
 | `tabPlacement` | `(typeof tabNavPlacements)[number]` | No | 'horizontal' | Orientation of the tab bar: horizontal (bottom) or vertical (left).<br>@default 'horizontal' |
 | `centered` | `boolean` | No | false | Whether to center the tabs.<br>@default false |
@@ -19,7 +20,7 @@ TabNav provides a horizontal or vertical navigation styled as tabs. Tab items ar
 ## Usage
 
 ```tsx
-import { TabNav } from '@capra/core';
+import { RouterProvider, TabNav } from '@capra/core';
 
 // Basic usage - tab items are links that redirect to URLs
 <TabNav
@@ -62,4 +63,21 @@ import { TabNav } from '@capra/core';
     { key: 'settings', name: 'Settings', href: '/settings' },
   ]}
 />
-```
+
+// With client-side routing
+<RouterProvider navigate={navigate}>
+  <TabNav
+    activeKey={currentPath}
+    items={[
+      { key: 'overview', name: 'Overview', href: '/overview' },
+      {
+        key: 'settings',
+        name: 'Settings',
+        subItems: [{ key: 'profile', name: 'Profile', href: '/settings/profile' }],
+      },
+    ]}
+  />
+</RouterProvider>
+```
+
+When the app provides `RouterProvider`, `TabNav` passes `href` and the rest of `RoutedLinkProps` through to navigable tabs and sub-items so routing stays client-side.

package/docs/history-changelogs-capra-core--docs.md

@@ -1,5 +1,31 @@
 # History/Changelogs/@capra-core
 
+### 1.13.0
+
+#### Minor Changes
+
+* [159e15b](https://bitbucket.org/cribl/capra-ui/commits/159e15b): Add a `SelectField` component.
+
+#### Patch Changes
+
+* [28df32f](https://bitbucket.org/cribl/capra-ui/commits/28df32f): Fix Switch background colors
+
+### 1.12.0
+
+#### Minor Changes
+
+* [1fdb8d2](https://bitbucket.org/cribl/capra-ui/commits/1fdb8d2): Add `TabNav` `onTabPress` for sub-item client-side routing support.
+
+#### Patch Changes
+
+* [9550263](https://bitbucket.org/cribl/capra-ui/commits/9550263): Fix Menu submenu viewport clipping by enabling popover flip when nested panels would overflow the screen edge.
+* [9550263](https://bitbucket.org/cribl/capra-ui/commits/9550263): Fix Menu leading icon vertical alignment with item labels.
+* [b4285e0](https://bitbucket.org/cribl/capra-ui/commits/b4285e0): Fix menu description text color when disabled.
+* [9550263](https://bitbucket.org/cribl/capra-ui/commits/9550263): Fix Menu danger item icons so leading icons inherit the same semantic foreground color as the label.
+* Updated dependencies [928c9a8](https://bitbucket.org/cribl/capra-ui/commits/928c9a8) — added new icons: AddressBook, AlignCenter, AlignJustify, AlignLeft, AlignRight, ArrowDownLeftAndArrowUpRightToCenter, ArrowTurnDownLeft, ArrowUpRightAndArrowDownLeftFromCenter, ArrowsMaximize, ArrowsMinimize, At, Backward, BackwardStep, BadgeCheck, BagShopping, Ban, Barcode, Bold, Bolt, Book, BookOpen, BoxArchive, BracketsCurly, BriefcaseMedical, Bug, Bullhorn, Bullseye, Car, CaretDownSolid, CaretLeftSolid, CaretRightSolid, CaretUpSolid, CartShopping, ChartEvents, ChartFunnel, ChartMap, ChartScatter, ChartSingle, Check, CircleCheck, CircleCheckSolid, CircleExclamation, CircleInfo, CircleInfoSolid, CirclePlusSolid, CircleQuestion, CircleR, CircleStopSolid, CircleUpFilled, CircleXmarkSolid, Code, CodeBlock, CodeBranch, CodeFork, CodeMerge, CodePullRequest, Compass, Copyright, CriblOutlined, Crown, CupTogo, Database, DiagramSankey, EmptySet, FaceFrown, FaceMeh, FaceSmile, File, FileLines, FilePlusMinus, Fire, Flask, Forward, ForwardStep, GaugeSimple, Gift, GitAlt, Grid2Plus, GripDotsVertical, HardDrive, Headphones, Heart, HeartSolid, HibernatingCloud, Highlighter, Hourglass, IdCard, Image, Italic, Keyboard, Lightbulb, LinkSlash, ListOrdered, ListTree, Lock, Mars, Message, Messages, Microphone, Mobile, MugHot, Notebook, Outbound, Palette, Paperclip, Pause, Play, Print, Qrcode, Robot, RocketLaunch, Scissors, Share, Shirt, SlashForward, Sliders, SlidersUp, SortAlphaAscending, SortAlphaDescending, SortDown, SortDownSolid, SortNumericAscending, SortNumericDescending, SortOutlined, SortUp, SortUpSolid, SpinnerThird, SquareExclamation, SquareExclamationSolid, Star, StarSolid, Store, Strikethrough, Tablet, Tag, ThumbsDown, ThumbsDownSolid, ThumbsUp, ThumbtackAngleFilled, ThumbtackAngleOutlined, Token, Trash, TriangleExclamation, TriangleExclamationSolid, Trophy, Underline, Venus, Video, Volume
+* Updated dependencies [3572a4f](https://bitbucket.org/cribl/capra-ui/commits/3572a4f) — Updated fill color for HibernatingCloud icon
+  * @capra/icons\@1.10.0
+
 ### 1.11.1
 
 #### Patch Changes

package/docs/index.md

@@ -77,6 +77,8 @@ Embedded documentation is available on the filesystem for each of these packages
 - [Core/RadioTile - Usage](./core-radiotile--usage.md)
 - [Core/Ribbon - Design](./core-ribbon--design.md)
 - [Core/Ribbon - Usage](./core-ribbon--usage.md)
+- [Core/SelectField - Design](./core-selectfield--design.md)
+- [Core/SelectField - Usage](./core-selectfield--usage.md)
 - [Core/Skeleton - Design](./core-skeleton--design.md)
 - [Core/Skeleton - Usage](./core-skeleton--usage.md)
 - [Core/SkeletonGroup - Design](./core-skeletongroup--design.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capra/core",
-  "version": "1.11.1",
+  "version": "1.13.0",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",
   "description": "Core React components for the Capra design system",
@@ -35,7 +35,7 @@
   "dependencies": {
     "react-aria": "^3.48.0",
     "react-aria-components": "^1.17.0",
-    "@capra/icons": "^1.9.0"
+    "@capra/icons": "^1.10.0"
   },
   "devDependencies": {
     "clsx": "^2.1.1",
@@ -44,7 +44,7 @@
     "storybook": "^10.4.6",
     "tsdown": "^0.22.7",
     "@private/building": "^0.1.0",
-    "@capra/theme": "^1.4.0",
+    "@capra/theme": "^1.5.0",
     "@private/linting": "^0.0.1",
     "@private/stories": "^0.0.0",
     "@private/testing": "^0.0.7"