@capra/core 1.5.3 → 1.7.0

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

@@ -0,0 +1,7 @@
+# Core/PasswordField - Design
+
+Password field with a trailing control to show or hide the value. Composes {@link TextField}; visibility toggles the underlying input between `password` and `text`.
+
+## Accessibility
+
+`PasswordField` is a thin wrapper around `TextField` with `type="password"` and a visibility toggle. It inherits the same keyboard support, focus management, and labeling expectations as `TextField`: associate a visible label, keep error text programmatically linked, and ensure the toggle remains reachable and operable via keyboard.

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

@@ -0,0 +1,3 @@
+# Core/PasswordField - Usage
+
+Password field with a trailing control to show or hide the value. Composes {@link TextField}; visibility toggles the underlying input between `password` and `text`.

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

@@ -0,0 +1,94 @@
+# Core/Pill - Design
+
+## Variants
+
+### Default
+
+Default pills communicate information neutral of intent.
+
+### Info
+
+Information pills communicate general information or an important property.
+
+### Danger
+
+Danger pills communicate problems that require action to be resolved.
+
+### Warning
+
+Warning pills can communicate information that is time-sensitive, or trending towards an 'attention' state.
+
+### Success
+
+Success pills communicate successful states or completed actions.
+
+### Highlight
+
+Highlight pills bring special attention to metadata without communicating status.
+
+## Other properties
+
+### Label
+
+Labels should use short and clear messaging, in one or two words. Labels are required.
+
+### Icon
+
+An optional icon is available. Use solid icons.
+
+## Style
+
+### Bold
+
+Pills have a bold and muted style.
+
+* **Bold**: Can be used for isolated pills, such as when in the header of an object details page. Use bold pills with caution, since they can easily distract from the primary content. Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.
+* **Muted**: Used when pills are inline with other content, such as table cells.
+
+### Muted
+
+Pills have a bold and muted style.
+
+* **Bold**: Can be used for isolated pills, such as when in the header of an object details page. Use bold pills with caution, since they can easily distract from the primary content. Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.
+* **Muted**: Used when pills are inline with other content, such as table cells.
+
+### Hollow
+
+Pills have a bold and muted style.
+
+* **Bold**: Can be used for isolated pills, such as when in the header of an object details page. Use bold pills with caution, since they can easily distract from the primary content. Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.
+* **Muted**: Used when pills are inline with other content, such as table cells.
+
+## Best Practices
+
+**Do**
+
+<img src="pill-bestpractices-label-do.png" />
+
+<p>
+  Do provide label that succinctly communicates the pill's messaging.
+</p>
+
+**Don't**
+
+<img src="pill-bestpractices-label-dont.png" />
+
+<p>
+  Don't us a pill with just an icon.
+</p>
+
+**Do**
+
+<img src="pill-bestpractices-interaction-do.png" />
+
+<p>
+  Do use pills to message and inform the user.
+</p>
+
+**Don't**
+
+<img src="pill-bestpractices-interaction-dont.png" />
+
+<p>
+  Don't use a tooltip or make a pill interactive.
+</p>

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

