@cognite/aura 1.46884.0 → 1.47174.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cognite/aura",
-  "version": "1.46884.0",
+  "version": "1.47174.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": [

package/src/components/ui/core/banner/banner.md

@@ -0,0 +1,51 @@
+Use a Banner for a persistent or dismissible message scoped to a page or section.
+Banners are stronger than inline helper text and stay visible while the user continues working.
+
+## When to use
+
+- Announcing environment or product state, such as maintenance, a trial period, or a feature preview.
+- Page-wide outcomes that should stay visible while the user continues.
+- Explaining why a page is read-only and offering the action that unlocks it.
+
+## When to use something else
+
+- Use an [Alert](?path=/docs/primitives-alert--docs) for task-specific guidance inside a flow.
+- Use a [Sonner Toast](?path=/docs/primitives-sonner-toast--docs) for brief confirmation after an action.
+- Use a [Dialog](?path=/docs/primitives-dialog--docs) when the user must respond before continuing.
+
+## Placement
+
+- Place Banners at the top of the page or section they describe.
+- Banners span the full width of their container by default.
+- Set `inset` to round the corners when the Banner sits inside padded content rather than edge to edge.
+
+## Variants
+
+| Variant       | Use                                                  |
+| :------------ | :--------------------------------------------------- |
+| `default`     | Neutral state, such as read-only or preview mode     |
+| `info`        | Helpful updates, such as new data being available    |
+| `warning`     | Upcoming issues, such as an expiring trial           |
+| `destructive` | Failures that affect the page, such as a failed save |
+
+## Content
+
+- Keep the title to one short sentence; Banners are a single line high.
+- Start with a `BannerIcon` that matches the variant.
+- Put actions in `BannerActions`, using `BannerAction` for actions and `BannerClose` for dismissal.
+
+## Dos and don'ts
+
+- **Do** limit actions to ones that resolve or explain the message.
+- **Do** make Banners dismissible unless the state they describe is still active.
+- **Don't** stack several Banners on one page; combine or prioritize the messages instead.
+- **Don't** use a Banner for field-level validation.
+
+## Behavior
+
+- `BannerClose` hides the Banner and calls `onClose`.
+- Use `visible` and `onClose` to control visibility, or `defaultVisible` to leave it uncontrolled.
+
+## Often used with
+
+[Button](?path=/docs/primitives-button--docs) through `BannerAction`, and [Topbar](?path=/docs/primitives-topbar--docs) above page-level Banners.

package/src/components/ui/core/input/input.md

@@ -0,0 +1,48 @@
+Use an Input to capture short, single-line text in forms and toolbars.
+
+## When to use
+
+- Collecting specific text data, such as names, credentials, or asset identifiers.
+- A form field needs free text that does not fit a structured picker.
+
+## When to use something else
+
+- Use a [Select](?path=/docs/primitives-select--docs), [Combobox](?path=/docs/primitives-combobox--docs), [Checkbox](?path=/docs/primitives-checkbox--docs), or [Radio](?path=/docs/primitives-radio-group--docs) when choosing from predefined options.
+- Use a [Combobox](?path=/docs/primitives-combobox--docs) when suggestions should appear as the user types.
+- Use a [Date Picker](?path=/docs/primitives-datepicker--docs) or [Time Picker](?path=/docs/primitives-timepicker--docs) for dates and times.
+- Use a [Textarea](?path=/docs/primitives-textarea--docs) when multi-line text is expected.
+- Use [Search](?path=/docs/primitives-search--docs) for filtering or searching content.
+
+## Content
+
+- Give every Input a visible [Label](?path=/docs/primitives-label--docs).
+- Use placeholder text only for a short example of the expected format.
+- Set `type` to match the data, such as `email`, `number`, `tel`, or `url`, so browsers offer the right keyboard and autofill.
+
+## States
+
+| State     | How to set it                                                |
+| :-------- | :----------------------------------------------------------- |
+| Default   | No extra props                                               |
+| Filled    | `value` or `defaultValue`                                    |
+| Disabled  | `disabled`, with `data-disabled="true"` on the field wrapper |
+| Read-only | `readOnly` for values users can see and copy but not edit    |
+| Error     | `aria-invalid`, with error helper text below the Input       |
+
+## Dos and don'ts
+
+- **Do** show validation messages below the Input with helper text.
+- **Do** prefer `readOnly` over `disabled` when users still need to read or copy the value.
+- **Don't** use long placeholder text that duplicates the label.
+- **Don't** mimic pre-filled content with placeholder text.
+- **Don't** wrap text inside an Input; truncate it or switch to a Textarea.
+
+## Behavior
+
+- Inputs are single-line and update as the user types.
+- Associate validation messages with the field so assistive technology announces them.
+- Use an [Input Group](?path=/docs/primitives-input-group--docs) for leading or trailing slots such as icons, prefixes, suffixes, or buttons.
+
+## Often used with
+
+[Label](?path=/docs/primitives-label--docs), [Helper Text](?path=/docs/primitives-helper-text--docs), [Button](?path=/docs/primitives-button--docs), and [Tooltip](?path=/docs/primitives-tooltip--docs).

package/src/components/ui/core/label/label.md

@@ -0,0 +1,35 @@
+Use a Label to identify a form field and associate it programmatically with that field.
+Labels are not intended as general-purpose text.
+
+## When to use
+
+- Every [Input](?path=/docs/primitives-input--docs), [Select](?path=/docs/primitives-select--docs), [Combobox](?path=/docs/primitives-combobox--docs), [Textarea](?path=/docs/primitives-textarea--docs), [Slider](?path=/docs/primitives-slider--docs), or [Date Picker](?path=/docs/primitives-datepicker--docs) needs one.
+- Groups of [Checkboxes](?path=/docs/primitives-checkbox--docs), [Radios](?path=/docs/primitives-radio-group--docs), or [Switches](?path=/docs/primitives-switch--docs) need one to name the group.
+
+## When to use something else
+
+- Use a heading for section titles.
+- Use [Helper Text](?path=/docs/primitives-helper-text--docs) for descriptive text below a field.
+- Use plain text or a [Badge](?path=/docs/primitives-badge--docs) for non-interactive elements such as status indicators.
+
+## Required fields
+
+- Set `required` on the Label to show the required asterisk.
+- `Label.required` is visual only, so also set `required` on the form control for native validation and assistive technology.
+- Mark required fields consistently across a form.
+
+## Dos and don'ts
+
+- **Do** associate every Label with its field through `htmlFor` and `id`.
+- **Do** keep Labels short and descriptive.
+- **Don't** replace Labels with placeholder text; placeholders disappear and are not reliably announced.
+- **Don't** hide Labels for visual cleanliness; use a [Tooltip](?path=/docs/primitives-tooltip--docs) to supplement shortened Labels.
+
+## Behavior
+
+- Clicking a Label focuses or toggles its associated field.
+- Wrapping the Label and field in an element with the `group` class and `data-disabled="true"` applies the disabled style to the Label.
+
+## Often used with
+
+[Input](?path=/docs/primitives-input--docs), [Select](?path=/docs/primitives-select--docs), [Combobox](?path=/docs/primitives-combobox--docs), [Checkbox](?path=/docs/primitives-checkbox--docs), [Radio](?path=/docs/primitives-radio-group--docs), [Switch](?path=/docs/primitives-switch--docs), [Slider](?path=/docs/primitives-slider--docs), [Textarea](?path=/docs/primitives-textarea--docs), and [Date Picker](?path=/docs/primitives-datepicker--docs).

package/src/components/ui/core/radio-group/radio-group.md

@@ -0,0 +1,38 @@
+Use a Radio Group to let users select exactly one option from a small set of mutually exclusive choices.
+
+## When to use
+
+- A single selection from a small, visible set of predefined options.
+- All options should be visible side by side for comparison.
+
+## When to use something else
+
+- Use a [Checkbox](?path=/docs/primitives-checkbox--docs) when multiple selections are allowed.
+- Use a [Select](?path=/docs/primitives-select--docs) or [Combobox](?path=/docs/primitives-combobox--docs) when there are more than about five options or space is limited.
+- Use a [Switch](?path=/docs/primitives-switch--docs) when the choice is binary and takes immediate effect.
+- Use a [Segmented Control](?path=/docs/primitives-segmented-control--docs) to switch between views rather than set a value.
+
+## Layout
+
+- Groups stack vertically by default; set `orientation="horizontal"` to lay options out in a row.
+- Use `variant="card"` on `RadioGroupItem` for options that need descriptions, such as plan or template choices.
+- Add `RadioGroupItemDescription` under the label when an option needs a short explanation.
+
+## Dos and don'ts
+
+- **Do** give every option a descriptive label.
+- **Do** pre-select a sensible default when one exists.
+- **Don't** group unrelated options.
+- **Don't** use more than five options.
+- **Don't** use card variants for long option lists.
+
+## Behavior
+
+- Clicking or pressing Space selects the focused option and deselects the others in the group.
+- Arrow keys move focus and selection between options.
+- Set `disabled` on the `RadioGroup` to disable every option, or on a `RadioGroupItemControl` to disable a single option.
+- Set `name` and `required` on the `RadioGroup` for native form submission.
+
+## Often used with
+
+[Label](?path=/docs/primitives-label--docs) to name the group, [Helper Text](?path=/docs/primitives-helper-text--docs), and the card variant for options that need descriptions.

package/src/components/ui/core/textarea/textarea.md

@@ -0,0 +1,42 @@
+Use a Textarea for extended, free-form, multi-line input such as comments, feedback, messages, descriptions, or notes.
+
+## When to use
+
+- Multi-line text is expected, such as comments, notes, bios, or explanations.
+- Editing large chunks of existing text.
+
+## When to use something else
+
+- Use an [Input](?path=/docs/primitives-input--docs) when a single line of text is enough.
+- Use an [Input](?path=/docs/primitives-input--docs), [Date Picker](?path=/docs/primitives-datepicker--docs), [Select](?path=/docs/primitives-select--docs), or [Combobox](?path=/docs/primitives-combobox--docs) when structured data is expected.
+- Use a rich-text editor when formatting is needed.
+- Use [Prompt Input](?path=/docs/ai-prompt-input--docs) for messages sent to an AI assistant.
+
+## Content
+
+- Give every Textarea a visible [Label](?path=/docs/primitives-label--docs).
+- Keep placeholder text concise and use it for an example, not instructions the user needs later.
+- Show a character count in helper text when there is a length limit.
+
+## Sizing
+
+- A Textarea starts at a minimum height and grows with its content.
+- Resizing by the user is disabled by default.
+- Set a maximum height with `className` when the Textarea sits in a constrained layout, so long content scrolls instead of pushing the layout.
+
+## Dos and don'ts
+
+- **Do** use concise labels and placeholder text.
+- **Do** let content scroll when it exceeds the maximum height.
+- **Don't** set a small fixed height when lengthy input is expected.
+- **Don't** pre-fill the Textarea with default text users might overlook.
+
+## States
+
+- Set `aria-invalid` and show error helper text below the Textarea when the value is invalid.
+- Set `disabled`, with `data-disabled="true"` on the field wrapper, when the field is unavailable.
+- Set `readOnly` when users need to read or copy the text but not change it.
+
+## Often used with
+
+[Label](?path=/docs/primitives-label--docs) and [Helper Text](?path=/docs/primitives-helper-text--docs), optionally with a character count.