@cognite/aura 0.3.0 → 0.3.2

package/README.md

@@ -2,6 +2,109 @@
 
 Aura exports Cognite's UI components, styles, utilities, and ESLint guidance for preserving the design system in downstream apps.
 
+## Using Aura in Fusion
+
+[`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.
+
+### Package imports
+
+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
+pnpm nx serve aura          # Storybook
+pnpm nx run aura:design-md-lint
+```
+
 ## Optional peer dependencies
 
 Some Aura entry points require optional peer dependencies that consumers must install themselves:
@@ -35,30 +138,49 @@ Some Aura entry points require optional peer dependencies that consumers must in
   </ChartContainer>
   ```
 
-## DESIGN.md (Google design.md linter)
+## Versioning
 
-[`DESIGN.md`](./DESIGN.md) is linted with [`@google/design.md`](https://www.npmjs.com/package/@google/design.md) (listed in this package’s `devDependencies`). After `pnpm install` in the Fusion workspace, run the CLI’s `lint` subcommand—no `dlx` needed.
+### Before releasing
 
-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).
+Ensure all documentation is up to date before bumping the version:
 
-From `fusion/libs/aura`:
+- [`CHANGELOG.md`](./CHANGELOG.md) — summarise all consumer-facing changes since the last release.
+- [`DESIGN.md`](./DESIGN.md) — reflect any new or updated components, tokens, or visual behaviour.
+- Any agent skills in `.cursor/skills/` or `.claude/skills/` that reference Aura components or APIs.
 
-```sh
-pnpm exec design.md lint ./DESIGN.md
-```
+### Release process
+
+1. Create a release branch off the latest `master`.
+2. Bump the version in `libs/aura/package.json` and prepend a new section to `CHANGELOG.md`.
+3. Commit with `release(aura): <version>` and open a PR into `master`.
+4. Once merged, CI publishes the package to the registry automatically.
+
+### After publishing
 
-From the Fusion workspace root:
+Consumers can adopt the new version by updating their `package.json` manually, or by letting Renovate/Dependabot open a bump PR in their repo automatically. [The Custom Apps repo](https://github.com/cognitedata/dune) has this configured and is the primary critical consumer. 
+
+## 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
-pnpm --filter @cognite/aura exec 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/components/index.d.ts

@@ -31,6 +31,7 @@ export { Kbd, KbdGroup } from './ui/core/kbd/kbd';
 export { Progress } from './ui/core/progress/progress';
 export { Textarea } from './ui/core/textarea/textarea';
 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 { Alert, AlertTitle, AlertDescription, AlertActions, AlertButton, AlertClose, } from './ui/core/alert/alert';
 export { EmptyState, EmptyStateIcon, EmptyStateTitle, EmptyStateDescription, EmptyStateActions, } from './ui/core/empty-state/empty-state';
@@ -46,7 +47,7 @@ export { Search } from './ui/core/search/search';
 export { Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverHeader, PopoverHeaderContent, PopoverSlot, PopoverTitle, PopoverTrigger, } from './ui/core/popover/popover';
 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 { DateRangePicker, DateTimeRangePicker, } from './ui/core/date-time-pickers';
-export type { DateRangePickerProps, DateTimeRangePickerProps, ShortcutItem, TimeFormat, } from './ui/core/date-time-pickers';
+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 { PortalContainerContext } from '../lib/portal-container-context';
 export type { ComponentMeta, ComponentStatusType } from '../lib/types';