@@ -0,0 +1,10 @@
+# Core/Pill - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `children` | `string` | Yes | `--` | The label text to display in the pill. The label should use short and clear messaging, in one or two words. Labels are required. |
+| `icon` | `React.ReactNode` | No | `--` | Overrides the default icon shown based on the pill appearance and variant.<br><br><b>To use this prop you will need a design review!</b> |
+| `variant` | `'bold' \| 'muted' \| 'outline'` | No | 'bold' | A variant to apply to the pill. Only applies when the appearance is not 'default'.<br><br><ul><br>  <li><br>    'bold' - Can be used for isolated pills, such as when in the header of an object details page.<br>    Use bold pills with caution, since they can easily distract from the primary content.<br>    Be cautious with multiple bold pills on a single page, and absolutely avoid multiple bold pills in close proximity.<br>  </li><br>  <li>'muted' - Used when pills are inline with other content, such as table cells.</li><br></ul><br><br>@default 'bold' |
+| `appearance` | `'default' \| 'info' \| 'danger' \| 'warning' \| 'success' \| 'highlight'` | No | 'default' | The appearance of the pill, which determines its color and severity.<br><br><ul><br>  <li>'info' - Information pills communicate general information or an important property.</li><br>  <li>'danger' - Danger pills communicate problems that require action to be resolved.</li><br>  <li>'warning' - Warning pills can communicate information that is time-sensitive, or trending towards a danger state.</li><br>  <li>'success' - Success pills communicate successful states or completed actions.</li><br>  <li>'highlight' - Highlight pills bring special attention to metadata without communicating status.</li><br></ul><br><br>@default 'default' |
+| `inline` | `boolean` | No | false | Whether to render the pill as an inline element. This is useful when the pill is used in a heading or other inline context.<br><br>By default, the pill will be rendered as a block element.<br><br>@default false |
+| `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. |

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

@@ -0,0 +1,25 @@
+# Core/Popover - Design
+
+A popover component that renders a trigger and popover content.
+
+### Placement
+
+The popover can be positioned relative to the trigger element in 12 different directions. The default
+placement is `top`.
+
+## Accessibility
+
+### Keyboard interaction
+
+| Key      | Function                                                                                                                      |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Escape` | Closes the popover and returns focus to the trigger.                                                                          |
+| `Tab`    | Moves focus to the next focusable element. If the popover contains focusable elements, they are included in the tab sequence. |
+
+### WAI-ARIA Roles, States, and Properties
+
+* The popover container has `role="dialog"`.
+* The trigger has `aria-expanded` set to `true` when the popover is open, and `false` otherwise.
+* The trigger has `aria-controls` set to the ID of the popover content.
+* The popover has `aria-hidden` set to `false` when open, and `true` when hidden (unless removed from DOM).
+* The popover has `aria-describedby` pointing to the content element.

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

@@ -0,0 +1,8 @@
+# Core/Popover - Usage
+
+A popover component that renders a trigger and popover content.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `content` | `React.ReactNode` | Yes | `--` | The popover content to be displayed. |
+| `children` | `React.ReactNode` | Yes | `--` | The visible trigger element. This can be a single element or a component tree, but there MUST be a `Button` or `IconButton` in the tree. Only Capra buttons will trigger the popover. |

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

@@ -0,0 +1,39 @@
+# Core/Radio - Design
+
+A presentational radio button component. You will typically use this component within a RadioGroup component.
+
+## Properties
+
+### Label
+
+A label is required for all radio buttons. They should be as short as possible. If a label is not visible ensure the proper aria labels are set.
+
+## Behavior
+
+### Label Wrapping
+
+Labels will wrap if they are wider than the parent container. The radio button remains aligned to the top of the text box.
+
+### Radio groups
+
+Radio buttons cannot be standalone. They should always be contained within a set of at least two items. The group title is required to clarify how the options are related and what decision is being made.
+
+## Best Practices
+
+### Logical defaults
+
+Whenever possible, a radio button group should have a logical default set.
+
+### Single Selection
+
+**Do**
+
+<p>
+  Radio buttons should only be used when a single element can be selected.
+</p>
+
+**Don't**
+
+<p>
+  Don’t use radio buttons when multiple options can be applied simultaneously.
+</p>

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

@@ -0,0 +1,8 @@
+# Core/Radio - Usage
+
+A presentational radio button component. You will typically use this component within a RadioGroup component.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string \| null` | Yes | `--` | The value of the radio button. |
+| `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. |

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

@@ -0,0 +1,5 @@
+# Core/RadioGroup - Design
+
+A control wrapper for a group of radio buttons.
+
+No content available yet. Check back soon!

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

