@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/citations.md

@@ -0,0 +1,241 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: citations
+  sourceFile: packages/design-system/src/components/citations.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: CitationMarker
+      kind: component
+      typeText: "({ source, onShow }: CitationMarkerProps) => Element"
+    - name: CitationMarkerProps
+      kind: type
+    - name: CitationSource
+      kind: type
+    - name: CitationSourceKind
+      kind: type
+    - name: formatSourceDate
+      kind: function
+      typeText: "(iso: string) => string"
+    - name: isStale
+      kind: function
+      typeText: "(date: string, asOf: string, days?: number) => boolean"
+    - name: SourceAvatar
+      kind: component
+      typeText: "({ kind, size }: SourceAvatarProps) => Element"
+    - name: SourceAvatarProps
+      kind: type
+    - name: SourceCard
+      kind: component
+      typeText: "ForwardRefExoticComponent<SourceCardProps & RefAttributes<HTMLDivElement>>"
+    - name: SourceCardProps
+      kind: type
+    - name: SourceList
+      kind: component
+      typeText: "ForwardRefExoticComponent<SourceListProps & RefAttributes<HTMLDivElement>>"
+    - name: SourceListProps
+      kind: type
+    - name: UnsupportedClaim
+      kind: component
+      typeText: "({ children, note }: UnsupportedClaimProps) => Element"
+    - name: UnsupportedClaimProps
+      kind: type
+  primaryExport: CitationMarker
+  subcomponents:
+    - SourceAvatar
+    - SourceCard
+    - SourceList
+    - UnsupportedClaim
+  props:
+    CitationMarker:
+      - name: onShow
+        type: "((id: number) => void)"
+        required: false
+        declaredIn: self
+        doc: "Adds \"Show in sources\" to the preview, e.g. to scroll to and highlight the source in a list."
+      - name: source
+        type: CitationSource
+        required: true
+        declaredIn: self
+    SourceAvatar:
+      - name: kind
+        type: CitationSourceKind
+        required: false
+        declaredIn: self
+      - name: size
+        type: "\"sm\" | \"xs\""
+        required: false
+        declaredIn: self
+    SourceCard:
+      - name: asOf
+        type: string
+        required: false
+        declaredIn: self
+        doc: "ISO \"today\" for the age check. Without it, no stale badge. Pass a fixed date to render the same on server and client."
+      - name: highlighted
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Rings the card, e.g. after \"Show in sources\"."
+      - name: source
+        type: CitationSource
+        required: true
+        declaredIn: self
+      - name: staleAfterDays
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Days after which the source is marked old."
+      - name: staleLabel
+        type: string
+        required: false
+        declaredIn: self
+    SourceList:
+      - name: asOf
+        type: string
+        required: false
+        declaredIn: self
+      - name: getSourceId
+        type: "((id: number) => string)"
+        required: false
+        declaredIn: self
+        doc: "DOM id for each card, so a marker's \"Show in sources\" can scroll to and focus it."
+      - name: highlighted
+        type: number
+        required: false
+        declaredIn: self
+        doc: "The source id to ring."
+      - name: initial
+        type: number
+        required: false
+        declaredIn: self
+        doc: "How many show before \"Show N more\". Defaults to all."
+      - name: onExpand
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: sources
+        type: "CitationSource[]"
+        required: true
+        declaredIn: self
+    UnsupportedClaim:
+      - name: children
+        type: ReactNode
+        required: true
+        declaredIn: self
+      - name: note
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Tooltip explaining the mark."
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - xs
+      default: sm
+      on: SourceAvatar
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - source-card
+    - source-list
+  dependsOn:
+    internal:
+      - avatar
+      - badge
+      - button
+      - popover
+      - text
+      - text-link
+      - tooltip
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Sources
+      id: components-citations--sources
+    - exportName: Collapsed
+      id: components-citations--collapsed
+    - exportName: Highlighted
+      id: components-citations--highlighted
+    - exportName: CitedAnswer
+      id: components-citations--cited-answer
+  storybookTitle: Components/Citations
+  docsId: components-citations--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "0c4ab9435b20"
+  factsHash: "2578f26d8544"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "Source citations for AI answers: numbered markers in the text that preview the passage used, a mark for claims no source backs, and a numbered source list with age warnings."
+useWhen:
+  - "an assistant answer states facts that people should be able to check"
+  - "a claim in an answer has no source and should be marked as an estimate"
+  - "an answer lists its sources with the exact passage used and how old each is"
+useInstead:
+  - id: blockquote
+    when: "quoting a passage on its own, not citing it from an answer"
+  - id: text-link
+    when: "a plain inline link with no preview or numbering"
+related:
+  - chat-message
+  - popover
+  - blockquote
+a11y:
+  notes:
+    - "Each marker is a button named \"Source N: title\" that opens the preview popover."
+    - "The unsupported-claim icon is a real button named \"Not backed by a source\" so keyboard users reach the tooltip."
+    - "SourceList is an ordered list labelled \"Sources\"; cards take focus (tabIndex -1) so \"Show in sources\" can move focus to them."
+  radixHandles: true
+pitfalls:
+  - "Pass a fixed asOf date to SourceCard and SourceList; reading today's date on the server and client renders different badges."
+  - "Give getSourceId and focus the card yourself in onShow; the marker only calls back with the id."
+  - "Markers and the unsupported mark use tooltips and popovers, so mount a TooltipProvider above them."
+canonicalSnippet: |
+  import { CitationMarker, SourceList } from "@adres/mgda-ui"
+
+  <p>
+    Listed at about AED 2,400 per sqft
+    <CitationMarker source={sources[0]} onShow={scrollToSource} />.
+  </p>
+  <SourceList sources={sources} asOf="2026-10-06" getSourceId={(id) => `source-${id}`} />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "0c4ab9435b20"
+---
+
+## Usage
+
+Put a `CitationMarker` after each cited fact in the answer. It is a small
+muted pill with the source kind's icon and number; opening it previews the publisher, date, title and the passage
+used, with "Open" and, when `onShow` is set, "Show in sources". Wrap a claim
+no source backs in `UnsupportedClaim` so it reads as the assistant's
+estimate.
+
+Under the answer, `SourceList` numbers the sources as `SourceCard`s with the
+linked title, publisher, kind and date, an "Older than 6 months" badge past
+`staleAfterDays`, and the passage. `initial` and `onExpand` fold long lists
+behind "Show N more". Each source can carry a `kind` (`{ label, icon }`);
+`SourceAvatar` shows that icon, for example stacked in a sources button.
+`isStale` and `formatSourceDate` are exported.
+
+## Anatomy
+
+- `CitationMarker` - numbered inline marker with a source preview.
+- `UnsupportedClaim` - dashed warning underline plus an explained warning icon.
+- `SourceCard` - one numbered source with its passage.
+- `SourceList` - ordered list of source cards with "Show N more".
+- `SourceAvatar` - the source kind's icon in a small avatar.

