@api7/ui-components 0.4.0 → 0.6.0

package/README.md

@@ -1,22 +1,25 @@
 # @api7/ui-components
 
-API7 React component library built on [Base UI](https://base-ui.com) and Tailwind CSS v4. It ships a precompiled stylesheet, so an application does not need Tailwind CSS to use it.
+API7 React component library built on [Base UI](https://base-ui.com) and Tailwind CSS v4. The components are styled with Tailwind utility classes, and the application's own Tailwind CSS compiles them, so the library and the application share one set of utilities and one theme.
 
 ## Installation
 
+The library needs React 19 and an application that already builds with Tailwind CSS 4.1 or newer. If the application does not use Tailwind yet, follow [the Tailwind CSS installation guide](https://tailwindcss.com/docs/installation) for your build tool first, then come back here.
+
 ```sh
-npm install @api7/ui-components react-day-picker lucide-react
+npm install @api7/ui-components tailwindcss react-day-picker lucide-react
 # or
-pnpm add @api7/ui-components react-day-picker lucide-react
+pnpm add @api7/ui-components tailwindcss react-day-picker lucide-react
 # or
-yarn add @api7/ui-components react-day-picker lucide-react
+yarn add @api7/ui-components tailwindcss react-day-picker lucide-react
 ```
 
-The package expects these peer dependencies in the application:
+`tailwindcss` is already there if the application uses Tailwind. Install the integration of Tailwind for your build tool as well (`@tailwindcss/vite`, `@tailwindcss/postcss` or `@tailwindcss/cli`). The import of the theme works with the Vite plugin, the PostCSS plugin and the CLI, which are the ones tested. Other build tools, such as webpack, are not tested. The package expects these peer dependencies in the application:
 
 | Package                 | Version   | Needed for                                                                                                                                                    |
 | ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `react`, `react-dom`    | `^19`     | Everything                                                                                                                                                    |
+| `tailwindcss`           | `^4.1.0`  | Compiles the classes of the components and registers the theme. See [Quick start](#quick-start)                                                               |
 | `lucide-react`          | `^1`      | Icons used inside components                                                                                                                                  |
 | `react-day-picker`      | `^10.0.1` | Required. `Calendar`, `DatePicker` and `DateRangePicker` import it, and the package declares it as a required peer, so install it even if you do not use them |
 | `@tanstack/react-form`  | `^1.33.0` | `@api7/ui-components/form` (optional)                                                                                                                         |
@@ -26,27 +29,50 @@ Add the optional ones only if you import those entry points.
 
 ## Quick start
 
-1. Import the stylesheet once, in the entry file of the application, before your own styles:
+1. In the main CSS file of the application (for example `src/index.css`), import Tailwind CSS and then the library theme, and make sure the entry file of the application imports that CSS file:
 
-   ```ts
-   import '@api7/ui-components/styles.css';
+   ```css
+   @import 'tailwindcss';
+   @import '@api7/ui-components';
    ```
 
-2. Load a font for `--asu-font-sans`. It is Inter by default. For example, install `@fontsource-variable/inter` (`npm install @fontsource-variable/inter`) and import it in the same entry file:
+   The order matters. The theme extends the Tailwind theme, so it has to come after `tailwindcss`.
+
+   In CSS the package name resolves to the theme through the `style` export condition, and in JavaScript it resolves to the components. Tailwind CSS 4 and the tools that resolve CSS imports the way it does (the Tailwind CLI, `@tailwindcss/postcss` and `@tailwindcss/vite`) apply the condition. A tool that ignores it finds the JavaScript entry instead and fails on `@import`.
+
+   That is all the configuration there is. The theme file points Tailwind at the classes the components use, so you do not add an `@source` line for the library, and it registers the semantic colors (`bg-primary`, `text-muted-foreground`, `border-border` and the rest), the radii and the font as Tailwind theme values. The application keeps its own Tailwind palette, and the same classes work in your own markup. See [Using it with your Tailwind CSS](#using-it-with-your-tailwind-css) for what the theme changes in the application.
+
+2. Load a font for `--font-sans`. It is Inter by default. For example, install `@fontsource-variable/inter` (`npm install @fontsource-variable/inter`) and import it in the same CSS file, or in the entry file of the application:
 
    ```ts
    import '@fontsource-variable/inter';
    ```
 
-   To use another font, override the variable:
+   To use another font, set `--font-sans` in an `@theme` block after the imports:
+
+   ```css
+   @theme {
+     --font-sans: 'Your Font', sans-serif;
+   }
+   ```
+
+   The library does not style the page. Components inherit the text color, the font and the font size from the page, so set them on `body` in the base layer of the application. The components are laid out and tested with this rule, and a different line height changes the height of components that do not set their own:
 
    ```css
-   :root {
-     --asu-font-sans: 'Your Font', sans-serif;
+   @layer base {
+     body {
+       background-color: var(--color-background);
+       color: var(--color-foreground);
+       font-family: var(--font-sans);
+       font-size: var(--text-sm);
+       line-height: var(--text-sm--line-height);
+     }
    }
    ```
 
-3. Use the components. Render `Toaster` once if you use `toast`, and wrap the application in `ConfigProvider` if you need a locale other than `en-US`:
+3. Put `isolate` on the root element of the application (`<div id="root" class="isolate">`). Popups, dialogs and drawers are rendered into `<body>`, outside your root, and they have `z-index: 50` (the toast has `1010`). An element of the application with a higher `z-index`, or a root with a `z-index` of its own, is painted over a popup that overlaps it. `isolate` makes the `z-index` values of the application local to the root, so every popup stays above it whatever values the application uses.
+
+4. Use the components. No provider is required. Render `Toaster` once if you use `toast`, and wrap the application in `ConfigProvider` if you need a locale other than `en-US`:
 
    ```tsx
    import { Button, ConfigProvider, Toaster, toast } from '@api7/ui-components';
@@ -61,17 +87,16 @@ Add the optional ones only if you import those entry points.
    }
    ```
 
-`ConfigProvider` accepts `locale` (`en-US` or `zh-CN`) and `messages`, an object that overrides the built-in texts, such as the loading label of a button, the close buttons, the empty state of the data table and the pagination labels. Define `messages` at module scope or memoize it.
+`ConfigProvider` accepts `locale` (`en-US` or `zh-CN`) and `messages`, an object that overrides the built-in texts, such as the loading label of a button or a spinner, the close buttons, the empty state of the data table and the pagination labels. Define `messages` at module scope or memoize it.
 
 ## Entry points
 
-| Import                           | Contents                                                                                                      |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `@api7/ui-components`            | Components, `toast` and `Toaster`, `ConfigProvider`, `useLocale` and `useMessages`                            |
-| `@api7/ui-components/form`       | Form components built on TanStack Form                                                                        |
-| `@api7/ui-components/data-table` | The data table built on TanStack Table                                                                        |
-| `@api7/ui-components/tokens`     | Design token data (`palette`, `themes`, `FAMILIES`, `STEPS` and the contrast helpers) for documentation pages |
-| `@api7/ui-components/styles.css` | The precompiled stylesheet                                                                                    |
+| Import                           | Contents                                                                                                                                         |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@api7/ui-components`            | Components, `toast` and `Toaster`, `ConfigProvider`, `useLocale` and `useMessages`, and in CSS the theme for the Tailwind CSS of the application |
+| `@api7/ui-components/form`       | Form fields built on TanStack Form. Their form row, `LabeledField`, is in the main entry and works with any form library                         |
+| `@api7/ui-components/data-table` | The data table built on TanStack Table                                                                                                           |
+| `@api7/ui-components/tokens`     | Design token data (`palette`, `themes`, `FAMILIES`, `STEPS` and the contrast helpers) for documentation pages                                    |
 
 The package is ESM only. Component modules keep their `"use client"` directive, so the components work in a React Server Components setup such as the Next.js app router.
 
@@ -97,20 +122,64 @@ export function Actions() {
 }
 ```
 
-A link that looks like a button is an ordinary anchor or router link styled with `buttonVariants`. Give it `data-slot="button"` so the library's CSS reset applies to it:
+A link that looks like a button is an ordinary anchor or router link styled with `buttonVariants`. It carries the same classes as a `Button`:
 
 ```tsx
 import { buttonVariants } from '@api7/ui-components';
 
 export function DocsLink() {
   return (
-    <a href="/docs" data-slot="button" className={buttonVariants({ variant: 'outline' })}>
+    <a href="/docs" className={buttonVariants({ variant: 'outline' })}>
       Docs
     </a>
   );
 }
 ```
 
+## Spinners
+
+`Spinner` is an SVG that spins, and it is a status, so a screen reader announces it. It takes a `size`: `xs`, `sm`, `md` (the default) or `lg`. Its colour is the text colour, so set it with a `text-*` class, and any other `className` is merged onto the SVG.
+
+```tsx
+import { Spinner } from '@api7/ui-components';
+
+<div className="flex justify-center py-12">
+  <Spinner />
+</div>;
+```
+
+Things worth knowing before you build on it:
+
+- The announced name is the `spinner.label` message of the `ConfigProvider`, and an `aria-label` on the spinner replaces it, for example to say what is loading.
+- The spinner mounts together with the loading state, and whether a screen reader announces a status that is inserted into the page is up to the screen reader. To make the loading state reliably announced, set `aria-busy` or `aria-live="polite"` on a container that is already on the page and put the spinner inside it.
+- It does not wrap other elements. To spin your own icon, add `animate-spin` to it.
+- It stops spinning when the user prefers reduced motion, and then shows the static icon.
+- It does not position itself. A loading overlay over a table or a card is built where you use it, with the layout that place needs. `Button` has its own `loading` prop, use that for a button.
+
+## Progress bars
+
+`Progress` shows how far a task has come. It takes a `value` between `min` (0) and `max` (100), and a `null` value makes the bar indeterminate, for a task whose length is unknown. It takes a `size`: `xs`, `sm` (the default) or `md`, which are 4, 6 and 8px high. It takes a `variant`: `default`, `success`, `warning` or `destructive`, the colour of the fill. The bar fills the width of its container, so set the width on the container or with `className`.
+
+```tsx
+import { Progress } from '@api7/ui-components';
+
+<div className="flex flex-col gap-1">
+  <div className="flex justify-between text-xs">
+    <span id="cores-label">Cores</span>
+    <span>45 / 100</span>
+  </div>
+  <Progress value={45} aria-labelledby="cores-label" />
+</div>;
+```
+
+Things worth knowing before you build on it:
+
+- There is no default accessible name, because only you know what is progressing. Give the bar an `aria-label`, or an `aria-labelledby` that points at the text next to it, as above.
+- The label and the numbers around a bar are laid out where you use it. There is no label or value part.
+- The variant is a fixed colour. A bar that changes colour as it fills, such as a quota that turns red near its limit, is a `variant` that you compute from the value where you use it.
+- An indeterminate bar slides a segment along the track. When the user prefers reduced motion it shows the whole track at half opacity instead of a static segment, so it is not read as a partial value. The width of a determinate bar is animated too, and that stops as well.
+- The fill uses the text colour of each tone (`primary-text`, `success-foreground`, `warning-foreground` and `destructive-text`), because those stay 3:1 against the track in both themes, and the plain tone colours do not.
+
 ## Forms
 
 `@api7/ui-components/form` wraps TanStack Form. `useAppForm` returns a form whose `AppField` hands you ready made fields: `TextField`, `TextareaField`, `NumberField`, `SelectField`, `ComboboxField`, `DatePickerField`, `DateRangePickerField`, `CheckboxField`, `SwitchField` and `RadioGroupField`:
@@ -144,6 +213,35 @@ export function NameForm({ onSave }: { onSave: (name: string) => void }) {
 
 Validators are the ones of TanStack Form, so a function or a Standard Schema such as a zod schema both work. A string returned by a validator is shown under the field.
 
+### With another form library
+
+The form row that these fields draw is `LabeledField` from the main entry, and it does not depend on TanStack Form. It takes the label, `labelTooltip`, `optional`, `description` and `layout` like the fields above, and the state of the field as props: `name`, `invalid`, `touched`, `dirty` and `errors`, a list of messages shown while `invalid` is true. The control inside it gets its id, `aria-invalid` and `aria-describedby` from the field, so it is wired the same way as in a TanStack form. `group` renders a fieldset with the label as its legend, for a group of controls such as radio buttons.
+
+With react-hook-form, read the state with `useController` and pass it in:
+
+```tsx
+import { Input, LabeledField } from '@api7/ui-components';
+import { useController } from 'react-hook-form';
+
+export function NameField() {
+  const { field, fieldState } = useController({ name: 'name', rules: { required: 'Name is required' } });
+  return (
+    <LabeledField
+      label="Name"
+      name={field.name}
+      invalid={fieldState.invalid}
+      touched={fieldState.isTouched}
+      dirty={fieldState.isDirty}
+      errors={fieldState.error?.message ? [fieldState.error.message] : []}
+    >
+      <Input ref={field.ref} value={field.value} onValueChange={field.onChange} onBlur={field.onBlur} />
+    </LabeledField>
+  );
+}
+```
+
+`invalid` decides when the error shows. The fields of `/form` show it once the field is touched, and react-hook-form sets `fieldState.invalid` after its own validation mode runs, on submit by default.
+
 ## Joining a field and a button
 
 `InputGroup` joins an `Input` with a `Button` or an `InputGroupAddon` into one control. The group draws no border, ring or state of its own. Each part keeps its own border, hover, focus, invalid and disabled styling, and they touch with one divider between them, so the field and the button read as one. Only the outer corners of the group are round. An `Input` and a `Button` that stand alone are not changed.
@@ -175,9 +273,63 @@ export function HostField() {
 
 The parts are the direct children of the group, in any order. An `InputGroupAddon` is a block with the muted background of the legacy console for text, an icon or a button, and a `Button` inside it loses its own surface. The state belongs to the part that has it: a focused field is framed alone, a button keeps the focus it has when it stands alone (a ring for the keyboard, none for a click), and an invalid field (`aria-invalid`, or a `Field` that is invalid) has the invalid border on the field only, as a disabled field has the disabled background on the field only. An outline button has the border colour of an input. A button with a fill (`primary`, `secondary` or `destructive`) keeps its own edge: at rest the border of the field toward it is transparent, so no line crosses the fill. The group is 32px high like an `Input`, and the parts stretch to that height, so they take no height of their own. Put the group inside a `Field` and a `FieldLabel` labels the field in it as it does any `Input`.
 
+## Description lists
+
+`DescriptionList` shows read-only label and value pairs, such as the fields of a detail page. It is composed from `DescriptionListItem`, `DescriptionListLabel` and `DescriptionListValue`, and there is no data array prop. To render a list of records, map over them where you use it, and filter out the ones you do not want to show there too.
+
+```tsx
+import {
+  DescriptionList,
+  DescriptionListItem,
+  DescriptionListLabel,
+  DescriptionListValue,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@api7/ui-components';
+import { Info } from 'lucide-react';
+
+export function GatewayDetails({ gateway }: { gateway: { id: string; name: string; verifyTls: boolean } }) {
+  return (
+    <DescriptionList variant="outline" columns={2}>
+      <DescriptionListItem colSpan={2}>
+        <DescriptionListLabel>ID</DescriptionListLabel>
+        <DescriptionListValue>{gateway.id}</DescriptionListValue>
+      </DescriptionListItem>
+      <DescriptionListItem>
+        <DescriptionListLabel>Name</DescriptionListLabel>
+        <DescriptionListValue>{gateway.name}</DescriptionListValue>
+      </DescriptionListItem>
+      <DescriptionListItem>
+        <DescriptionListLabel>
+          Verify TLS
+          <Tooltip>
+            <TooltipTrigger aria-label="About Verify TLS">
+              <Info />
+            </TooltipTrigger>
+            <TooltipContent>Verify the certificate of the upstream server.</TooltipContent>
+          </Tooltip>
+        </DescriptionListLabel>
+        <DescriptionListValue>{gateway.verifyTls ? 'Enabled' : 'Disabled'}</DescriptionListValue>
+      </DescriptionListItem>
+    </DescriptionList>
+  );
+}
+```
+
+`variant` is `default`, a list without borders, or `outline`, which reproduces the bordered grid of the legacy console detail pages with a tinted label column. `columns` is how many label and value pairs sit on one row and defaults to 1. An item takes a `colSpan` to span several of them. A fractional `columns` or `colSpan` is rounded down, one that is below 1 or not a number counts as 1, and a `colSpan` larger than `columns` is reduced to `columns`.
+
+Things worth knowing before you build on it:
+
+- The markup is a `dl`, and every item is a `div` that holds one `dt` and one `dd`. The label and the value are adjacent siblings, so a test can take the value of a label with its next sibling. There is no row element, because the browser lays the items out with CSS grid, so select the items, not rows.
+- A row that is not filled, for example the third item with `columns={2}`, leaves the rest of the row empty. The last item does not stretch.
+- The label column is 160px wide, as in the legacy console. Set `--description-list-label-width` in `style` or `className` on the list to change it.
+- A value can hold any content. It grows with its content and long text wraps, so do not give a value a fixed height.
+- A tooltip in a label is a `Tooltip` you place there, and its trigger needs an accessible name, as it does anywhere else.
+
 ## Theming
 
-Theme colors, radii and the font are CSS variables with the `--asu-` prefix, for example `--asu-primary`. The light values are defined on `:root, [data-theme=light]` and the dark values on `[data-theme=dark]`. To change the palette, override the variables on those selectors in a stylesheet that comes after the library stylesheet, because the selectors have the same specificity and the later rule wins.
+The library theme is the default theme of the application. The colors, the radii and the font are Tailwind theme variables, such as `--color-primary` and `--font-sans`, and the application overrides them in its own CSS after the import, as [Using it with your Tailwind CSS](#using-it-with-your-tailwind-css) explains. The light values are the values of the page, `[data-theme=light]` repeats them for a region, and `[data-theme=dark]` holds the dark values. The values themselves are in `src/tokens/semantic.ts`.
 
 ### Dark mode
 
@@ -187,20 +339,59 @@ The library only reads the attribute. It never follows `prefers-color-scheme`, n
 
 `color-scheme` follows the theme as well, so scrollbars and native form controls match.
 
+The library defines the Tailwind `dark` variant as "inside a `data-theme=dark` element", so `dark:bg-muted` in your own markup follows the same attribute. If the application declares its own `@custom-variant dark` after the import, for a `.dark` class or the media query, that declaration replaces the library one, and the `dark:` classes of the components follow it as well. The color variables still switch only with `data-theme`, so such an application gets the light tokens together with the `dark:` adjustments of the components, a mixed look. Set `data-theme` as well, or do not redefine the variant.
+
 #### A region with another theme
 
-`data-theme="light"` or `data-theme="dark"` on any element sets the color variables and the `color-scheme` of everything inside it, and the nearest ancestor wins, so a dark page can hold a light region and the other way round. This works for the color variables and for the `dark:` styles of components alike. The one case plain CSS cannot express is a dark element inside a light element inside a dark element: the innermost dark element is read as light in the `dark:` styles, though its variables are right.
+`data-theme="light"` or `data-theme="dark"` on any element sets the color variables and the `color-scheme` of everything inside it, and the nearest ancestor wins, so a dark page can hold a light region and the other way round. This works for the color variables and for the `dark:` styles alike. The one case plain CSS cannot express is a dark element inside a light element inside a dark element: the innermost dark element is read as light in the `dark:` styles, though its variables are right.
 
 The attribute does not paint a background or a text color, so a region that should look like a page of its own needs `bg-background text-foreground` (or your own rules) on it. A popup is rendered into `<body>`, so it follows `<html>`, not the region that opened it. To theme a popup, put the attribute on the popup element itself (`<PopoverContent data-theme="light">`, which works for the content of Popover, Menu, Select, Combobox, Tooltip, Dialog and Drawer, because each passes its props to the popup element), or on an element inside the popup's content, which then applies to what it wraps.
 
 #### Writing dark styles in a component
 
-A component styles itself with semantic tokens, and each token has a light and a dark value, so most components need nothing for dark mode. When a dark theme needs a different treatment than a token swap, a component may add an `asu:dark:` class, and only together with semantic tokens (`asu:dark:bg-input/30`). A raw palette step behind `asu:dark:` is allowed only in `badge.tsx`, which is the one component that uses palette steps, and each Badge color has its steps for both themes in `BADGE_STEPS` in `src/tokens/contrast.ts`. A brand color has two tokens because a fill and a text color need different lightness in dark: `primary` and `destructive` are fills (with `primary-foreground` on top), while `primary-text` and `destructive-text` are for text and icons on a surface, such as the Button link variant, a selected Tab, error text or the destructive menu item. They equal the fill in light. Prefer a token to `asu:dark:` wherever the token can carry the difference. `src/theme-classes.test.ts` enforces these rules. The values of the dark tokens are in `src/tokens/semantic.ts`, and every text and surface pair of both themes is tested for WCAG AA in `src/tokens/contrast.test.ts`.
+A component styles itself with semantic tokens, and each token has a light and a dark value, so most components need nothing for dark mode. When a dark theme needs a different treatment than a token swap, a component may add a `dark:` class together with a semantic token (`dark:bg-input/30`). Raw palette steps (`bg-blue-100`) are not used in a component at all, because the application's palette is the application's own. Badge is the one component with a color per palette family, and it reads the private variables `--badge-<color>-bg` and `--badge-<color>-fg`, which the theme sets for each theme from `BADGE_STEPS` in `src/tokens/contrast.ts`. A brand color has two tokens because a fill and a text color need different lightness in dark: `primary` and `destructive` are fills (with `primary-foreground` on top), while `primary-text` and `destructive-text` are for text and icons on a surface, such as the Button link variant, a selected Tab, error text or the destructive menu item. They equal the fill in light, so a page that colors text with `text-primary` passes in light and fails contrast in dark. Prefer a token to `dark:` wherever the token can carry the difference. `src/theme-classes.test.ts` enforces these rules. The values of the dark tokens are in `src/tokens/semantic.ts`, and every text and surface pair of both themes is tested for WCAG AA in `src/tokens/contrast.test.ts`.
+
+### Using it with your Tailwind CSS
+
+The components are ordinary Tailwind utilities, so there is one stylesheet and one cascade. The classes of the components are generated into the `utilities` layer of the application, next to its own utilities, and a `className` you pass to a component replaces the default classes that set the same property. Passing `p-6` to a component that has `px-3` leaves only `p-6`.
+
+What the theme changes in the application:
+
+- It adds the semantic colors to the Tailwind theme: `background`, `foreground`, `card`, `popover`, `primary`, `primary-text`, `muted`, `accent`, `destructive`, `success`, `warning`, `info`, `border`, `input`, `ring` and the others listed in `src/tokens/semantic.ts`. The names are common, so an application that already defines `--color-primary` or `--color-muted` gets the value of whichever declaration comes last.
+- It sets `rounded-sm` to 2px and `rounded-md` to 4px, for the application's own markup as well. Other radii and the whole color palette stay as Tailwind defines them.
+- It sets `--font-sans`. Tailwind's theme points `--default-font-family` at it, so Inter becomes the default font of the whole application, not only of the `font-sans` utility.
+- It defines the `dark` variant, as described in [Dark mode](#dark-mode).
+
+To change a color, redeclare the variable after the import, on the same selectors the library uses, so that both themes and the nested regions keep working:
 
-`className` on a component is passed to its element for your own classes. The library's component rules are not placed in a cascade layer, so styles of yours that are in a layer, such as the utilities of Tailwind CSS, cannot override what a component already sets. Your own rules that are not in a layer compete by specificity and source order as usual, so import the library stylesheet first, as the quick start says, and use a selector that is specific enough.
+```css
+@import 'tailwindcss';
+@import '@api7/ui-components';
 
-### Using it next to Tailwind CSS
+:root,
+[data-theme='light'] {
+  --color-primary: #0b5cff;
+}
+
+[data-theme='dark'] {
+  --color-primary: #6ea0ff;
+}
+```
 
-Every utility class in the library carries the `asu:` prefix and every variable the `--asu-` prefix, so an application that uses Tailwind itself can load both without clashes.
+An `@theme` block with the same variable changes only the value of a page root that has no `data-theme` attribute. A `data-theme` region, including `<html data-theme="…">`, keeps the library value, because the library rules are not in a layer and Tailwind emits `@theme` values in the theme layer. Use `@theme` only for values that do not change with the theme, such as `--font-sans`.
 
-The CSS reset applies only inside library components (`[data-slot]` elements and their descendants), so the rest of the page keeps its own styles.
+## Popover arrows
+
+`PopoverContent` has no arrow by default. Add `PopoverArrow` inside it for a pointer that follows the trigger when viewport collision handling shifts or flips the popup. The arrow uses the popover background token and accepts the Base UI arrow props, including `className` and `style` for appearance overrides.
+
+```tsx
+import { Popover, PopoverArrow, PopoverContent, PopoverTrigger } from '@api7/ui-components';
+
+<Popover>
+  <PopoverTrigger>View ID</PopoverTrigger>
+  <PopoverContent align="center" sideOffset={12}>
+    <PopoverArrow />
+    ID: service-production
+  </PopoverContent>
+</Popover>;
+```

package/dist/animations.css

@@ -0,0 +1,12 @@
+@theme {
+  --animate-progress-indeterminate: progress-indeterminate 1.4s ease-in-out infinite;
+
+  @keyframes progress-indeterminate {
+    from {
+      translate: -100%;
+    }
+    to {
+      translate: 300%;
+    }
+  }
+}

package/dist/components/alert/alert.d.ts

@@ -1,6 +1,5 @@
 import { ComponentProps, ReactNode } from "react";
 import { VariantProps } from "class-variance-authority";
-//#region src/components/alert/alert.d.ts
 declare const alertVariants: (props?: ({
   variant?: "destructive" | "success" | "warning" | "info" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
@@ -12,5 +11,4 @@ export type AlertDescriptionProps = ComponentProps<'div'>;
 declare function Alert({ variant, icon, className, children, ...props }: AlertProps): import("react").JSX.Element;
 declare function AlertTitle({ className, ...props }: AlertTitleProps): import("react").JSX.Element;
 declare function AlertDescription({ className, ...props }: AlertDescriptionProps): import("react").JSX.Element;
-//#endregion
 export { Alert, AlertDescription, AlertTitle, alertVariants };

package/dist/components/alert/alert.js

@@ -2,13 +2,13 @@ import { cn } from "../../lib/cn.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cva } from "class-variance-authority";
 import { CircleAlert, CircleCheck, Info, TriangleAlert } from "lucide-react";
-//#region src/components/alert/alert.tsx
-const alertVariants = cva("asu:relative asu:flex asu:w-full asu:gap-2 asu:rounded-sm asu:px-3 asu:py-2 asu:text-sm asu:text-foreground asu:[&>svg]:mt-0.5 asu:[&>svg]:size-4 asu:[&>svg]:shrink-0", {
+// src/components/alert/alert.tsx
+const alertVariants = cva("relative flex w-full gap-2 rounded-sm px-3 py-2 text-sm text-foreground [&>svg]:mt-0.5 [&>svg]:size-4 [&>svg]:shrink-0", {
 	variants: { variant: {
-		info: "asu:bg-info-subtle asu:[&>svg]:text-info",
-		success: "asu:bg-success-subtle asu:[&>svg]:text-success",
-		warning: "asu:bg-warning-subtle asu:[&>svg]:text-warning",
-		destructive: "asu:bg-destructive-subtle asu:[&>svg]:text-destructive-text"
+		info: "bg-info-subtle [&>svg]:text-info",
+		success: "bg-success-subtle [&>svg]:text-success",
+		warning: "bg-warning-subtle [&>svg]:text-warning",
+		destructive: "bg-destructive-subtle [&>svg]:text-destructive-text"
 	} },
 	defaultVariants: { variant: "info" }
 });
@@ -27,14 +27,14 @@ function Alert({ variant, icon, className, children, ...props }) {
 		...props,
 		"data-slot": "alert",
 		children: [icon === void 0 ? /* @__PURE__ */ jsx(Icon, { "aria-hidden": "true" }) : icon || null, /* @__PURE__ */ jsx("div", {
-			className: "asu:flex asu:min-w-0 asu:flex-col asu:gap-0.5",
+			className: "flex min-w-0 flex-col gap-0.5",
 			children
 		})]
 	});
 }
 function AlertTitle({ className, ...props }) {
 	return /* @__PURE__ */ jsx("div", {
-		className: cn("asu:font-medium", className),
+		className: cn("font-medium", className),
 		...props,
 		"data-slot": "alert-title"
 	});
@@ -46,5 +46,4 @@ function AlertDescription({ className, ...props }) {
 		"data-slot": "alert-description"
 	});
 }
-//#endregion
 export { Alert, AlertDescription, AlertTitle, alertVariants };

package/dist/components/avatar/avatar.d.ts

@@ -1,21 +1,20 @@
 import { ComponentProps } from "react";
-//#region src/components/avatar/avatar.d.ts
 declare const SIZES: {
   readonly sm: {
     readonly px: 24;
-    readonly className: "asu:size-6 asu:text-[10px]";
+    readonly className: "size-6 text-[10px]";
   };
   readonly md: {
     readonly px: 28;
-    readonly className: "asu:size-7 asu:text-xs";
+    readonly className: "size-7 text-xs";
   };
   readonly lg: {
     readonly px: 40;
-    readonly className: "asu:size-10 asu:text-base";
+    readonly className: "size-10 text-base";
   };
   readonly xl: {
     readonly px: 96;
-    readonly className: "asu:size-24 asu:text-4xl";
+    readonly className: "size-24 text-4xl";
   };
 };
 export type AvatarSize = keyof typeof SIZES;
@@ -29,5 +28,4 @@ export type AvatarProps = Omit<ComponentProps<'span'>, 'children'> & {
   alt?: string;
 };
 declare function Avatar({ src, name, size, alt, className, style, ...props }: AvatarProps): import("react").JSX.Element;
-//#endregion
 export { Avatar };

package/dist/components/avatar/avatar.js

@@ -1,23 +1,23 @@
 import { cn } from "../../lib/cn.js";
 import { useState } from "react";
 import { jsx } from "react/jsx-runtime";
-//#region src/components/avatar/avatar.tsx
+// src/components/avatar/avatar.tsx
 const SIZES = {
 	sm: {
 		px: 24,
-		className: "asu:size-6 asu:text-[10px]"
+		className: "size-6 text-[10px]"
 	},
 	md: {
 		px: 28,
-		className: "asu:size-7 asu:text-xs"
+		className: "size-7 text-xs"
 	},
 	lg: {
 		px: 40,
-		className: "asu:size-10 asu:text-base"
+		className: "size-10 text-base"
 	},
 	xl: {
 		px: 96,
-		className: "asu:size-24 asu:text-4xl"
+		className: "size-24 text-4xl"
 	}
 };
 function initialOf(name) {
@@ -36,7 +36,7 @@ function Avatar({ src, name, size = "md", alt = "", className, style, ...props }
 	return /* @__PURE__ */ jsx("span", {
 		"data-slot": "avatar",
 		"data-size": size,
-		className: cn("asu:relative asu:inline-flex asu:shrink-0 asu:items-center asu:justify-center asu:overflow-hidden asu:rounded-full asu:font-medium asu:text-white asu:select-none", sizeClassName, className),
+		className: cn("relative inline-flex shrink-0 items-center justify-center overflow-hidden rounded-full font-medium text-white select-none", sizeClassName, className),
 		style: showImage ? style : {
 			backgroundColor: colourOf(name),
 			...style
@@ -51,7 +51,7 @@ function Avatar({ src, name, size = "md", alt = "", className, style, ...props }
 			loading: "lazy",
 			decoding: "async",
 			onError: () => setFailedSrc(src ?? null),
-			className: "asu:size-full asu:object-cover"
+			className: "size-full object-cover"
 		}) : /* @__PURE__ */ jsx("span", {
 			"data-slot": "avatar-initial",
 			"aria-hidden": "true",
@@ -59,5 +59,4 @@ function Avatar({ src, name, size = "md", alt = "", className, style, ...props }
 		})
 	});
 }
-//#endregion
 export { Avatar };

package/dist/components/badge/badge.d.ts

@@ -1,6 +1,5 @@
 import { ComponentProps } from "react";
 import { VariantProps } from "class-variance-authority";
-//#region src/components/badge/badge.d.ts
 declare const badgeVariants: (props?: ({
   color?: "gray" | "slate" | "blue" | "green" | "red" | "yellow" | "orange" | "cyan" | "indigo" | "purple" | "pink" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
@@ -10,5 +9,4 @@ export type BadgeProps = Omit<ComponentProps<'span'>, 'color'> & {
   dot?: boolean;
 };
 declare function Badge({ color, dot, className, children, ...props }: BadgeProps): import("react").JSX.Element;
-//#endregion
 export { Badge, badgeVariants };

package/dist/components/badge/badge.js

@@ -1,20 +1,20 @@
 import { cn } from "../../lib/cn.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { cva } from "class-variance-authority";
-//#region src/components/badge/badge.tsx
-const badgeVariants = cva("asu:inline-flex asu:min-h-5 asu:max-w-[500px] asu:items-center asu:gap-1.5 asu:rounded-full asu:px-2 asu:text-xs asu:font-medium", {
+// src/components/badge/badge.tsx
+const badgeVariants = cva("inline-flex min-h-5 max-w-[500px] items-center gap-1.5 rounded-full px-2 text-xs font-medium", {
 	variants: { color: {
-		gray: "asu:bg-gray-100 asu:text-gray-700 asu:dark:bg-gray-700 asu:dark:text-gray-100",
-		slate: "asu:bg-slate-100 asu:text-slate-700 asu:dark:bg-slate-700 asu:dark:text-slate-100",
-		blue: "asu:bg-blue-100 asu:text-blue-700 asu:dark:bg-blue-700 asu:dark:text-blue-100",
-		green: "asu:bg-green-100 asu:text-green-700 asu:dark:bg-green-700 asu:dark:text-green-100",
-		red: "asu:bg-red-100 asu:text-red-700 asu:dark:bg-red-700 asu:dark:text-red-100",
-		yellow: "asu:bg-yellow-100 asu:text-yellow-700 asu:dark:bg-yellow-700 asu:dark:text-yellow-100",
-		orange: "asu:bg-orange-100 asu:text-orange-700 asu:dark:bg-orange-700 asu:dark:text-orange-100",
-		cyan: "asu:bg-cyan-100 asu:text-cyan-700 asu:dark:bg-cyan-700 asu:dark:text-cyan-100",
-		indigo: "asu:bg-indigo-100 asu:text-indigo-700 asu:dark:bg-indigo-700 asu:dark:text-indigo-100",
-		purple: "asu:bg-purple-100 asu:text-purple-700 asu:dark:bg-purple-700 asu:dark:text-purple-100",
-		pink: "asu:bg-pink-100 asu:text-pink-700 asu:dark:bg-pink-700 asu:dark:text-pink-100"
+		gray: "bg-(--badge-gray-bg) text-(color:--badge-gray-fg)",
+		slate: "bg-(--badge-slate-bg) text-(color:--badge-slate-fg)",
+		blue: "bg-(--badge-blue-bg) text-(color:--badge-blue-fg)",
+		green: "bg-(--badge-green-bg) text-(color:--badge-green-fg)",
+		red: "bg-(--badge-red-bg) text-(color:--badge-red-fg)",
+		yellow: "bg-(--badge-yellow-bg) text-(color:--badge-yellow-fg)",
+		orange: "bg-(--badge-orange-bg) text-(color:--badge-orange-fg)",
+		cyan: "bg-(--badge-cyan-bg) text-(color:--badge-cyan-fg)",
+		indigo: "bg-(--badge-indigo-bg) text-(color:--badge-indigo-fg)",
+		purple: "bg-(--badge-purple-bg) text-(color:--badge-purple-fg)",
+		pink: "bg-(--badge-pink-bg) text-(color:--badge-pink-fg)"
 	} },
 	defaultVariants: { color: "gray" }
 });
@@ -26,13 +26,12 @@ function Badge({ color = "gray", dot = false, className, children, ...props }) {
 		"data-slot": "badge",
 		children: [dot && /* @__PURE__ */ jsx("span", {
 			"aria-hidden": "true",
-			className: "asu:size-1.5 asu:shrink-0 asu:rounded-full asu:bg-current",
+			className: "size-1.5 shrink-0 rounded-full bg-current",
 			"data-slot": "badge-dot"
 		}), /* @__PURE__ */ jsx("span", {
-			className: "asu:truncate asu:[&_img]:inline-block asu:[&_svg]:inline-block asu:[&_img]:align-text-bottom asu:[&_svg]:align-text-bottom asu:[&>img:first-child]:me-1.5 asu:[&>svg:first-child]:me-1.5",
+			className: "truncate [&_img]:inline-block [&_svg]:inline-block [&_img]:align-text-bottom [&_svg]:align-text-bottom [&>img:first-child]:me-1.5 [&>svg:first-child]:me-1.5",
 			children
 		})]
 	});
 }
-//#endregion
 export { Badge, badgeVariants };

package/dist/components/button/button.d.ts

@@ -1,6 +1,5 @@
 import { VariantProps } from "class-variance-authority";
 import { Button } from "@base-ui/react/button";
-//#region src/components/button/button.d.ts
 declare const buttonVariants: (props?: ({
   variant?: "primary" | "secondary" | "destructive" | "link" | "outline" | "ghost" | null | undefined;
   size?: "sm" | "md" | "lg" | "icon" | null | undefined;
@@ -9,8 +8,7 @@ declare const buttonVariants: (props?: ({
  * Base UI's Button enforces button semantics (`role="button"`, keyboard
  * interaction, disabled state) on whatever `render` points at, so links must
  * not be rendered through it. Style the anchor or router link element
- * directly with `buttonVariants()` instead, and give it `data-slot="button"` so the
- * library's scoped CSS reset applies to it.
+ * directly with `buttonVariants()` instead.
  */
 export interface ButtonProps extends Omit<Button.Props, 'className'>, VariantProps<typeof buttonVariants> {
   className?: string;
@@ -18,5 +16,4 @@ export interface ButtonProps extends Omit<Button.Props, 'className'>, VariantPro
   loadingLabel?: string;
 }
 declare function Button$1({ className, variant, size, loading, loadingLabel, disabled, focusableWhenDisabled, children, ...props }: ButtonProps): import("react").JSX.Element;
-//#endregion
 export { Button$1 as Button, buttonVariants };