@cognite/aura 0.3.2 → 0.3.4

package/DESIGN.md

@@ -2135,21 +2135,73 @@ App icons identify **products, workspaces, or integrations** (launcher tiles, ch
 
 ### System icons
 
-System icons are **functional** shorthand for actions, state, and navigation. Aura standardizes on **Tabler Icons** (`@tabler/icons-react` in the library). Names describe intent — **do not repurpose** an icon for an unrelated meaning.
+System icons are **functional** shorthand for actions, state, and navigation. Aura standardizes on **Tabler Icons** (`@tabler/icons-react` in the library). Names describe intent — **do not repurpose** an icon for an unrelated meaning. For the full set of icons, visit [tabler.io/icons](https://tabler.io/icons), or search for a single icon by name with a query parameter: https://tabler.io/icons?icon={icon_name}.
 
 **Sizes**
 
 - **Default / recommended:** 16×16px
-- **Accepted in UI components:** 12×12px, 14×14px, 16×16px (match the component’s density; Aura primitives often default to **16px** via `size-4` classes on icons)
+- **Accepted in UI components:** 12×12px, 14×14px, 16×16px, 24×24px (match the component’s density; Aura primitives often default to **16px** via `size-4` classes on icons) with a stroke weight of 1.5px.
 
 **Guidance**
 
-- **Must** use **filled** variants where brand or application chrome calls for weight (e.g. persistent app strip); use **outlined** variants for in-product actions and navigation unless a specific Aura component specifies otherwise.
+- **Must** use **filled** variants where brand or application chrome calls for weight or within sonner-toast or alert components (e.g. persistent app strip); use **outlined** variants for in-product actions and navigation unless a specific Aura component specifies otherwise.
 - **Must not** edit, merge, or warp glyphs; icons stay **single-color** (typically `currentColor` so **Tokens** foreground colors apply). Exceptions: **branded** marks supplied as dedicated assets (see below).
 - **Must not** hang hover, active, or focus styling on the raw icon — those states belong on the **control** (button, link, menu item).
 - **Should** limit how many distinct icons compete on one view so each stays recognizable.
 - **Avoid** icon-only interactive targets without a **Tooltip** or visible label (see accessibility).
 
+**Action icons**
+
+Action icons represent operations a user can perform that trigger a change in state, content, or system behavior. They typically appear in interactive, contextual components like buttons, toolbars, context menus, dropdown menus, and inline controls.
+
+| Concept | Icon name | Source | Keywords / aliases | Accepted labels |
+|---|---|---|---|---|
+| Add / New | `plus` | [Tabler](https://tabler.io/icons?icon=plus) | create, add, new, insert | Add, Create |
+| Cancel | `cancel` | [Tabler](https://tabler.io/icons?icon=cancel) | abort, stop | Cancel |
+| Collapse (window) | `arrows-diagonal-minimize-2` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal-minimize-2) | exit fullscreen, collapse, minimize | Collapse |
+| Copy | `copy` | [Tabler](https://tabler.io/icons?icon=copy) | duplicate, clone | Copy |
+| Delete | `trash` | [Tabler](https://tabler.io/icons?icon=trash) | delete, destroy | Delete |
+| Download | `download` | [Tabler](https://tabler.io/icons?icon=download) | save to file, export file | Download |
+| Edit | `pencil` | [Tabler](https://tabler.io/icons?icon=pencil) | modify, rename, update | Edit |
+| Expand (window) | `arrows-diagonal` | [Tabler](https://tabler.io/icons?icon=arrows-diagonal) | fullscreen, expand, maximize | Expand |
+| Filter | `filter` | [Tabler](https://tabler.io/icons?icon=filter) | narrow, refine, search filters | Filter |
+| Hide | `eye-off` | [Tabler](https://tabler.io/icons?icon=eye-off) | hide; conceal, invisible, toggle visibility | Hide |
+| Link | `link` | [Tabler](https://tabler.io/icons?icon=link) | hyperlink, relationship, connected | — |
+| More options (menu opens above or below) | `dots-vertical` | [Tabler](https://tabler.io/icons?icon=dots-vertical) | overflow, actions, kebab menu | — |
+| Notifications | `bell` | [Tabler](https://tabler.io/icons?icon=bell) | alerts, notification center | Notifications |
+| Open external link | `external-link` | [Tabler](https://tabler.io/icons?icon=external-link) | open in new tab, link out | Open |
+| Publish | `rocket` | [Tabler](https://tabler.io/icons?icon=rocket) | deploy, release, go live, launch | Publish |
+| Redo | `arrow-forward-up` | [Tabler](https://tabler.io/icons?icon=arrow-forward-up) | step forward, redo | Redo |
+| Refresh | `reload` | [Tabler](https://tabler.io/icons?icon=reload) | reload page, refresh view | Refresh |
+| Remove / Close | `x` | [Tabler](https://tabler.io/icons?icon=x) | close, dismiss, remove, exit | Close, Remove |
+| Save | `check` | [Tabler](https://tabler.io/icons?icon=check) | save changes, confirm, persist, write | Save |
+| Search | `search` | [Tabler](https://tabler.io/icons?icon=search) | find, look up, query | Search |
+| Settings | `settings` | [Tabler](https://tabler.io/icons?icon=settings) | configure, preferences, gear | Settings |
+| Share | `share` | [Tabler](https://tabler.io/icons?icon=share) | send, distribute, invite | Share |
+| Show | `eye` | [Tabler](https://tabler.io/icons?icon=eye) | show; reveal, visible, unhide | Show |
+| Sync | `refresh` | [Tabler](https://tabler.io/icons?icon=refresh) | synchronize, pull latest, update data | Sync |
+| Undo | `arrow-back-up` | [Tabler](https://tabler.io/icons?icon=arrow-back-up) | revert, undo, step back | Undo |
+| Upload | `upload` | [Tabler](https://tabler.io/icons?icon=upload) | import from file, attach | Upload |
+
+**Navigation icons**
+
+Navigation icons represent spatial or positional concepts that help users understand where they are, where they can go, or how to move through an interface. They typically appear in structural, persistent components like sidebars, top bars, breadcrumbs, tabs, and pagination controls.
+
+| Concept | Icon name | Source | Keywords / aliases | Accepted labels |
+|---|---|---|---|---|
+| App switcher | `grid-dots` | [Tabler](https://tabler.io/icons?icon=grid-dots) | apps, modules, switcher, launcher | — |
+| Back | `arrow-left` | [Tabler](https://tabler.io/icons?icon=arrow-left) | back, go back, previous, navigate back | Back |
+| Home | `home` | [Tabler](https://tabler.io/icons?icon=home) | root, dashboard, start, homepage | Home |
+| Open | `chevron-down` | [Tabler](https://tabler.io/icons?icon=chevron-down) | expand, open, closed or opened state | — |
+| Close | `chevron-up` | [Tabler](https://tabler.io/icons?icon=chevron-up) | collapse, close, opened state | — |
+| Open, Next page | `chevron-right` | [Tabler](https://tabler.io/icons?icon=chevron-right) | expand, open, closed state, next, right | — |
+| Last page, skip | `chevrons-right` | [Tabler](https://tabler.io/icons?icon=chevrons-right) | last page, pagination, skip to end | — |
+| Previous page | `chevron-left` | [Tabler](https://tabler.io/icons?icon=chevron-left) | previous, left | — |
+| First page, skip | `chevrons-left` | [Tabler](https://tabler.io/icons?icon=chevrons-left) | first page, pagination, skip to start | — |
+| Location | `map-pin` | [Tabler](https://tabler.io/icons?icon=map-pin) | place, geographic, anchor, location, plant, site, rig, factory, warehouse | — |
+| Sign in | `login-2` | [Tabler](https://tabler.io/icons?icon=login-2) | log in, authenticate, sign in | Sign in |
+| Sign out | `login` | [Tabler](https://tabler.io/icons?icon=login) | log out, sign out, exit session | Sign out |
+
 **Branded icons**
 
 Rare exceptions (third-party or Cognite logos inside a cell) use **provided SVGs only** — same rules as app icons for distortion and clear space; color may be multi-hue **only** when the asset is the official brand mark.
@@ -2157,12 +2209,89 @@ Rare exceptions (third-party or Cognite logos inside a cell) use **provided SVGs
 **Accessibility**
 
 - **Must** meet **4.5:1** contrast against the icon’s background (same bar as body text when the icon communicates meaning).
-- **Must** give icon-only controls an accessible name (`aria-label` / `aria-labelledby`) **and** a **Tooltip** on hover/focus where the design hides the text label.
+- **Must** give icon-only controls an accessible name (`aria-label` / `aria-labelledby`) **and** a
+**Tooltip** on hover/focus where the design hides the text label.
 - Icons that only repeat the meaning of adjacent visible text **should** be `aria-hidden="true"`.
 
 ### Motion (reference)
 
-Short UI motion (e.g. accordion height) uses **~0.2s ease-out** in utilities; there is no separate “motion duration” token table in Aura today — follow component and `tw-animate-css` patterns.
+#### Motion
+
+**What this is:** the rules for **when**, **how fast**, and **how** something should move in Aura-based UIs — durations, easing curves, and which properties to animate — so engineers and agents pick consistent motion instead of inventing values per component. 
+
+**Motion roles**
+
+Every animation plays one of two roles. Role determines how visible, fast, and expressive it should be.
+
+- **Productive motion** — supports without drawing attention: menus opening, content fading in, cards rearranging, tooltips. **Must** be fast, subtle, and functional — barely conscious, but noticeably missing if removed.
+- **Expressive motion** — motion people are meant to see: AI generating a response, a view transition, onboarding. **Should** take more time, use more of the aurora accent language, and be more visible — these are the moments that give Aura character.
+- **Must not** let productive motion compete with whatever the user is actually focused on.
+
+**Timing**
+
+- **Must** scale duration to distance and area: small, local changes (checkbox, toggle) get shorter durations; large or page-level transitions get longer ones. Values are relative to each other within one experience, not absolute.
+- Reference bands: **short** motion (state changes, small components) stays under **~200ms**; **longer** expressive transitions (page-level, content entrances) run **~400–500ms**.
+- **Should** use **stagger** — a timing offset between elements animating in sequence rather than all at once — for groups of similar items (list rows, dashboard cards, revealed menu items). Typical offset: **~30–35ms per item**.
+- **Must not** apply stagger to elements leaving the screen — exits animate together, without a staggered trail.
+- **Should** make exits slightly quicker than entrances for the same element — once the user has acted, the UI does not need to hold their attention on the way out.
+
+**Easing**
+
+Easing is the rate of speed change — it makes motion feel physical rather than mechanical. Use `cubic-bezier` curves, not linear or default browser easing.
+
+| Curve | cubic-bezier | Use |
+| :--- | :--- | :--- |
+| Standard | `(0.40, 0.00, 0.15, 1.00)` | Motion between two states — most repositioning and in-view transitions |
+| Entrance | `(0.00, 0.00, 0.15, 1.00)` | Elements appearing — decelerates into place, arrives with momentum and lands softly |
+| Exit | `(0.67, 0.00, 0.83, 0.83)` | Elements leaving — accelerates away, lifts off and clears the view decisively |
+| Sine | `(0.33, 0.00, 0.67, 1.00)` | Near-linear; opacity fades and subtle color shifts where a strong ease would distract |
+
+- **Should** treat heavier or larger elements as slower to start and more settled on arrival; lighter, smaller elements can respond and land more quickly.
+- **Must not** let easings overshoot or bounce — restraint is part of the Aura feel (see **Animation anchors**, Calm).
+
+**Tailwind implementation**
+
+Aura has no custom `duration-*`/`ease-*` theme tokens — use [Tailwind's transition utilities](https://tailwindcss.com/docs/transition-duration) directly, matching existing components (`accordion.tsx`, `tabs.tsx`, `segmented-control.tsx`):
+
+| Concept | Tailwind utility |
+| :--- | :--- |
+| Duration | `duration-150` / `duration-200` / `duration-300`, or an arbitrary value like `duration-[233ms]` for values off the default scale |
+| Standard / Entrance / Exit / Sine easing | Tailwind's built-in `ease-*` keywords don't match Aura's curves — use an arbitrary value, e.g. `ease-[cubic-bezier(0.40,0.00,0.15,1.00)]` |
+| Which properties animate | `transition-[property-list]`, e.g. `transition-[top,left,width,height]` (see `tabs.tsx`), rather than the broader `transition-all` |
+| Stagger | `delay-[Nms]` per item (arbitrary value, since Tailwind has no stagger primitive), or `[animation-delay:Nms]` when using `@keyframes` |
+| Respect reduced motion | Prefix with `motion-safe:` (already used in `tabs.tsx`, `segmented-control.tsx`) so the transition is skipped for users with reduced-motion enabled |
+
+**What to animate**
+
+Every animation is built from a combination of these properties:
+
+| Property | Use |
+| :--- | :--- |
+| Position | Moving elements on screen — the most common property for entrances, exits, and layout transitions |
+| Scale | Growing or shrinking — drawing attention or showing hierarchy |
+| Rotation | Less common in UI; adds dynamism when used with restraint |
+| Opacity | Fading in/out — often paired with position or scale for softer transitions |
+| Color | Shifting an element's color — state changes, hover feedback, the aurora accent language |
+| Mask / morph | Revealing through a mask or transforming one shape into another — expressive moments, progressive disclosure |
+
+- **Should** combine 2–3 properties per transition (e.g. position + opacity) rather than relying on one alone.
+- **Avoid** animating more properties than the moment needs — restraint keeps productive motion productive.
+
+**Animation anchors**
+
+Three qualities every Aura animation should reinforce. Use them to test a motion design, not as literal component names.
+
+- **Flow** — continuity. Elements arrive and leave with direction and connection; nothing jumps or teleports. Groups reveal with a natural stagger. *Test: can I follow the motion with my eyes without losing my place?*
+- **Calm** — confidence in restraint. Motion never competes with the industrial data it's presenting. Easings don't overshoot, staggers don't drag, nothing bounces when it should settle. Calm does not mean slow — most motion is quiet **and** fast. *Test: does this still feel good after 8 hours of use?*
+- **Tactile** — motion builds intuition. Buttons snap, panels slide from the edge they belong to, cards lift when selected — the way something moves signals what's possible before the user thinks about it. *Test: can I tell what's interactive just by how it moves?*
+
+**Reference example — anatomy of a transition**
+
+Illustrative breakdown of a dropdown + content entrance, showing how role, timing, easing, and stagger combine (values are examples, not fixed tokens):
+
+- **Dropdown open** (~233ms total): panel expands with **entrance easing**, 200ms — `transition-[height] duration-200 ease-[cubic-bezier(0.00,0.00,0.15,1.00)]`; list items fade in with a **33ms stagger** per item — `transition-opacity duration-150` plus `delay-[calc(var(--item-index)*33ms)]` (or per-item inline `style={{ transitionDelay: … }}` when the index isn't known at build time).
+- **Dropdown close** (~233ms total, faster exit): panel and list items fade out together with **exit easing**, no stagger on the way out — `transition-[height,opacity] duration-150 ease-[cubic-bezier(0.67,0.00,0.83,0.83)]`; button copy cross-fades to the new selection with a brief accent wipe for confirmation.
+- **Content entrance** (~467ms total, expressive): main content scales in from 110% with **entrance easing** — `transition-[transform,opacity] duration-[300ms] ease-[cubic-bezier(0.00,0.00,0.15,1.00)]`; supporting elements (buttons, separators) follow with a **~100–133ms stagger** via `delay-[100ms]`/`delay-[133ms]`; any internal line/chart animation runs slower and separately so it doesn't compete for attention.
 
 ---
 

package/README.md

@@ -10,7 +10,7 @@ Aura exports Cognite's UI components, styles, utilities, and ESLint guidance for
 
 Aura ships two flavours of component import. Both resolve through the package's `exports` map — never reach into `src/`.
 
-**Per-component subpath (preferred for app code)** keeps bundles small by only pulling in what each module actually needs:
+**Per-component subpath (strongly preferred for app code)** keeps bundles small *and* keeps builds fast by only pulling in what each module actually needs:
 
 ```tsx
 import { Button } from '@cognite/aura/components/button';
@@ -18,12 +18,33 @@ import { Card } from '@cognite/aura/components/card';
 import { DatePicker } from '@cognite/aura/components/date-time-pickers';
 ```
 
-**Aggregate barrel** is convenient for stories, prototypes, and code that already pulls in many components. The barrel is side-effect-free (`*.css` aside) and tree-shakes well in modern bundlers, so prefer whichever style reads better at the call site:
+**Aggregate barrel** is convenient for stories, prototypes, and code that already pulls in many components:
 
 ```tsx
 import { Button, Card } from '@cognite/aura/components';
 ```
 
+> ⚠️ **The barrel is not free at build time.** Even though the runtime output tree-shakes (the barrel is side-effect-free apart from `*.css`), a bundler must still *load and transform* every module the barrel re-exports before tree-shaking can drop the unused ones. That includes heavy graphs such as `shiki` (via `CodeBlock`) and `mermaid` + `streamdown` (via `Message`). For a small app this can mean transforming ~10k modules and exhausting the default Node heap (`JavaScript heap out of memory`). Reaching for a single component from the barrel (`import { Card } from '@cognite/aura/components'`) pays this whole cost. Use per-component subpaths in app code; reserve the barrel for stories/prototypes.
+
+Lightweight components never pull the heavy graphs: `shiki` is only imported by `@cognite/aura/components/code-block`, and `mermaid`/`streamdown` only by `@cognite/aura/components/message`. Importing e.g. `@cognite/aura/components/card` (or the shared `@cognite/aura/utils` `cn` helper) pulls neither — the `cn` helper is deliberately kept in a module that has no path to `shiki`.
+
+> The `highlightCode` helper (Shiki wrapper) previously lived on `@cognite/aura/utils`. It now has its own entry point, `@cognite/aura/highlight-code`, so that importing `cn` from `@cognite/aura/utils` never drags Shiki into your build graph.
+
+**System icons** are provided by Tabler through Aura's icon entry point. Use named imports so application bundlers can tree-shake unused icons:
+
+```tsx
+import { IconSearch, IconSettings } from '@cognite/aura/icons';
+```
+
+Aura styles default Tabler icons to 16px with a 1.5px stroke. Override these defaults with Tailwind utilities, which take precedence over Aura's base styles:
+
+```tsx
+<IconSearch />
+<IconSettings className="size-6 stroke-2" />
+```
+
+Use `size-*` and `stroke-*` utilities rather than Tabler's `size` and `stroke` props when Aura styles are loaded, because CSS takes precedence over SVG presentation attributes.
+
 Stylesheets and tokens are imported the same way regardless of which component-import style you use:
 
 ```tsx
@@ -33,7 +54,7 @@ import '@cognite/aura/styles.css';
 
 Canonical token sources in this repo: `src/colors.css` and `src/styles.source.css`. In consuming apps, import from the published package paths above — not from `src/` next to your app code.
 
-Do not import Aura through relative paths from another project, such as `../../../libs/aura/src/components`. Fusion resolves Aura through its package exports, so use `@cognite/aura/components` (or a per-component subpath), `@cognite/aura/colors.css`, and `@cognite/aura/styles.css`.
+Do not import Aura through relative paths from another project, such as `../../../libs/aura/src/components`. Fusion resolves Aura through its package exports, so use `@cognite/aura/components` (or a per-component subpath), `@cognite/aura/icons`, `@cognite/aura/colors.css`, and `@cognite/aura/styles.css`.
 
 #### Adding a new component
 

package/dist/components/index.d.ts

@@ -19,13 +19,17 @@ export { RadioGroup, RadioGroupItem, RadioGroupItemControl, RadioGroupItemDescri
 export { Badge, badgeVariants } from './ui/core/badge/badge';
 export { Banner, BannerAction, BannerActions, BannerClose, BannerIcon, BannerStatus, BannerTitle, } from './ui/core/banner/banner';
 export { Breadcrumb, BreadcrumbEllipsis, BreadcrumbEllipsisButton, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbPageButton, BreadcrumbSeparator, } from './ui/core/breadcrumb/breadcrumb';
+export { type CollapseStrategy } from './ui/core/overflow-list/overflow-list.utils';
 export { Topbar, TopbarAction, TopbarBreadcrumbs, TopbarCenter, TopbarIcon, TopbarLeft, TopbarMetadata, TopbarRight, TopbarThemeSwitcher, type TopbarTheme, } from './ui/core/topbar/topbar';
 export { Collapsible, CollapsibleContent, CollapsibleTrigger, } from './ui/core/collapsible/collapsible';
 export { HoverCard, HoverCardTrigger, HoverCardContent, } from './ui/core/hover-card/hover-card';
 export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, } from './ui/core/select/select';
 export { SegmentedControl, SegmentedControlButton, SegmentedControlContent, SegmentedControlList, segmentedControlButtonVariants, segmentedControlListVariants, } from './ui/core/segmented-control/segmented-control';
 export { Skeleton } from './ui/core/skeleton/skeleton';
+export { Slider } from './ui/core/slider/slider';
+export { Switch } from './ui/core/switch/switch';
 export { Toaster, toast } from './ui/core/sonner-toast/sonner-toast';
+export { Combobox } from './ui/core/combobox/combobox';
 export { Input } from './ui/core/input/input';
 export { Kbd, KbdGroup } from './ui/core/kbd/kbd';
 export { Progress } from './ui/core/progress/progress';
@@ -48,6 +52,6 @@ export { Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverHeade
 export { Pagination, PaginationContent, PaginationEllipsis, PaginationFirst, PaginationItem, PaginationLast, PaginationLink, PaginationNext, PaginationPrevious, PaginationResultsPerPage, PaginationResultsPerPageLabel, PaginationSelectTrigger, PaginationStatus, PaginationTeleport, } from './ui/core/pagination/pagination';
 export { Sources, SourcesTitle, Source } from './ui/core/sources/sources';
 export { DatePicker, DateRangePicker, DateTimeRangePicker, TimePicker, } from './ui/core/date-time-pickers';
-export type { DatePickerProps, DateRangePickerProps, DateTimeRangePickerProps, ShortcutItem, TimeFormat, TimePickerProps, } from './ui/core/date-time-pickers';
+export type { AmPm, DatePickerProps, DateRangePickerProps, DateTimeRangePickerProps, ShortcutItem, TimeFormat, TimePickerProps, } from './ui/core/date-time-pickers';
 export { PortalContainerContext } from '../lib/portal-container-context';
 export type { ComponentMeta, ComponentStatusType } from '../lib/types';