@squadbase/vantage 0.6.2-dev1.b332e5a → 0.6.2-dev1.bcb51d1

package/docs/en/ui/field.md

@@ -0,0 +1,42 @@
+# Field
+
+> A form layout part that binds a label, description and error to an input.
+
+Lays out one input's label, helper text and error message with fixed spacing and direction. Put the
+input itself, such as [`Input`](ui/input) or [`Switch`](ui/switch),
+inside it.
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldContent,
+  FieldTitle,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+  FieldSeparator,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Field` | The frame for one input. `orientation` picks the layout |
+| `FieldLabel` | The label (uses `Label`). Tie it to the input with `htmlFor` |
+| `FieldDescription` | Helper text |
+| `FieldError` | The error. Pass `children` or `errors` (`{ message }[]`). Renders nothing when empty |
+| `FieldContent` | A column that groups the label and description in a horizontal layout |
+| `FieldTitle` | A heading that is not a `<label>` |
+| `FieldGroup` | Stacks several `Field`s vertically |
+| `FieldSet` / `FieldLegend` | `<fieldset>` / `<legend>`. `FieldLegend` takes `variant` (`"legend"` by default, or `"label"` for smaller text) |
+| `FieldSeparator` | A divider line. You can put text in the middle |
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | `"vertical"` | Passed to `Field`. `responsive` goes horizontal only when the container is wide. |
+| `data-invalid` | `boolean` |  | Set on `Field` to turn the label and description the error colour. Also put `aria-invalid` on the input. |
+| `errors` | `Array<{ message?: string } \| undefined>` |  | Passed to `FieldError`. Several are shown as a bulleted list, and duplicates are merged into one. |

package/docs/en/ui/hover-card.md

@@ -0,0 +1,21 @@
+# Hover Card
+
+> A preview card that appears when you hover a link.
+
+Shows supplementary content in a card when the pointer rests on a link or term (or when it receives
+keyboard focus). Meant for **read-only** information such as a metric definition or a user profile.
+For anything interactive use [`Popover`](ui/popover); for a short phrase use
+[`Tooltip`](ui/tooltip). Built on Base UI's `PreviewCard`.
+
+```tsx
+import { HoverCard, HoverCardTrigger, HoverCardContent } from "@squadbase/vantage/ui";
+```
+
+`HoverCardTrigger` renders an `<a>` by default. Pass `render` to use another element.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Passed to `HoverCardContent`. Which side of the trigger it appears on. |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | Passed to `HoverCardContent`. |
+| `sideOffset` | `number` | `4` | Distance in px between `HoverCardContent` and the trigger. |
+| `delay` | `number` | `600` | Passed to `HoverCardTrigger`. Milliseconds before it opens. |

package/docs/en/ui/kbd.md

@@ -0,0 +1,17 @@
+# Kbd
+
+> A keyboard key.
+
+A small part for showing shortcut keys. Line several keys up with `KbdGroup`.
+
+```tsx
+import { Kbd, KbdGroup } from "@squadbase/vantage/ui";
+```
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `Kbd` | `ComponentProps<"kbd">` | A single key. |
+| `KbdGroup` | `ComponentProps<"div">` | Lays the keys out side by side. |
+
+Placed inside a button or a [`Tooltip`](ui/tooltip), it blends in with the
+surrounding text colour.

package/docs/en/ui/loading.md

@@ -12,7 +12,7 @@ import { Loading } from "@squadbase/vantage/ui";
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `label` | `string` | `"Loading…"` | Text shown next to the spinner. |
+| `label` | `string` | `"読み込んでいます…"` | Text shown next to the spinner. |
 | `className` | `string` |  | Classes to add. By default it centres within a 30vh minimum height. |
 
 To hold the layout while waiting use [`Skeleton`](ui/skeleton); in tight spots such

package/docs/en/ui/pagination.md

@@ -0,0 +1,36 @@
+# Pagination
+
+> A row of page links.
+
+Page navigation for a list split into pages. It is purely visual and holds neither the current page
+nor the total — the caller owns that state (URL search params or `useState`).
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from "@squadbase/vantage/ui";
+```
+
+## Parts
+
+| Part | Role |
+| --- | --- |
+| `Pagination` | The `<nav>`, with `aria-label="pagination"` |
+| `PaginationContent` / `PaginationItem` | The `<ul>` / `<li>` |
+| `PaginationLink` | One page's `<a>`. `isActive` marks the current page |
+| `PaginationPrevious` / `PaginationNext` | The `<a>` to the previous / next page. `text` changes the wording |
+| `PaginationEllipsis` | The ellipsis |
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isActive` | `boolean` |  | Passed to `PaginationLink`. Sets `aria-current="page"` and an outlined look. |
+| `text` | `string` | `"Previous" / "Next"` | Label of `PaginationPrevious` / `PaginationNext` (hidden below 640px). |
+
+The links are plain `<a>` elements, so passing `href` navigates as usual. To change only in-page
+state, call `preventDefault()` in `onClick`.

package/docs/en/ui/radio-group.md

@@ -0,0 +1,21 @@
+# Radio Group
+
+> Radio buttons for choosing one of a few options.
+
+An input that keeps every option visible and lets the user pick one. With many options consider
+[`Select`](ui/select); to switch with side-by-side buttons consider
+[`SegmentedControl`](parts/segmented-control).
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@squadbase/vantage/ui";
+```
+
+`RadioGroupItem` has no label of its own. Give it an `id` and tie it to a
+[`Label`](ui/label) through `htmlFor`.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `unknown` | The selected value of `RadioGroup` (controlled). |
+| `defaultValue` | `unknown` | The initial value of `RadioGroup` (uncontrolled). |
+| `onValueChange` | `(value: unknown) => void` | Passed to `RadioGroup`. Receives the `value` of the chosen `RadioGroupItem`. |
+| `disabled` | `boolean` | Disables the whole group, or a single item. |

