@gradeui/ui 3.1.0 → 3.2.0

package/components/ui/combobox.md

@@ -0,0 +1,46 @@
+---
+name: Combobox
+import: "@gradeui/ui"
+props:
+  - options: { value, label, icon?, keywords?, disabled? }[] — the selectable pool
+  - value?: string | null — controlled selection (wire onValueChange)
+  - defaultValue?: string | null — uncontrolled initial selection
+  - onValueChange?: (next: string | null) => void — fired with the next value, or null when cleared
+  - placeholder?: string — trigger text when nothing is selected
+  - searchPlaceholder?: string — search-input placeholder
+  - emptyMessage?: string — shown when search returns no rows
+  - searchable?: boolean — show the search input (default true)
+  - clearable?: boolean — add a Clear row so the value can return to unset
+  - triggerVariant?: "default" | "inline" — default = form-control surface (like Select); inline = chrome-free token trigger
+  - renderValue?: (option) => ReactNode — render the selected value yourself (e.g. a Badge); falls back to icon + label
+  - hideChevron?: boolean — drop the trailing chevron (inline token look)
+  - disabled?: boolean — lock to a read-only display of the current value
+  - align?: "start" | "center" | "end" — popover alignment
+when_to_use: Single-pick searchable picker — the single-select sibling of MultiSelect and the Linear "selectable badge" pattern (status / priority / assignee). Use triggerVariant="inline" with renderValue returning a Badge to make a value read as a clickable token that opens a command menu. For multiple selection use MultiSelect; for a small fixed list with no search use Select; for free-form command palettes use Command directly. Pass disabled (driven by a permission check) to show the value without letting the user edit it.
+composes_with: [Popover, Command, Badge, Avatar, PropertyList, Table, Field]
+aliases: [combobox, single select, searchable select, picker, status picker, priority picker, assignee picker, command select, autocomplete, dropdown select, selectable badge, inline select, token select, linear combobox]
+---
+
+```jsx
+<Combobox
+  options={[
+    { value: "low", label: "Low" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High" },
+  ]}
+  defaultValue="low"
+  placeholder="Set priority"
+/>
+```
+
+```jsx
+// Linear-style: the value IS the trigger.
+<Combobox
+  triggerVariant="inline"
+  hideChevron
+  options={priorityOptions}
+  value={priority}
+  onValueChange={setPriority}
+  renderValue={(opt) => <Badge variant="warning-soft">{opt.label}</Badge>}
+/>
+```

package/components/ui/data-view.md

@@ -0,0 +1,59 @@
+---
+name: DataView
+import: "@gradeui/ui"
+props:
+  - data: T[] — the rows
+  - columns: { key, header, type?, options?, cell?, role?, sortable?, pinned?, width?, align?, hideable?, defaultHidden? }[] — the schema; one list drives table, cards, and grid
+  - getRowId?: (row, i) => string — defaults to row.id
+  - view? / defaultView? / onViewChange?: "table" | "cards" | "grid" — controlled or uncontrolled view
+  - views?: ("table" | "cards" | "grid")[] — allowed views; one entry = single view, no toggle
+  - activeId? / defaultActiveId? / onActiveChange?: string | null — the selected row; click emits it
+  - sorting? / defaultSorting? / onSortingChange? — TanStack SortingState
+  - columnVisibility? / defaultColumnVisibility? / onColumnVisibilityChange? — which fields show
+  - stickyHeader?: boolean — freeze the header row on scroll
+  - toolbar?: boolean — render the built-in columns menu + view toggle above the view
+  - renderCard?: (row, { active }) => ReactNode — override card / grid tiles
+  - emptyMessage?: ReactNode
+when_to_use: One dataset, drawn as a table, a list of cards, or a grid — without re-typing the TanStack boilerplate (sortable headers, flexRender, selection, view switch) on every page. Hand it data + a columns schema; columns declare a `type` (badge/tags/number/currency/percent/date/boolean/url/text) that DataView renders, with a `cell` override for bespoke cells (avatars, relations). The view toggle can live anywhere — `useDataView()` holds the state so a `<DataViewToggle>` or `<DataViewColumns>` in a page header drives a `<DataView>` lower down. Mark a column `pinned="left"` (with a `width`) for a fixed column and `stickyHeader` to freeze the header. For a single record's fields use PropertyList; for the raw table primitive use Table.
+composes_with: [Table, Card, Badge, Avatar, ToggleGroup, DropdownMenu, PropertyList, Combobox]
+aliases: [data view, data table, datatable, data grid, dataview, table view, card view, grid view, list view, gallery, records list, master list, tanstack table, sortable table, column visibility, pinned column, frozen column, sticky header, view switcher]
+---
+
+```jsx
+const dv = useDataView({ defaultView: "table", defaultActiveId: rows[0].id });
+
+// The toggle / columns menu can live anywhere — they just read dv.
+<Row justify="between">
+  <h1>Alerts</h1>
+  <Row gap="sm">
+    <DataView.Columns columns={columns} visibility={dv.columnVisibility} onVisibilityChange={dv.setColumnVisibility} />
+    <DataView.Toggle value={dv.view} onChange={dv.setView} views={dv.views} />
+  </Row>
+</Row>
+
+<DataView
+  data={rows}
+  columns={columns}
+  view={dv.view}
+  activeId={dv.activeId}
+  onActiveChange={dv.setActiveId}
+  sorting={dv.sorting}
+  onSortingChange={dv.setSorting}
+  columnVisibility={dv.columnVisibility}
+  onColumnVisibilityChange={dv.setColumnVisibility}
+  stickyHeader
+/>
+```
+
+```jsx
+// Self-contained: built-in toolbar, single column pinned, table only.
+<DataView
+  data={rows}
+  toolbar
+  columns={[
+    { key: "name", header: "Name", role: "title", pinned: "left", width: 220 },
+    { key: "status", header: "Status", type: "badge", options: statusOptions, sortable: true },
+    { key: "arr", header: "ARR", type: "currency", align: "end", sortable: true },
+  ]}
+/>
+```