@@ -0,0 +1,12 @@
+# Core/RadioGroup - Usage
+
+A control wrapper for a group of radio buttons.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | No | `--` | The name of the radio group, this will act as a default name if one is not provided to the child radio components. |
+| `required` | `boolean` | No | `--` | Whether the radios in the group are required |
+| `disabled` | `boolean` | No | `--` | Whether the radios in the group are disabled |
+| `value` | `string \| null` | No | `--` | The current value of the radio group |
+| `layout` | `'vertical' \| 'horizontal'` | No | 'horizontal' | Whether the radio buttons should be displayed vertically or horizontally<br>@default 'horizontal' |
+| `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. |

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

@@ -0,0 +1,5 @@
+# Core/RadioTile - Design
+
+A card variation of a radio button component. You will typically use this component within a RadioGroup component.
+
+No content available yet. Check back soon!

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

@@ -0,0 +1,10 @@
+# Core/RadioTile - Usage
+
+A card variation of a radio button component. You will typically use this component within a RadioGroup component.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `description` | `React.ReactNode` | No | `--` | Optional description text displayed below the main label in the tile. |
+| `children` | `React.ReactNode` | Yes | `--` | The main label for the tile. |
+| `icon` | `React.ReactNode` | No | `--` | Optional icon to display in the tile. |
+| `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. |

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

@@ -0,0 +1,39 @@
+# Core/Ribbon - Design
+
+A ribbon component used to highlight new features that exist in a 'preview' state. Ribbons communicate that users may encounter errors when using these features.
+
+## Properties
+
+### Color
+
+Ribbons use the 'decorative' palette by default. Use the `color` prop for preset colors (teal, green, purple). For the rare case where you need to use a custom color, use `FORCE__className` with a class that sets the `--_ribbon-background-color` CSS variable.
+
+### Label
+
+Labels highlight features of the UI.
+
+## Content
+
+### Label
+
+Use a simple short sentence, fewer than 5 words, in sentence case.
+
+## Best Practices
+
+### Preview features
+
+Use ribbons to highlight new features that are in a 'preview' state. These features may not be fully completed and users may encounter unexpected errors.
+
+## Accessibility
+
+### Keyboard interaction
+
+A ribbon is a static element, associated with other user interface controls (e.g. a card). It is not keyboard focusable by itself.
+
+### Labeling
+
+A ribbon adds context which must be announced in addition to the parent component's label. For example, "\[parent identifier], \[ribbon string]".
+
+### Color contrast
+
+When using custom colors via `FORCE__className` (e.g. setting `--_ribbon-background-color`), ensure the background color meets WCAG 2.2 Level AA contrast requirements (4.5:1 ratio) against the white foreground text.

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