package/knowledge/combobox.md

@@ -0,0 +1,265 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: combobox
+  sourceFile: packages/design-system/src/components/combobox.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Combobox
+      kind: component
+      typeText: "({ items, value, onValueChange, onSelect, query: queryProp, onQueryChange, filter, startContent, emptyMessage, loading, loadingMessage, maxPerGroup, highlightMatches, placeholder, \"aria-label\": ariaLabel, id, name, size,...[truncated]"
+    - name: ComboboxItem
+      kind: type
+    - name: ComboboxProps
+      kind: type
+    - name: ComboboxSize
+      kind: type
+    - name: defaultComboboxFilter
+      kind: function
+      typeText: "(item: ComboboxItem, query: string) => boolean"
+    - name: groupComboboxItems
+      kind: function
+      typeText: "(items: ComboboxItem[], maxPerGroup?: number) => { name: string | undefined; items: ComboboxItem[]; }[]"
+    - name: nextEnabledIndex
+      kind: function
+      typeText: "(items: ComboboxItem[], from: number, direction: 1 | -1) => number"
+    - name: splitComboboxMatch
+      kind: function
+      typeText: "(text: string, query: string) => { before: string; match: string; after: string; }"
+  primaryExport: Combobox
+  subcomponents: []
+  props:
+    Combobox:
+      - name: aria-label
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accessible name. Required unless a <Label htmlFor={id}> names the input."
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+      - name: disabled
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: emptyMessage
+        type: "((query: string) => ReactNode) | ReactNode"
+        required: false
+        declaredIn: self
+        doc: "Shown when the query matches nothing. Receives the trimmed query."
+      - name: filter
+        type: "((item: ComboboxItem, query: string) => boolean)"
+        required: false
+        declaredIn: self
+        doc: "Return true to keep an item. Default: case-insensitive match on label, description and keywords."
+      - name: highlightMatches
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Bold the matched part of each label. Default true."
+      - name: id
+        type: string
+        required: false
+        declaredIn: self
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: items
+        type: "ComboboxItem[]"
+        required: true
+        declaredIn: self
+      - name: loading
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show a pending row instead of results, e.g. while fetching remote items."
+      - name: loadingMessage
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: maxPerGroup
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Cap the rows shown per group (or overall when ungrouped)."
+      - name: name
+        type: string
+        required: false
+        declaredIn: self
+      - name: onQueryChange
+        type: "((query: string) => void)"
+        required: false
+        declaredIn: self
+      - name: onSelect
+        type: "((item: ComboboxItem) => void)"
+        required: false
+        declaredIn: self
+        doc: "Called on every pick. Without `value`, the input clears after a pick (search launcher)."
+      - name: onValueChange
+        type: "((value: string | null) => void)"
+        required: false
+        declaredIn: self
+      - name: placeholder
+        type: string
+        required: false
+        declaredIn: self
+      - name: query
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Controlled query. Leave unset to let the combobox own it."
+      - name: size
+        type: InputSize
+        required: false
+        declaredIn: self
+      - name: startContent
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Shown instead of the item list while the query is empty, e.g. recent searches."
+      - name: value
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Selected item's value. Set it (with onValueChange) for a picker that shows the choice in the input."
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: Combobox
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - SIZE_TEXT
+  dataSlots:
+    - combobox
+  dependsOn:
+    internal:
+      - input
+      - spinner
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-popover"
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-combobox--default
+    - exportName: WithLabel
+      id: components-combobox--with-label
+    - exportName: SearchLauncher
+      id: components-combobox--search-launcher
+    - exportName: Loading
+      id: components-combobox--loading
+    - exportName: Invalid
+      id: components-combobox--invalid
+    - exportName: KeyboardSelection
+      id: components-combobox--keyboard-selection
+    - exportName: SearchSelection
+      id: components-combobox--search-selection
+    - exportName: RemoteResults
+      id: components-combobox--remote-results
+  storybookTitle: Components/Combobox
+  docsId: components-combobox--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: b8d3d12095c6
+  factsHash: ec2144723e3f
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "Text input with a filtered, keyboard-navigable list of options: a picker that keeps the chosen value, or a search launcher that clears after each pick."
+useWhen:
+  - "a single choice from a list too long to scan in a Select, e.g. communities, projects or agents"
+  - "an app-wide search box that suggests grouped results while typing"
+  - "options load from a server as the user types, using query, onQueryChange and loading"
+useInstead:
+  - id: select
+    when: "there are only a handful of options and typing to filter adds nothing"
+  - id: search
+    when: "the field filters a list already on the page and needs no suggestions"
+  - id: dropdown-menu
+    when: "the options are actions to run, not values to choose"
+related:
+  - search
+  - select
+  - popover
+a11y:
+  notes:
+    - "Implements the WAI-ARIA combobox pattern: role=combobox on the input, aria-expanded, aria-controls on the open listbox, and aria-activedescendant for the highlighted option. Focus never leaves the input."
+    - "Give it a name with aria-label, or with a <Label htmlFor={id}> and the id prop. Without either the input is announced only as 'combobox'."
+    - "The result count is announced through a polite live region while typing."
+    - "The trailing clear button is labelled 'Clear selection' in picker mode and 'Clear search' otherwise, and returns focus to the input."
+    - "Mark decorative item icons aria-hidden; the label is the option's accessible name."
+  keyboard:
+    - "ArrowDown / ArrowUp open the list and move through enabled options, wrapping at the ends; disabled options are skipped."
+    - "Home / End jump to the first or last enabled option while the list is open."
+    - "Enter picks the highlighted option. Typing highlights the first match, so Enter picks it straight away."
+    - "Escape closes the list and keeps the typed text; Tab closes it and moves on."
+  radixHandles: false
+pitfalls:
+  - "Passing value turns on picker mode: the input shows the selected label and clearing it calls onValueChange(null). Leave value unset (undefined, not null) for a search launcher that clears after each pick."
+  - "startContent replaces the item list while the query is empty. Without it, an empty query lists every item, which suits a picker but not a large search index."
+  - "The default filter is a substring match on label, description and keywords. Pass filter for fuzzy or server-side matching, and set loading while results are fetched."
+  - "The list renders in a portal, so it is not clipped by overflow-hidden parents, but it also does not inherit their styles."
+canonicalSnippet: |
+  import { Combobox } from "@adres/mgda-ui"
+
+  <Combobox
+    items={communities}
+    value={community}
+    onValueChange={setCommunity}
+    placeholder="Choose a community"
+    aria-label="Community"
+  />
+reviewedAt: 2026-10-05
+reviewedAgainstContractHash: b8d3d12095c6
+---
+
+## Usage
+
+`Combobox` is the DS answer whenever typing should narrow a list of options.
+It has two modes, chosen by whether you pass `value`:
+
+- **Picker** (`value` + `onValueChange`): the chosen option's label stays in
+  the input, the selected option is marked in the list, and clearing the input
+  clears the value. Use it in forms in place of a `Select` with many options.
+- **Search launcher** (`onSelect` only): each pick fires `onSelect` and the
+  input clears for the next search. Pair it with `startContent` for recent
+  searches and `group` on items for sections such as Properties and Agents.
+
+Items are plain data. `group` sections them in first-seen order (capped by
+`maxPerGroup`), `description` adds trailing detail such as a price, `icon`
+adds a leading visual, and `keywords` adds hidden match text, for example a
+property's community.
+
+### Remote results
+
+```tsx
+<Combobox
+  items={results}
+  query={query}
+  onQueryChange={setQuery}
+  filter={() => true}
+  loading={isFetching}
+  onSelect={openResult}
+  aria-label="Search listings"
+/>
+```
+
+Own the `query`, fetch on change, and pass `filter={() => true}` because the
+server has already filtered.

