@cognite/aura 0.2.0 → 0.3.1

package/README.md

@@ -2,30 +2,164 @@
 
 Aura exports Cognite's UI components, styles, utilities, and ESLint guidance for preserving the design system in downstream apps.
 
-## DESIGN.md (Google design.md linter)
+## Using Aura in Fusion
 
-[`DESIGN.md`](./DESIGN.md) is linted with [`@google/design.md`](https://www.npmjs.com/package/@google/design.md) via `npx`, so Aura does not need a direct package dependency on the linter.
+[`DESIGN.md`](./DESIGN.md) describes visual identity, critical interaction rules, and UX guidance for feedback, disclosure, errors, layout, and accessibility. This section covers *how to use the package* in the Fusion monorepo and host shell.
 
-Published installs ship this spec at the package root; you can resolve it as `@cognite/aura/DESIGN.md` (for example with `import.meta.resolve` or your bundler’s raw import).
+### Package imports
 
-From `fusion/libs/aura`:
+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:
+
+```tsx
+import { Button } from '@cognite/aura/components/button';
+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:
+
+```tsx
+import { Button, Card } from '@cognite/aura/components';
+```
+
+Stylesheets and tokens are imported the same way regardless of which component-import style you use:
+
+```tsx
+import '@cognite/aura/colors.css';
+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`.
+
+#### Adding a new component
+
+Every Aura component must support **both** import styles. When you add a new component:
+
+1. Place its source under `src/components/ui/core/<name>/<name>.tsx`, matching the kebab-case directory used by existing components.
+2. Re-export it from the aggregate barrel in `src/components/index.ts` so `@cognite/aura/components` keeps working.
+3. Register a per-component subpath export in `libs/aura/package.json` (alphabetical order):
+
+   ```json
+   "./components/<name>": {
+     "@fusion/source": "./src/components/ui/core/<name>/<name>.tsx",
+     "import": "./dist/components/ui/core/<name>/<name>.js",
+     "types": "./dist/components/ui/core/<name>/<name>.d.ts"
+   }
+   ```
+
+   Composite components that ship as a folder (such as `date-time-pickers`) point at the folder's `index.ts` instead.
+
+The Vite build derives library entries directly from `package.json` (`entriesFromPackageJson: true`), so once both entry points are wired the dist output and types appear automatically. The two surfaces must stay in sync — consumers should be able to choose either style without missing exports.
+
+Aura uses Tailwind v4 package CSS entry points. Consuming Fusion apps should not add a `tailwind.config.js` just to wire Aura tokens or content paths; import `@cognite/aura/styles.css` and let Aura's exported CSS carry the theme and source directives. `styles.css` is the public stylesheet entry point for product consumers; in published external packages it resolves to the built Tailwind CSS output produced by Aura's build.
+
+When another Fusion library exposes Aura-styled components, give that library the same self-sourcing setup instead of pushing scan rules into every consumer:
+
+- Export a package stylesheet, for example `@cognite/example-ui/styles.css`.
+- In that stylesheet, import `@cognite/aura/styles.source.css` and source the library itself. `styles.source.css` is for package stylesheets that compose Aura's Tailwind theme/source directives before adding their own `@source` rules:
+
+  ```css
+  @import '@cognite/aura/styles.source.css';
+  @source './';
+  ```
+
+- If the target app already relies on `!important` style precedence, for example through styled-components overrides or existing Cogs components, add Tailwind's import modifier so Aura utilities can match that setup when necessary:
+
+  ```css
+  @import '@cognite/aura/styles.source.css' important;
+  @source './';
+  ```
+
+- If the library builds or previews that stylesheet directly, include `@tailwindcss/vite` in its Vite and Storybook setup.
+- Consumers should import the library stylesheet, not Aura internals. For example, an app using `@cognite/atlas-ai-react-ui` should import `@cognite/atlas-ai-react-ui/styles.css`, which can pull in Aura internally.
+- Do not add cross-project `@source "../../../libs/..."` directives or `tailwind.config.js` `content` entries for other Fusion libraries. In Tailwind v4 these app-level content arrays do not replace package-owned `@source` directives.
+
+Prefer **CVA** variants and component APIs over overriding primitive styles. Prop names, `size` values, and subcomponents are defined in:
+
+- [Aura Storybook](https://storybook-aura-23638.fusion-preview.preview.cogniteapp.com)
+- [Aura design system docs](https://docs.cognite.com/aura-design-system/get-started)
+- TypeScript types from `@cognite/aura/components`
+
+### Fusion shell integration
+
+The Fusion host shell owns global chrome that Aura does not ship: **Topbar**, **Sonner** toasts, **AlertDialog**, **Sheet** / **Drawer**, **Tabs**, **SegmentedControl**, and some patterns like **EmptyState**. These **must** still follow Aura tokens, [Interaction states](./DESIGN.md#interaction-states), and [Heuristics](./DESIGN.md#heuristics).
+
+| Concern | Fusion convention |
+| ------- | ----------------- |
+| Primary navigation | One **Topbar**; avoid duplicating global nav in content |
+| View switching | Shell **Tabs** / **SegmentedControl** when the product uses that pattern |
+| Toasts | **Sonner**, bottom-right, ~4s auto-dismiss, themed with Aura tokens |
+| Confirm destructive work | Shell **AlertDialog** or Aura **Dialog** with explicit copy |
+| Narrow viewports | Prefer shell **Drawer** / **Dialog** over compressed multi-column chrome |
+
+For local sub-app development against the live shell, use import map overrides — see the Fusion [subapp manual testing guide](../../.cursor/rules/subapp-manual-testing.mdc).
+
+### Serve and test locally
 
 ```sh
-npx --yes @google/design.md lint ./DESIGN.md
+pnpm nx serve aura          # Storybook
+pnpm nx run aura:design-md-lint
 ```
 
-From the Fusion workspace root:
+## Optional peer dependencies
+
+Some Aura entry points require optional peer dependencies that consumers must install themselves:
+
+- `@cognite/aura/chart` requires `recharts >=3.7`. Add it to your app:
+
+  ```sh
+  pnpm add recharts
+  ```
+
+  Aura follows the [shadcn/ui Charts](https://ui.shadcn.com/docs/components/chart) pattern: import the shell and chrome from `@cognite/aura/chart`, and import Recharts primitives from `recharts`.
+
+  ```tsx
+  import { Bar, BarChart, XAxis } from 'recharts';
+  import {
+    ChartContainer,
+    ChartTooltip,
+    type ChartConfig,
+  } from '@cognite/aura/chart';
+
+  const config = {
+    runs: { label: 'Runs', color: 'var(--color-chart-fjord-color-1)' },
+  } satisfies ChartConfig;
+
+  <ChartContainer config={config} aria-label="Runs by day">
+    <BarChart data={data}>
+      <XAxis dataKey="day" />
+      <ChartTooltip />
+      <Bar dataKey="runs" fill="var(--color-runs)" />
+    </BarChart>
+  </ChartContainer>
+  ```
+
+## DESIGN.md
+
+[`DESIGN.md`](./DESIGN.md) describes Aura's visual identity in the [Google design.md](https://github.com/google-labs-code/design.md) format — YAML design tokens in front matter plus markdown rationale for coding agents.
+
+Validate structure, token references, and section order with [`@google/design.md`](https://www.npmjs.com/package/@google/design.md):
+
+**Recommended (from the Fusion workspace root):**
 
 ```sh
-cd libs/aura && npx --yes @google/design.md lint ./DESIGN.md
+pnpm nx run aura:design-md-lint
 ```
 
-Or with Nx:
+**Direct CLI (from `libs/aura`):**
 
 ```sh
-nx run aura:design-md-lint
+npx --yes @google/design.md lint ./DESIGN.md
 ```
 
+Exit code `0` means the file passed (no errors). Warnings surface issues such as orphaned tokens or out-of-order sections.
+
+Published installs ship this spec at the package root; resolve it as `@cognite/aura/DESIGN.md` (for example with `import.meta.resolve` or your bundler's raw import).
+
 ## ESLint
 
 Aura ships an ESLint plugin at `@cognite/aura/eslint`.

package/dist/colors.css

@@ -235,6 +235,18 @@
   --color-mountain-800: var(--mountain-800);
   --color-mountain-900: var(--mountain-900);
   --color-mountain-950: var(--mountain-950);
+  --color-mountain-alpha-100: var(--mountain-alpha-100);
+  --color-mountain-alpha-200: var(--mountain-alpha-200);
+  --color-mountain-alpha-300: var(--mountain-alpha-300);
+  --color-mountain-alpha-400: var(--mountain-alpha-400);
+  --color-mountain-alpha-450: var(--mountain-alpha-450);
+  --color-mountain-alpha-50: var(--mountain-alpha-50);
+  --color-mountain-alpha-600: var(--mountain-alpha-600);
+  --color-mountain-alpha-650: var(--mountain-alpha-650);
+  --color-mountain-alpha-700: var(--mountain-alpha-700);
+  --color-mountain-alpha-800: var(--mountain-alpha-800);
+  --color-mountain-alpha-900: var(--mountain-alpha-900);
+  --color-mountain-alpha-950: var(--mountain-alpha-950);
   --color-mountain-black: var(--mountain-black);
   --color-mountain-white: var(--mountain-white);
   --color-muted-background: var(--muted-background);
@@ -300,6 +312,10 @@
   --color-pink-950: var(--pink-950);
   --color-popover-background: var(--popover-background);
   --color-primary-background: var(--primary-background);
+  --color-disabled-background-fixed-dark: var(--disabled-background-fixed-dark);
+  --color-disabled-foreground-fixed-dark: var(--disabled-foreground-fixed-dark);
+  --color-primary-background-fixed-dark: var(--primary-background-fixed-dark);
+  --color-primary-background-fixed-dark-hover: var(--primary-background-fixed-dark-hover);
   --color-primary-background-hover: var(--primary-background-hover);
   --color-raised-background: var(--raised-background);
   --color-red-100: var(--red-100);
@@ -322,6 +338,8 @@
   --color-ring-muted: var(--ring-muted);
   --color-secondary-background: var(--secondary-background);
   --color-secondary-background-hover: var(--secondary-background-hover);
+  --color-secondary-background-fixed-dark: var(--secondary-background-fixed-dark);
+  --color-secondary-background-fixed-dark-hover: var(--secondary-background-fixed-dark-hover);
   --color-secondary-foreground: var(--secondary-foreground);
   --color-secondary-foreground-fixed-light: var(--secondary-foreground-fixed-light);
   --color-sky-100: var(--sky-100);
@@ -874,6 +892,10 @@
   --overlay-background: var(--mountain-alpha-300);
   --popover-background: var(--mountain-white);
   --primary-background: var(--mountain-900);
+  --disabled-background-fixed-dark: var(--mountain-alpha-50);
+  --disabled-foreground-fixed-dark: var(--mountain-650);
+  --primary-background-fixed-dark: var(--mountain-10);
+  --primary-background-fixed-dark-hover: var(--mountain-50);
   --primary-background-hover: var(--mountain-700);
   --raised-background: var(--mountain-800);
   --ring: var(--gray-500);
@@ -881,6 +903,8 @@
   --ring-destructive-muted: var(--red-100);
   --ring-muted: var(--gray-200);
   --secondary-background: var(--mountain-100);
+  --secondary-background-fixed-dark: var(--mountain-700);
+  --secondary-background-fixed-dark-hover: var(--mountain-650);
   --secondary-background-hover: var(--mountain-200);
   --secondary-foreground: var(--mountain-700);
   --secondary-foreground-fixed-light: var(--mountain-200);
@@ -1028,6 +1052,8 @@
   --overlay-background: var(--mountain-alpha-300);
   --popover-background: var(--mountain-900);
   --primary-background: var(--mountain-10);
+  --primary-background-fixed-dark: var(--mountain-10);
+  --primary-background-fixed-dark-hover: var(--mountain-50);
   --primary-background-hover: var(--mountain-100);
   --raised-background: var(--mountain-700);
   --ring: var(--gray-500);
@@ -1035,6 +1061,10 @@
   --ring-destructive-muted: var(--red-900);
   --ring-muted: var(--gray-800);
   --secondary-background: var(--mountain-700);
+  --disabled-background-fixed-dark: var(--mountain-alpha-950);
+  --disabled-foreground-fixed-dark: var(--mountain-650);
+  --secondary-background-fixed-dark: var(--mountain-700);
+  --secondary-background-fixed-dark-hover: var(--mountain-650);
   --secondary-background-hover: var(--mountain-600);
   --secondary-foreground: var(--mountain-200);
   --secondary-foreground-fixed-light: var(--mountain-200);

package/dist/components/index.d.ts

@@ -1,82 +1,53 @@
 export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, } from './ui/core/accordion/accordion';
-export { AccordionMetadata } from './ui/core/accordion/accordion.metadata';
+export { ActionToolbar, ActionToolbarAction, ActionToolbarActionClear, ActionToolbarActions, ActionToolbarPrimaryAction, ActionToolbarSelection, ActionToolbarSelectionSummary, } from './ui/core/action-toolbar/action-toolbar';
 export { Card, CardHeader, CardHeaderStart, CardHeaderCenter, CardHeaderEnd, CardFooter, CardFooterStart, CardFooterEnd, CardTitle, CardActions, CardDescription, CardContent, } from './ui/core/card/card';
-export { CardMetadata } from './ui/core/card/card.metadata';
 export { Button, buttonVariants } from './ui/core/button/button';
-export { ButtonMetadata } from './ui/core/button/button.metadata';
 export { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants, } from './ui/core/button-group/button-group';
-export { ButtonGroupMetadata } from './ui/core/button-group/button-group.metadata';
 export { Avatar, AvatarImage, AvatarFallback, AvatarIcon, } from './ui/core/avatar/avatar';
-export { AvatarMetadata } from './ui/core/avatar/avatar.metadata';
 export { Label } from './ui/core/label/label';
-export { LabelMetadata } from './ui/core/label/label.metadata';
 export { CheckboxGroup, CheckboxItem, CheckboxItemControl, CheckboxItemDescription, CheckboxItemLabel, } from './ui/core/checkbox/checkbox';
 export { CheckboxMetadata } from './ui/core/checkbox/checkbox.metadata';
 export { HelperText } from './ui/core/helper-text/helper-text';
-export { HelperTextMetadata } from './ui/core/helper-text/helper-text.metadata';
 export { Loader } from './ui/core/loader/loader';
-export { LoaderMetadata } from './ui/core/loader/loader.metadata';
 export { Shimmer } from './ui/core/shimmer/shimmer';
-export { ShimmerMetadata } from './ui/core/shimmer/shimmer.metadata';
 export { CodeBlock, CodeBlockCollapseButton, CodeBlockCopyButton, CodeBlockDownloadButton, } from './ui/core/code-block/code-block';
-export { CodeBlockMetadata } from './ui/core/code-block/code-block.metadata';
 export { Separator } from './ui/core/separator/separator';
-export { SeparatorMetadata } from './ui/core/separator/separator.metadata';
 export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from './ui/core/tooltip/tooltip';
-export { TooltipMetadata } from './ui/core/tooltip/tooltip.metadata';
 export { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput, } from './ui/core/tool/tool';
-export { ToolMetadata } from './ui/core/tool/tool.metadata';
 export { DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuHeader, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent, DropdownMenuSectionLabel, } from './ui/core/dropdown-menu/dropdown-menu';
-export { DropdownMenuMetadata } from './ui/core/dropdown-menu/dropdown-menu.metadata';
 export { RadioGroup, RadioGroupItem, RadioGroupItemControl, RadioGroupItemDescription, RadioGroupItemLabel, } from './ui/core/radio-group/radio-group';
-export { RadioGroupMetadata } from './ui/core/radio-group/radio-group.metadata';
 export { Badge, badgeVariants } from './ui/core/badge/badge';
-export { BadgeMetadata } from './ui/core/badge/badge.metadata';
 export { Banner, BannerAction, BannerActions, BannerClose, BannerIcon, BannerStatus, BannerTitle, } from './ui/core/banner/banner';
-export { BannerMetadata } from './ui/core/banner/banner.metadata';
 export { Breadcrumb, BreadcrumbEllipsis, BreadcrumbEllipsisButton, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbPage, BreadcrumbPageButton, BreadcrumbSeparator, } from './ui/core/breadcrumb/breadcrumb';
-export { BreadcrumbMetadata } from './ui/core/breadcrumb/breadcrumb.metadata';
 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 { CollapsibleMetadata } from './ui/core/collapsible/collapsible.metadata';
 export { HoverCard, HoverCardTrigger, HoverCardContent, } from './ui/core/hover-card/hover-card';
-export { HoverCardMetadata } from './ui/core/hover-card/hover-card.metadata';
 export { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, } from './ui/core/select/select';
-export { SelectMetadata } from './ui/core/select/select.metadata';
 export { SegmentedControl, SegmentedControlButton, SegmentedControlContent, SegmentedControlList, segmentedControlButtonVariants, segmentedControlListVariants, } from './ui/core/segmented-control/segmented-control';
 export { Skeleton } from './ui/core/skeleton/skeleton';
-export { SkeletonMetadata } from './ui/core/skeleton/skeleton.metadata';
 export { Toaster, toast } from './ui/core/sonner-toast/sonner-toast';
-export { SonnerToastMetadata } from './ui/core/sonner-toast/sonner-toast.metadata';
 export { Input } from './ui/core/input/input';
-export { InputMetadata } from './ui/core/input/input.metadata';
 export { Kbd, KbdGroup } from './ui/core/kbd/kbd';
-export { KbdMetadata } from './ui/core/kbd/kbd.metadata';
 export { Progress } from './ui/core/progress/progress';
-export { ProgressMetadata } from './ui/core/progress/progress.metadata';
 export { Textarea } from './ui/core/textarea/textarea';
-export { TextareaMetadata } from './ui/core/textarea/textarea.metadata';
 export { Tabs, TabsLabel, TabsList, TabsPanel, TabsTrigger, tabsListVariants, tabsTriggerVariants, } from './ui/core/tabs/tabs';
+export { Toggle, toggleVariants } from './ui/core/toggle/toggle';
 export { InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea, } from './ui/core/input-group/input-group';
-export { InputGroupMetadata } from './ui/core/input-group/input-group.metadata';
 export { Alert, AlertTitle, AlertDescription, AlertActions, AlertButton, AlertClose, } from './ui/core/alert/alert';
-export { AlertMetadata } from './ui/core/alert/alert.metadata';
+export { EmptyState, EmptyStateIcon, EmptyStateTitle, EmptyStateDescription, EmptyStateActions, } from './ui/core/empty-state/empty-state';
 export { Message, MessageContent, MessageActions, MessageAction, MessageResponse, } from './ui/core/message/message';
-export { PromptInputMetadata } from './ui/core/prompt-input/prompt-input.metadata';
 export { usePromptInputController, PromptInputProvider, PromptInput, PromptInputBody, PromptInputTextarea, PromptInputHeader, PromptInputFooter, PromptInputTools, PromptInputButton, PromptInputActionMenu, PromptInputActionMenuTrigger, PromptInputActionMenuContent, PromptInputActionMenuItem, PromptInputSubmit, PromptInputModelSelect, PromptInputModelSelectTrigger, PromptInputModelSelectContent, PromptInputModelSelectItem, PromptInputModelSelectValue, PromptInputHoverCard, PromptInputHoverCardTrigger, PromptInputHoverCardContent, PromptInputTabsList, PromptInputTab, PromptInputTabLabel, PromptInputTabBody, PromptInputTabItem, PromptInputCommand, PromptInputCommandInput, PromptInputCommandList, PromptInputCommandEmpty, PromptInputCommandGroup, PromptInputCommandItem, PromptInputCommandSeparator, } from './ui/core/prompt-input/prompt-input';
 export { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, } from './ui/core/dialog/dialog';
-export { DialogMetadata } from './ui/core/dialog/dialog.metadata';
 export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, } from './ui/core/command/command';
-export { CommandMetadata } from './ui/core/command/command.metadata';
 export { Count, countVariants } from './ui/core/count/count';
-export { InlineCitationMetadata } from './ui/core/inline-citation/inline-citation.metadata';
 export { InlineCitation, InlineCitationGroup, InlineCitationText, InlineCitationCard, InlineCitationCardTrigger, InlineCitationCardBody, InlineCitationSource, InlineCitationQuote, InlineCitationLink, type InlineCitationLinkProps, } from './ui/core/inline-citation/inline-citation';
 export { Reasoning, ReasoningContent, ReasoningHeader, ReasoningItem, } from './ui/core/reasoning/reasoning';
-export { ReasoningMetadata } from './ui/core/reasoning/reasoning.metadata';
 export { ScrollArea, ScrollBar } from './ui/core/scroll-area/scroll-area';
-export { ScrollAreaMetadata } from './ui/core/scroll-area/scroll-area.metadata';
+export { Search } from './ui/core/search/search';
 export { Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverHeader, PopoverHeaderContent, PopoverSlot, PopoverTitle, PopoverTrigger, } from './ui/core/popover/popover';
-export { PopoverMetadata } from './ui/core/popover/popover.metadata';
+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, } from './ui/core/date-time-pickers';
+export type { DatePickerProps, DateRangePickerProps, DateTimeRangePickerProps, ShortcutItem, TimeFormat, } from './ui/core/date-time-pickers';
 export { PortalContainerContext } from '../lib/portal-container-context';
 export type { ComponentMeta, ComponentStatusType } from '../lib/types';