package/docs/en/ui/toast.md

@@ -0,0 +1,44 @@
+# Toast
+
+> A transient notification in the corner of the screen.
+
+A short notice about the result of an action, such as a save succeeding or failing. Built on Base
+UI's `Toast`; it does not depend on `sonner`.
+
+```tsx
+import { Toaster, toast } from "@squadbase/vantage/ui";
+```
+
+## Usage
+
+**Wrap the app root in `Toaster` once**, then call `toast.add()` from anywhere. `Toaster` renders
+its children and adds a stack for notifications at the bottom right (bottom centre on mobile).
+
+```tsx
+<Toaster>
+  <App />
+</Toaster>;
+
+toast.add({ title: "レポートを保存しました", type: "success" });
+```
+
+`toast` is a manager created once per module, with `add` / `close` / `update` / `promise`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` |  | The heading. |
+| `description` | `ReactNode` |  | The body. |
+| `type` | `"success" \| "info" \| "warning" \| "error" \| "loading" \| string` |  | Picks the icon shown on the left. No icon if omitted. |
+| `timeout` | `number` | `5000` | Milliseconds until it closes itself. `0` keeps it open. |
+| `actionProps` | `ButtonProps` |  | Shows an action button when given (`children` is the label, `onClick` the handler). |
+
+`toast.add()` returns an ID. Replace the contents with `toast.update(id, {...})` and close it with
+`toast.close(id)`. For async work use `toast.promise(promise, { loading, success, error })`.
+
+> [!NOTE]
+> The call style differs from shadcn/ui's `sonner` version (`toast("…")` / `toast.success("…")`).
+> This has the same API as shadcn/ui's Base UI `toast`. When you need a separate manager outside
+> `Toaster`, create one with `createToastManager()` and pass it as `<Toaster toastManager={manager}>`.
+> You can also recompose the parts (`Toast` / `ToastTitle` / `ToastDescription` / `ToastAction` /
+> `ToastClose` / `ToastViewport` / `ToastPortal` / `ToastProvider`, `useToastManager`) into your own
+> layout.

package/docs/en/ui/toggle-group.md

@@ -14,13 +14,14 @@ import { ToggleGroup, ToggleGroupItem } from "@squadbase/vantage/ui";
 | --- | --- | --- | --- |
 | `value` | `string[]` |  | The selected values — **an array even for single choice**. |
 | `onValueChange` | `(value: string[]) => void` |  | Fired on change, with an array. |
-| `toggleMultiple` | `boolean` |  | Allow more than one selection. |
+| `multiple` | `boolean` | `false` | `true` allows more than one selection. |
 | `variant` | `"default" \| "outline"` | `"default"` |  |
 | `size` | `"default" \| "sm" \| "lg"` | `"default"` |  |
 | `spacing` | `number` | `2` | Gap between items; `0` welds them into one band. |
 | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |  |
 
 > [!WARNING]
-> There is no Radix-style `type="single"` / `type="multiple"`. Single choice means keeping the array's
-> length at one yourself. [`SegmentedControl`](parts/segmented-control) already does
+> There is no Radix-style `type="single"` / `type="multiple"`. Instead there is a boolean `multiple`;
+> by default (`false`) only one item can be pressed at a time. Even then `value` is an array of at
+> most one element. [`SegmentedControl`](parts/segmented-control) already handles
 > that, so prefer it when you want single choice.

package/docs/en/ui-and-theming.md

@@ -36,7 +36,7 @@ In `/ui` (a selection): `Button`, `Card`, the `Table` primitives, `Tabs`, `Input
 `DropdownMenu`, `Sidebar`, `Alert` / `Skeleton` / `Spinner`, `Loading` / `Empty` / `ErrorState`.
 
 In `/components` (a selection): `PageShell`, `AppShell`, `DashboardCard`, `DataTable`, `EChart`,
-`FunnelSteps`, `FilterBar`, `DateRangePicker`, `MetricValue`, `TrendIndicator`.
+`FunnelSteps`, `FilterBar`, `DateRangePicker`, `KpiCard`, `Delta`.
 
 Props and usage for every component live in the [Components](components) tab.