package/knowledge/countdown-pill.md

@@ -0,0 +1,153 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: countdown-pill
+  sourceFile: packages/design-system/src/components/countdown-pill.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: CountdownPill
+      kind: component
+      typeText: "ForwardRefExoticComponent<CountdownPillProps & RefAttributes<HTMLDivElement>>"
+    - name: CountdownPillProps
+      kind: type
+    - name: CountdownSize
+      kind: type
+    - name: CountdownTone
+      kind: type
+    - name: getCountdownLabel
+      kind: function
+      typeText: "(dateIso: string, ongoingLabel: string, now?: number) => string"
+  primaryExport: CountdownPill
+  subcomponents: []
+  props:
+    CountdownPill:
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional icon override. Defaults to a Clock glyph. Pass `null` to omit."
+      - name: label
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Optional context label rendered before the value. e.g. `\"Starts in\"`, `\"Bidding ends in\"`."
+      - name: size
+        type: CountdownSize
+        required: false
+        declaredIn: self
+        doc: "Visual density."
+      - name: tone
+        type: CountdownTone
+        required: false
+        declaredIn: self
+        doc: "Visual urgency tier. Drives the value (and icon) color so the consumer can dial attention up or down without changing markup."
+      - name: value
+        type: string
+        required: true
+        declaredIn: self
+        doc: "The countdown text itself - the bit that gets emphasized. e.g. `\"2h 15m\"`, `\"3 days\"`, `\"Live now\"`."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    tone:
+      kind: enum
+      options:
+        - info
+        - success
+        - warning
+        - neutral
+        - critical
+      default: neutral
+      on: CountdownPill
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: CountdownPill
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - GAP_CLASS
+    - ICON_CLASS
+    - LABEL_CLASS
+    - TONE_ICON
+    - TONE_VALUE
+    - VALUE_CLASS
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-countdownpill--default
+    - exportName: Critical
+      id: components-countdownpill--critical
+  storybookTitle: Components/CountdownPill
+  docsId: components-countdownpill--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "8ad71d408603"
+  factsHash: "372ace40c571"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "An inline countdown display for time-to-event copy - a muted context label plus a large, tone-colored value, with a matching getCountdownLabel formatter."
+useWhen:
+  - "showing time remaining until, or since, an event inline - session starts, deadlines, auction end times"
+  - "urgency should visually escalate as the deadline approaches, via tone"
+useInstead:
+  - id: step-indicator
+    when: "the content is discrete steps in a process, not a countdown to a single point in time"
+related:
+  - step-indicator
+tokens:
+  - "--foreground"
+  - "--muted-foreground"
+  - "--primary"
+  - "--success-foreground"
+  - "--warning-foreground"
+  - "--destructive-foreground"
+a11y:
+  notes:
+    - "Purely presentational text - no live region or ARIA is added, so a countdown that updates in place (e.g. on an interval) does not announce its own changes to screen readers. Wrap it in your own aria-live region if the live update itself needs to be announced, not just visible."
+  radixHandles: false
+pitfalls:
+  - "CountdownPill is display-only - it does not tick down on its own or manage any timer. value is a static string recomputed and re-rendered by the caller, typically alongside getCountdownLabel on an interval."
+  - "tone is never inferred from the value or from time remaining - the component has no concept of how urgent a given duration is. Pick the tone in the consumer based on your own thresholds, and update it alongside value."
+  - "getCountdownLabel deliberately does not return a tone - it only formats the string (\"2h 15m\", \"3 days\", or your ongoingLabel). It will not also tell you how urgent that duration is."
+canonicalSnippet: |
+  import { CountdownPill } from "@adres/mgda-ui"
+
+  <CountdownPill label="Starts in" value="2h 15m" tone="warning" />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "8ad71d408603"
+---
+
+## Usage
+
+`CountdownPill` is for inline time-to-event copy - a session starting soon,
+a bidding deadline, a limited-time offer. It pairs a muted context `label`
+("Starts in") with a large, `tone`-colored `value` ("2h 15m") that raises
+attention as urgency increases. Reach for `StepIndicator` instead when the
+content is discrete steps in a process, not a countdown to one point in
+time.
+
+The component is presentational only - it has no timer of its own. Compute
+`value` yourself - the paired `getCountdownLabel(dateIso, ongoingLabel)`
+helper formats an ISO timestamp into `"2h 15m"`/`"3 days"`/your ongoing
+label - and re-render on whatever interval you choose. `tone` is likewise
+never inferred; pick it from your own urgency thresholds and update it
+alongside `value`.