@@ -0,0 +1,12 @@
+# Core/Ribbon - Usage
+
+A ribbon component used to highlight new features that exist in a 'preview' state. Ribbons communicate that users may encounter errors when using these features.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `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. |
+| `children` | `string` | Yes | `--` | The label text to display. |
+| `color` | `(typeof ribbonColors)[number]` | No | 'teal' | The color of the ribbon. One of the predefined colors (teal, green, purple).<br>For custom colors, use FORCE__className with CSS that sets --_ribbon-background-color.<br>@default 'teal' |
+| `leadingIcon` | `SvgIcon` | No | `--` | Icon to display before the ribbon text. |
+| `position` | `(typeof ribbonPositions)[number]` | No | 'right' | The position of the ribbon tail (left or right).<br>@default 'right' |
+| `trailingIcon` | `SvgIcon` | No | `--` | Icon to display after the ribbon text. |

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

@@ -0,0 +1,88 @@
+# Core/Skeleton - Design
+
+A skeleton is a graphical placeholder, reserving physical space in the page for content in cases where a service or action may be slow to resolve. A skeleton can be considered as an alternative to the progress spinner in many situations.
+
+## Properties
+
+### Title width
+
+The title width can be controlled using the `titleWidth` prop.
+
+### Paragraph
+
+The paragraph rows and width can be controlled using the `paragraph` prop.
+
+### Loading
+
+The loading state can be controlled using the `loading` prop.
+
+### Round
+
+The paragraph and title radius can be controlled using the `round` prop.
+
+### Active
+
+The animation effect can be controlled using the `active` prop.
+
+## Usage
+
+### When to use
+
+* When a resource needs long time to load
+* When the component contains lots of information (List, Card)
+* Only when loading data for the first time
+
+### When to consider something else
+
+* If the visual layout of the page is not known
+* If you need to indicate processing (use Spinner)
+* If the content can be pre-loaded without a skeleton
+
+## Best Practices
+
+**Do**
+
+<p>
+  Do maintain consistent skeleton coloring.
+</p>
+
+**Don't**
+
+<p>
+  Don't change the color of skeletons.
+</p>
+
+**Do**
+
+<p>
+  Do use skeleton loading by itself.
+</p>
+
+**Don't**
+
+<p>
+  Don't combine skeleton loading with other spinners, or other loading indicators.
+</p>
+
+## Accessibility
+
+### Alternative text
+
+The loading skeleton requires an appropriate accessible role and label.
+
+**Landmark details:**
+
+* **element**: `span` (root container)
+* **aria-label**: `"Loading"` (when loading)
+* **role**: `status` (live region)
+* **aria-busy**: `true` (when loading)
+
+<img className="w-full" src="images/guidelines/skeleton/alternative-text.png" alt="Skeleton with accessibility landmark annotation showing element, aria-label, and role" />
+
+### Color contrast
+
+Graphics and user interface components like skeletons are not required to meet minimum contrast.
+
+### Motion
+
+When `active` is true, the skeleton shows a gradient shimmer animation. The animation is automatically disabled when the user has `prefers-reduced-motion: reduce` set.

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

@@ -0,0 +1,13 @@
+# Core/Skeleton - Usage
+
+A skeleton is a graphical placeholder, reserving physical space in the page for content in cases where a service or action may be slow to resolve. A skeleton can be considered as an alternative to the progress spinner in many situations.
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `loading` | `boolean` | No | `--` | Display the skeleton when true.<br>@default true |
+| `title` | `SkeletonTitleProps \| boolean` | No | `--` | Show title placeholder.<br>@default true |
+| `paragraph` | `SkeletonParagraphProps \| boolean` | No | `--` | Show paragraph placeholder.<br>@default true |
+| `round` | `boolean` | No | `--` | Show paragraph and title radius when true.<br>@default false |
+| `active` | `boolean` | No | `--` | Show animation effect. Respects prefers-reduced-motion.<br>@default false |
+| `children` | `React.ReactNode` | No | `--` | When set together with `loading`: if `loading` is false, only `children`<br>are rendered (no skeleton). If `loading` is true, the skeleton is shown instead — for preset<br>layouts (title and/or paragraph) children are not mounted while loading; in element mode<br>(`title={false}` and `paragraph={false}`) children render inside the placeholder while loading. |
+| `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. |

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

@@ -0,0 +1,50 @@
+# Core/SkeletonGroup - Design
+
+### SkeletonGroup.Button
+
+Button-shaped placeholder.
+
+### SkeletonGroup.Input
+
+Input-shaped placeholder.
+
+### SkeletonGroup.Node
+
+Custom content placeholder.
+
+## Preset layouts
+
+SkeletonGroup provides standalone skeleton shapes. Use `Skeleton` for the preset title+paragraph layout.
+
+## Best Practices
+
+**Do**
+
+Do maintain consistent skeleton coloring.
+
+**Don't**
+
+Don't change the color of skeletons.
+
+## Accessibility
+
+### Alternative text
+
+The loading skeleton requires an appropriate accessible role and label.
+
+**Landmark details:**
+
+* **element**: `span` (root container)
+* **aria-label**: `"Loading"` (when loading)
+* **role**: `status` (live region)
+* **aria-busy**: `true` (when loading)
+
+<img className="w-full" src="images/guidelines/skeleton/alternative-text.png" alt="Skeleton with accessibility landmark annotation showing element, aria-label, and role" />
+
+### Color contrast
+
+Graphics and user interface components like skeletons are not required to meet minimum contrast.
+
+### Motion
+
+When `active` is true, the skeleton shows a gradient shimmer animation. The animation is automatically disabled when the user has `prefers-reduced-motion: reduce` set.

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