package/components/ui/map.md

@@ -90,3 +90,9 @@ ANTI-PATTERNS — don't do these:
 - DO NOT render >500 markers without clustering. The component warns in dev. For larger datasets, drop to `.instance` and use the provider's clustering layer.
 
 Markers are DOM — children inherit `--gds-*` tokens. Drop a `<Card>`, `<Badge>`, `<Avatar>`, or anything else inside `<MapMarker>` and it themes correctly.
+
+Stacking inside a marker follows normal DOM order on every provider — you do NOT need `z-index` hacks to layer content (e.g. a count label sitting on top of an inline pin-shield `<svg>`). The DS neutralizes Leaflet's vendor rule that sets `z-index: 200` on map `<svg>` elements (via `[data-gds-part="map-marker-content"] svg { z-index: auto }` in `globals.css`); without it, an inline SVG would paint above later siblings on Leaflet (the default provider) but not on Mapbox/MapLibre/Google, making the same marker markup look provider-dependent. If you nest an inline SVG behind text in a marker, just rely on source order.
+
+For a floating text label over busy tiles, add the `gds-map-label` class — it applies a mode-aware halo (`--gds-map-label-halo`: white stroke on light tiles, near-black on dark) so the label never washes out. Don't hard-code a white `-webkit-text-stroke`.
+
+Note: `<Map>` carries no border-radius or border of its own — it's an unopinionated primitive (the container clips with `overflow: hidden`). Round or frame it from the call site with `className` (e.g. `rounded-xl border`).

package/components/ui/property-list.md

@@ -0,0 +1,43 @@
+---
+name: PropertyList
+import: "@gradeui/ui"
+props:
+  - layout?: "row" | "stack" — row (default): label column beside value; stack: label above value for narrow panels
+  - density?: "compact" | "default" | "relaxed" — row rhythm
+  - align?: "start" | "center" — default vertical alignment of label vs value; use start when values wrap (tag groups, multi-line)
+  - divider?: boolean — hairline rule between rows
+  - labelWidth?: string — override the label column width (any CSS length); sets --gds-property-list-label-width
+  - children: PropertyList.Row[]
+when_to_use: Read-only display of the properties of a SINGLE item — detail panels, inspectors, "about this" cards, order/record summaries. It is a Table row transposed (schema vertical, one record). The value side is a polymorphic slot, so the same renderers that fill a Table cell (text, Badge, tag group, Avatar stack, date, link) drop straight into a row. For an EDITABLE field (label + control) use Field instead; a panel that flips between read and edit swaps a PropertyList for a stack of Fields.
+composes_with: [Badge, Avatar, Table, Field, Separator, Card]
+aliases: [property list, properties, property panel, description list, definition list, detail list, key value, key-value, data list, field list, attributes, metadata list, record summary, detail panel, inspector fields, spec list]
+---
+
+```jsx
+<PropertyList>
+  <PropertyList.Row label="Status" icon={<Activity />}>
+    <Badge variant="warning-soft">Low</Badge>
+  </PropertyList.Row>
+  <PropertyList.Row label="Published">2026-06-18</PropertyList.Row>
+  <PropertyList.Row label="Owner">
+    <Avatar className="h-5 w-5"><AvatarFallback>EO</AvatarFallback></Avatar>
+  </PropertyList.Row>
+</PropertyList>
+```
+
+```jsx
+<PropertyList density="compact" divider align="start">
+  <PropertyList.Row label="Topics">
+    <Row gap="xs" wrap>
+      <Badge variant="secondary">Pricing</Badge>
+      <Badge variant="secondary">Onboarding</Badge>
+    </Row>
+  </PropertyList.Row>
+  <PropertyList.Row label="Business profiles">
+    <Row gap="xs" wrap>
+      <Badge variant="outline">Acme</Badge>
+      <Badge variant="outline">Kite</Badge>
+    </Row>
+  </PropertyList.Row>
+</PropertyList>
+```