themelia-ui 1.0.0

package/docs/generated/components/base--display.md

@@ -0,0 +1,728 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# `base/display`
+
+Presenting label/key and value facts, a collapsible region, a keyboard hint or a scrollable pane.
+
+## Selection
+
+- **Use when:** Presenting label/key and value facts, a collapsible region, a keyboard hint or a scrollable pane.
+- **Avoid when:** The pair is an editable field, or the row carries identity and actions.
+- **Consider instead:** `base/forms`, `base/item`
+- **Stability:** stable.
+
+## Import
+
+```tsx fragment — import-only example
+import { BooleanIndicator } from "themelia-ui/base/display"
+import "themelia-ui/base/display.css"
+```
+
+## Composition
+
+This family composes `base/badge`, `base/buttons`, `base/structure`, `base/tooltip`, `base/typography`.
+
+Application policy—routing, fetching, persistence, permissions, and translation—stays
+outside the package and arrives through the public props, callbacks, slots, or accessors below.
+
+## Public declarations
+
+### `BooleanIndicator`
+
+Kind: callable.
+
+```text
+({ value, strings, className, ...props }: BooleanIndicatorProps) => React.JSX.Element
+```
+
+### `BooleanIndicatorProps`
+
+Kind: interface.
+
+Extends: `Omit<React.ComponentProps<"span">, "children">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `value` | no | `boolean \| null` |
+| `strings` | no | `Partial<BooleanIndicatorStrings>` |
+
+### `BooleanIndicatorStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `true` | yes | `string` |
+| `false` | yes | `string` |
+
+### `Collapsible`
+
+Kind: callable.
+
+```text
+({ open, defaultOpen, onOpenChange, className, children, ...props }: CollapsibleProps) => React.JSX.Element
+```
+
+### `CollapsibleContent`
+
+Kind: callable.
+
+```text
+({ className, children, ...props }: React.ComponentProps<"div">) => React.JSX.Element
+```
+
+### `CollapsibleProps`
+
+Kind: interface.
+
+Extends: `Omit<React.ComponentProps<"div">, "onToggle">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `open` | no | `boolean` |
+| `defaultOpen` | no | `boolean` |
+| `onOpenChange` | no | `(open: boolean) => void` |
+
+### `CollapsibleTrigger`
+
+Kind: callable.
+
+```text
+({ className, children, onClick, ...props }: React.ComponentProps<"button">) => React.JSX.Element
+```
+
+### `ContentBlock`
+
+Kind: callable.
+
+```text
+({ title, description, icon, titleSuffix, headerEnd, surface, flush, className, children, ...props }: ContentBlockProps) => import("react").JSX.Element
+```
+
+### `ContentBlockProps`
+
+Kind: interface.
+
+Extends: `Omit<ComponentProps<"div">, "title">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | no | `ReactNode` |
+| `description` | no | `ReactNode` |
+| `icon` | no | `ReactNode` |
+| `titleSuffix` | no | `ReactNode` |
+| `headerEnd` | no | `ReactNode` |
+| `surface` | no | `ContentBlockSurface` |
+| `flush` | no | `boolean` |
+| `children` | no | `ReactNode` |
+
+### `ContentBlockSurface`
+
+Kind: type.
+
+```text
+"plain" | "bordered" | "muted" | "card"
+```
+
+### `DateBlock`
+
+Kind: callable.
+
+```text
+({ date, time, dateTime, layout, boxed, showWeekday, showMonth, showYear, weekdayFormat, dayFormat, monthFormat, yearFormat, className, ...props }: DateBlockProps) => import("react").JSX.Element | null
+```
+
+### `DateBlockLayout`
+
+Kind: type.
+
+```text
+"stacked" | "inline"
+```
+
+### `DateBlockProps`
+
+Kind: interface.
+
+Extends: `Omit<ComponentProps<"time">, "children" | "dateTime">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `date` | no | `Date \| string \| number \| null` |
+| `time` | no | `ReactNode` |
+| `dateTime` | no | `string` |
+| `layout` | no | `DateBlockLayout` |
+| `boxed` | no | `boolean` |
+| `showWeekday` | no | `boolean` |
+| `showMonth` | no | `boolean` |
+| `showYear` | no | `boolean` |
+| `weekdayFormat` | no | `string` |
+| `dayFormat` | no | `string` |
+| `monthFormat` | no | `string` |
+| `yearFormat` | no | `string` |
+
+### `defaultBooleanIndicatorStrings`
+
+Kind: const.
+
+```text
+BooleanIndicatorStrings
+```
+
+### `defaultMetadataListStrings`
+
+Kind: const.
+
+```text
+MetadataListStrings
+```
+
+### `IconBadge`
+
+Kind: callable.
+
+```text
+({ icon, children, tone, shape, solid, bordered, className, ...props }: IconBadgeProps) => import("react").JSX.Element
+```
+
+### `IconBadgeProps`
+
+Kind: interface.
+
+Extends: `Omit<ComponentProps<"span">, "children">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `icon` | no | `ComponentType<{ className?: string; }> \| ReactNode` |
+| `children` | no | `ReactNode` |
+| `tone` | no | `IconBadgeTone` |
+| `shape` | no | `IconBadgeShape` |
+| `solid` | no | `boolean` |
+| `bordered` | no | `boolean` |
+
+### `IconBadgeShape`
+
+Kind: type.
+
+```text
+"rounded" | "circle"
+```
+
+### `IconBadgeTone`
+
+Kind: type.
+
+```text
+"neutral" | "primary" | "success" | "warning" | "destructive" | "info"
+```
+
+### `InlineStat`
+
+Kind: callable.
+
+```text
+({ label, value, layout, mono, className, ...props }: InlineStatProps) => import("react").JSX.Element
+```
+
+### `InlineStatLayout`
+
+Kind: type.
+
+```text
+"between" | "inline" | "stacked"
+```
+
+### `InlineStatProps`
+
+Kind: interface.
+
+Extends: `Omit<ComponentProps<"div">, "children">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `label` | yes | `ReactNode` |
+| `value` | no | `ReactNode` |
+| `layout` | no | `InlineStatLayout` |
+| `mono` | no | `boolean` |
+
+### `Kbd`
+
+Kind: callable.
+
+```text
+({ className, ...props }: ComponentProps<"kbd">) => import("react").JSX.Element
+```
+
+### `KbdGroup`
+
+Kind: callable.
+
+```text
+({ className, ...props }: ComponentProps<"span">) => import("react").JSX.Element
+```
+
+### `MetadataBadgeValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & DisplayOverride & { kind: "badge"; value: DisplayValue; badgeTone?: BadgeProps["tone"]; badgeVariant?: BadgeProps["variant"]; }
+```
+
+### `MetadataColumns`
+
+Kind: type.
+
+```text
+1 | 2 | 3 | 4
+```
+
+### `MetadataContactValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & DisplayOverride & { kind: "email" | "phone" | "url"; value: string; }
+```
+
+### `MetadataDateTimeValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & { kind: "datetime"; value: DateValueInput; pattern?: string; }
+```
+
+### `MetadataDateValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & { kind: "date"; value: DateValueInput; pattern?: string; }
+```
+
+### `MetadataDensity`
+
+Kind: type.
+
+```text
+"default" | "compact"
+```
+
+### `MetadataEmptyValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & { kind: "empty"; }
+```
+
+### `MetadataInlineListItem`
+
+Kind: type.
+
+```text
+Omit<MetadataListItem, "description"> & { description?: never; }
+```
+
+### `MetadataLayout`
+
+Kind: type.
+
+```text
+"grid" | "rows" | "inline"
+```
+
+### `MetadataLinkValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & DisplayOverride & { kind: "link"; href: string; value?: DisplayValue; }
+```
+
+### `MetadataList`
+
+Kind: callable.
+
+```text
+({ items, columns, density, emptyLabel, title, titleSeparator, className, layout, separator, itemSeparator, strings, }: MetadataListProps) => import("react").JSX.Element | null
+```
+
+### `MetadataListItem`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `id` | no | `string` |
+| `label` | yes | `ReactNode` |
+| `value` | no | `ReactNode \| MetadataValueDescriptor \| null` |
+| `description` | no | `ReactNode \| null` |
+| `tooltip` | no | `ReactNode` |
+| `icon` | no | `ComponentType<{ className?: string; }>` |
+| `emptyLabel` | no | `ReactNode` |
+| `render` | no | `(item: MetadataListItem) => ReactNode` |
+
+### `MetadataListProps`
+
+Kind: type.
+
+```text
+MetadataGridRowsProps | MetadataInlineProps
+```
+
+### `MetadataListStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `formatInfoLabel` | yes | `(label: string) => string` |
+| `infoFallback` | yes | `string` |
+
+### `MetadataMoneyValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & { kind: "money"; value: number | string; currency?: MoneyProps["currency"]; unit?: MoneyProps["unit"]; minorUnitScale?: MoneyProps["minorUnitScale"]; formatMode?: MoneyProps["formatMode"]; locale?: MoneyProps["locale"]; }
+```
+
+### `MetadataMonoValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & DisplayOverride & { kind: "mono"; value: DisplayValue; }
+```
+
+### `MetadataNodeValueDescriptor`
+
+Kind: type.
+
+### `MetadataTextValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & DisplayOverride & { kind?: "text"; value: DisplayValue; }
+```
+
+### `MetadataTimeValueDescriptor`
+
+Kind: type.
+
+```text
+DescriptorBase & ValueFallback & { kind: "time"; value: DateValueInput; pattern?: string; }
+```
+
+### `MetadataValue`
+
+Kind: callable.
+
+```text
+(props: MetadataValueProps) => import("react").JSX.Element
+```
+
+### `MetadataValueDescriptor`
+
+Kind: type.
+
+```text
+MetadataTextValueDescriptor | MetadataMonoValueDescriptor | MetadataContactValueDescriptor | MetadataLinkValueDescriptor | MetadataDateValueDescriptor | MetadataTimeValueDescriptor | MetadataDateTimeValueDescriptor | MetadataMoneyValueDescriptor | MetadataBadgeValueDescriptor | MetadataNodeValueDescriptor | MetadataEmptyValueDescriptor
+```
+
+### `MetadataValueKind`
+
+Kind: type.
+
+```text
+"text" | "mono" | "email" | "phone" | "url" | "link" | "date" | "time" | "datetime" | "money" | "badge" | "node" | "empty"
+```
+
+### `MetadataValueProps`
+
+Kind: type.
+
+```text
+MetadataValueDescriptor
+```
+
+### `PlaceholderPattern`
+
+Kind: callable.
+
+```text
+({ className, ...props }: PlaceholderPatternProps) => import("react").JSX.Element
+```
+
+### `PlaceholderPatternProps`
+
+Kind: type.
+
+```text
+ComponentProps<"div">
+```
+
+### `ScrollArea`
+
+Kind: callable.
+
+```text
+({ className, ...props }: React.ComponentProps<"div">) => React.JSX.Element
+```
+
+### `Separator`
+
+Kind: callable.
+
+```text
+({ className, orientation, variant, thickness, label, style, ...props }: SeparatorProps) => React.JSX.Element
+```
+
+### `SeparatorProps`
+
+Kind: interface.
+
+Extends: `SeparatorPrimitive.Props`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `variant` | no | `SeparatorVariant` |
+| `thickness` | no | `string \| number` |
+| `label` | no | `React.ReactNode` |
+
+### `SeparatorVariant`
+
+Kind: type.
+
+```text
+"solid" | "dashed" | "dotted"
+```
+
+### `VisuallyHidden`
+
+Kind: callable.
+
+```text
+({ className, render, ...props }: VisuallyHiddenProps) => React.JSX.Element
+```
+
+### `VisuallyHiddenProps`
+
+Kind: interface.
+
+Extends: `React.ComponentProps<"span">`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `render` | no | `React.ReactElement<{ className?: string; }>` |
+
+## Preview recipes
+
+Preview route: Collapsible — `/collapsible`
+
+### Collapsible
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Collapsible>
+  <CollapsibleTrigger>Advanced options</CollapsibleTrigger>
+  <CollapsibleContent>…</CollapsibleContent>
+</Collapsible>
+```
+
+### Four surfaces
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ContentBlock surface="card" title="Contract" description="…">
+  …
+</ContentBlock>
+```
+
+### flush
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ContentBlock surface="card" flush>
+  <ItemGroup ruled>…</ItemGroup>
+</ContentBlock>
+```
+
+### The header assembles itself
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ContentBlock
+  icon={<TruckIcon />}
+  title="Shipment"
+  titleSuffix={<Badge tone="info">In transit</Badge>}
+  headerEnd={<Button buttonStyle="ghost">Track</Button>}
+/>
+```
+
+### IconBadge
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<IconBadge icon={CreditCardIcon} tone="success" />
+<IconBadge icon={CreditCardIcon} tone="success" shape="circle" solid />
+```
+
+### DateBlock
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<DateBlock date="2026-08-16" />
+```
+
+### PlaceholderPattern
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<PlaceholderPattern style={{ height: "8rem" }} />
+```
+
+### DirectionProvider and Slot
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<DirectionProvider direction="rtl">
+  <Stack>…</Stack>
+</DirectionProvider>
+
+// render is Slot:
+<OverlayTrigger render={<Button>Open</Button>} />
+```
+
+### between
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<InlineStat label="Subtotal" value="€ 1,240.00" mono />
+```
+
+### inline
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<InlineStat layout="inline" label="Version" value="v3.2" mono />
+```
+
+### stacked
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<InlineStat layout="stacked" label="Open invoices" value="14" mono />
+```
+
+### grid
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<MetadataList
+  columns={3}
+  items={[
+    { label: "Reference", value: { kind: "mono", value: "INV-4417" } },
+    { label: "Amount", value: { kind: "money", value: 48200, currency: "USD" } },
+    { label: "Status", value: { kind: "badge", value: "Overdue", badgeTone: "destructive" } },
+  ]}
+/>
+```
+
+### rows
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<MetadataList layout="rows" itemSeparator items={facts} />
+```
+
+### inline
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<MetadataList layout="inline" itemSeparator items={summary} />
+```
+
+### density
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<MetadataList density="compact" columns={2} items={facts} />
+```
+
+### Menubar
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New <MenubarShortcut>⌘N</MenubarShortcut></MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+### HoverCard
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<HoverCard>
+  <HoverCardTrigger render={<TextLink />}>@jane</HoverCardTrigger>
+  <HoverCardContent>…</HoverCardContent>
+</HoverCard>
+```
+
+### Resizable
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ResizablePanelGroup orientation="horizontal" autoSaveId="inspector">
+  <ResizablePanel defaultSize={65}>…</ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={35}>…</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+### OtpInput
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<OtpInput length={6} groupSize={3} value={code} onValueChange={setCode} />
+```
+
+### AspectRatio
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<AspectRatio ratio={16 / 9}>
+  <img src={cover} alt="" />
+</AspectRatio>
+```
+
+### Kbd
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Kbd>⌘K</Kbd>
+```
+
+### ScrollArea
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ScrollArea style={{ maxHeight: "8rem" }}>…</ScrollArea>
+```
+
+### BooleanIndicator
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<BooleanIndicator value strings={{ true: "Active", false: "Paused" }} />
+```
+
+### VisuallyHidden
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Text>
+  Saved
+  <VisuallyHidden> at 09:32 by Jane McDonald</VisuallyHidden>
+</Text>
+```
+
+### Separator
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Separator />
+<Separator label="OR" />
+<Separator orientation="vertical" />
+```
+
+### Variants and thickness
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<Separator variant="dashed" />
+<Separator variant="dotted" />
+<Separator thickness={2} />
+```