@@ -0,0 +1,10 @@
+# Core/SkeletonGroup - Usage
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `style` | `React.CSSProperties` | No | `--` | `--` |
+| `size` | `keyof typeof SKELETON_SIZE` | No | `--` | Preset dimensions from `dimension.component.*`; use `style` for custom width/height. |
+| `active` | `boolean` | No | `--` | Show animation effect. @default false |
+| `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. |
+| `block` | `boolean` | No | `--` | `--` |
+| `shape` | `'circle' \| 'round' \| 'square' \| 'default'` | No | `--` | `--` |

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

@@ -0,0 +1,99 @@
+# Core/Spinner - Design
+
+The Spinner component is used to display a loading state. It can be used in two modes: **Mode 1 - Standalone Spinner:**
+
+<p>
+  A spinner is a visual indicator of an ongoing, user-initiated process.
+</p>
+
+## Modes
+
+### Replacement Mode
+
+<p>
+  Use Replacement Mode when you want to completely hide content while loading and show the spinner instead. This is ideal for initial page loads, route transitions, or when fetching data that's required before any content can be displayed. The content and spinner never appear simultaneously—the component returns early with just the spinner when loading.
+</p>
+
+<p>
+  This mode is best for scenarios where showing partial or stale content would be confusing or misleading to users.
+</p>
+
+<p>
+  <pre>
+    ```tsx
+    if (isLoading) {
+      return <Spinner title="Loading..." />;
+    }
+    return <div>Content</div>;
+    ```
+  </pre>
+</p>
+
+### Overlay Mode
+
+<p>
+  Use Overlay Mode when you want to keep content visible while indicating an ongoing operation. The spinner appears
+  as an overlay, allowing users to see what they're waiting for or maintain context during the loading process. This
+  is perfect for refreshing data, submitting forms, or updating specific sections of a page.
+</p>
+
+<p>
+  This mode works well for progressive enhancement scenarios, search results that are being refined, or any
+  situation where the existing content provides value even during loading. It's particularly useful when you want to
+  prevent user interaction temporarily without completely removing the content from view, such as during a save
+  operation or background data synchronization.
+</p>
+
+<p>
+  <pre>
+    ```tsx
+    <Spinner title="Loading..." isPending={isLoading}>
+      <div>Content will be shown always</div>
+      <div>Will be blurred if the spinner is visible</div>
+    </Spinner>
+    ```
+  </pre>
+</p>
+
+## Properties
+
+### Label
+
+<p>
+  A label can be added to the spinner to better inform users during a loading process. Common situations in which
+  they are used include navigating to a page that is not fully known beforehand (e.g., a dashboard), or loading a
+  large set of data.
+</p>
+
+### Sizes
+
+<p>
+  Small spinners are used when in cards or other inline components. Medium spinners are the default and are
+  displayed when it represents a larger portion of the page, such as a primary data table. The large size can be
+  used when all, or most, of the page content is being loaded.
+</p>
+
+## Accessibility
+
+### Keyboard interaction
+
+<p>
+  A spinner is not a focusable element.
+</p>
+
+### Labeling
+
+<p>
+  When possible, supplement spinners with textual indicators to clarify the purpose and state.
+</p>
+
+### Focus order
+
+<p>
+  If the spinner is a blocking interaction, make sure to return focus to a relevant action once loading is complete.
+</p>
+
+### Aria considerations
+
+* Use `aria-live="polite"` to enable screen readers to notify users of the loading state.
+* When the loading state ends, remove the spinner from the DOM or hide it with `aria-hidden="true"`.

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

@@ -0,0 +1,11 @@
+# Core/Spinner - Usage
+
+The Spinner component is used to display a loading state. It can be used in two modes: **Mode 1 - Standalone Spinner:**
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | No | `--` | The size of the Spinner. @default "md" |
+| `title` | `string` | No | `--` | (optional) The title to display in the Spinner. |
+| `children` | `React.ReactNode` | No | `--` | The content to display inside the Spinner. When provided, Spinner acts as a wrapper with overlay. |
+| `isPending` | `boolean` | No | `--` | Whether the Spinner is visible. Only used when children are provided. @default true |
+| `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. |