@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/pricing.md

@@ -0,0 +1,132 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: pricing
+  sourceFile: packages/design-system/src/components/pricing.tsx
+  client: true
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Pricing
+      kind: component
+      typeText: "({ className, eyebrow, title, description, tiers, ...props }: PricingProps) => Element"
+    - name: PricingProps
+      kind: type
+    - name: PricingTier
+      kind: type
+  primaryExport: Pricing
+  subcomponents: []
+  props:
+    Pricing:
+      - name: description
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: eyebrow
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: tiers
+        type: "PricingTier[]"
+        required: true
+        declaredIn: self
+      - name: title
+        type: ReactNode
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLElement>, \"title\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+      - motion
+    hooks:
+      - use-reduced-motion
+    external:
+      - lucide-react
+      - motion/react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-pricing--default
+  storybookTitle: Components/Pricing
+  docsId: components-pricing--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: bd27f89d7eb9
+  factsHash: c49d11237576
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A pricing tier grid - name, price, optional period/badge/description, a feature checklist, and a CTA per tier, with one tier optionally highlighted as the recommended plan."
+useWhen:
+  - "presenting 2 or more pricing plans side by side with a feature comparison checklist and a per-tier CTA"
+useInstead:
+  - id: feature-grid
+    when: "showcasing product capabilities generally, not comparing purchasable plans"
+related:
+  - feature-grid
+a11y:
+  notes:
+    - "cta is untyped ReactNode per tier - the component adds no button semantics itself, so each tier's cta needs to be a real interactive element, typically a Button, with its own accessible name, not styled text."
+    - "highlighted only changes visual styling, a filled primary card versus a bordered neutral one - it carries no semantic recommended announcement to assistive tech; if that distinction matters, say so in the tier's badge or description text, which are read normally."
+  radixHandles: false
+pitfalls:
+  - "features is a flat string array per tier - there is no way to mark an item as excluded or unavailable; every listed feature renders identically with the same checkmark, so an excluded-features design needs a workaround string or a different component."
+  - "The grid layout branches on tiers.length - 2 tiers get a narrower, centered layout while 3 or more span the full section width, so adding or removing a tier can change the overall section width, not just the column count."
+  - "highlighted is a plain boolean with no built-in guard against multiple tiers being highlighted at once - passing it true on more than one tier renders more than one filled primary card, which undermines the single-recommended-plan pattern the styling implies."
+  - "badge only renders when tier.badge is set, and its color inverts opposite the tier's own highlighted state - a highlighted tier's badge does not just look the same as a non-highlighted one's, its colors are intentionally swapped for contrast."
+canonicalSnippet: |
+  import { Button, Pricing } from "@adres/mgda-ui"
+
+  const heading = "Simple, transparent pricing"
+  const tiers = [
+    {
+      name: "Starter",
+      price: "$9",
+      period: "mo",
+      features: ["1 project", "Community support"],
+      cta: <Button variant="outline">Choose Starter</Button>,
+    },
+    {
+      name: "Pro",
+      price: "$29",
+      period: "mo",
+      features: ["Unlimited projects", "Priority support"],
+      cta: <Button>Choose Pro</Button>,
+      highlighted: true,
+      badge: "Most popular",
+    },
+  ]
+
+  <Pricing title={heading} tiers={tiers} />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: bd27f89d7eb9
+---
+
+## Usage
+
+`Pricing` presents pricing tiers side by side - each with a name, price, an
+optional billing period and badge, a feature checklist, and a CTA. Reach for
+`FeatureGrid` instead when showcasing product capabilities generally rather
+than comparing purchasable plans.
+
+Set `highlighted: true` on at most one tier to mark it as the recommended
+plan - it swaps to a filled primary card and inverts the badge's coloring
+for contrast. The component does not guard against multiple highlighted
+tiers; that is a call-site discipline, not something enforced.
+
+`features` is a flat list of strings, all rendered with the same checkmark -
+there is no way to mark a feature as excluded or unavailable on a given tier
+within this component. The grid layout itself branches on how many `tiers`
+are passed: 2 tiers get a narrower, centered layout, while 3 or more span
+the full section width.

package/knowledge/progress.md

@@ -0,0 +1,156 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: progress
+  sourceFile: packages/design-system/src/components/progress.tsx
+  client: true
+  category: web-app-feedback
+  categoryFromBarrel: web-app-feedback
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Progress
+      kind: component
+      typeText: "ForwardRefExoticComponent<ProgressProps & RefAttributes<HTMLDivElement>>"
+    - name: ProgressProps
+      kind: type
+    - name: ProgressShape
+      kind: type
+    - name: ProgressSize
+      kind: type
+    - name: ProgressVariant
+      kind: type
+  primaryExport: Progress
+  subcomponents: []
+  props:
+    Progress:
+      - name: max
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Maximum value. Defaults to 100."
+      - name: ringSize
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Ring-only: override the pixel diameter (takes precedence over `size`)."
+      - name: shape
+        type: ProgressShape
+        required: false
+        declaredIn: self
+        doc: "Visual shape - horizontal `bar` (default) or circular `ring`."
+      - name: size
+        type: ProgressSize
+        required: false
+        declaredIn: self
+        doc: "Size - applies to both shapes: bar → height (h-1 / h-2 / h-4) ring → pixel diameter (32 / 48 / 64)"
+        variantKey: true
+      - name: strokeWidth
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Ring-only: override the stroke width in pixels."
+      - name: value
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Current value, 0-max."
+      - name: variant
+        type: ProgressVariant
+        required: false
+        declaredIn: self
+        doc: "Colour treatment. The track stays neutral; this drives the indicator."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: Progress
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - RING_DEFAULT_PX
+    - RING_DEFAULT_STROKE
+    - RING_STROKE_CLASS
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-progress--default
+    - exportName: Ring
+      id: components-progress--ring
+  storybookTitle: Components/Progress
+  docsId: components-progress--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "81975d7fc639"
+  factsHash: d13c34778748
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A determinate progress indicator with a known value - horizontal bar or circular ring shape, both driven by the same props."
+useWhen:
+  - "showing progress toward a known total - an upload, a multi-step wizard, a quota, anything with a real percentage"
+useInstead:
+  - id: spinner
+    when: "the duration is unknown - there is no value to show, just an indication that something is happening"
+  - id: quota-bar
+    when: "showing usage against a limit with its own labeling conventions, not a generic progress value"
+  - id: step-indicator
+    when: "the progress is a fixed sequence of discrete, named steps rather than a continuous percentage"
+related:
+  - spinner
+  - quota-bar
+  - step-indicator
+tokens:
+  - "--muted"
+  - "--primary"
+  - "--success"
+  - "--warning"
+  - "--destructive"
+a11y:
+  notes:
+    - "Sets role=\"progressbar\" plus aria-valuemin/max/now automatically from value/max - no extra ARIA is needed for either shape."
+    - "Neither shape renders a visible label - pair Progress with your own visible text (e.g. \"64% uploaded\") when the percentage itself matters to sighted users, since aria-valuenow alone only reaches assistive tech."
+  radixHandles: false
+pitfalls:
+  - "size means different things per shape: for shape=\"bar\" it sets the bar's height (h-1/h-2/h-4); for shape=\"ring\" it sets the ring's pixel diameter (32/48/64) instead. Switching shape without reconsidering size can produce an unexpectedly tiny or huge ring."
+  - "ringSize and strokeWidth are ring-only and silently do nothing on shape=\"bar\" - they do not throw or warn if passed to a bar."
+  - "value is not clamped to max by the component's props themselves, only by the rendered percentage - aria-valuenow still reports the raw, unclamped value, so passing a value greater than max reports an out-of-range value to assistive tech even though the visual fill stops at 100%."
+canonicalSnippet: |
+  import { Progress } from "@adres/mgda-ui"
+
+  <Progress value={64} variant="default" />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "81975d7fc639"
+---
+
+## Usage
+
+`Progress` shows progress toward a known total - reach for it whenever there
+is a real percentage to display (an upload, a wizard step count, a quota).
+Reach for `Spinner` instead when the duration is unknown and there is no
+value to show at all.
+
+`shape="bar"` (default) is a horizontal track; `shape="ring"` is a circular
+one - both read `value`/`max`/`variant` the same way, but `size` means
+something different for each: bar height for `bar`, pixel diameter for
+`ring`. Override a ring's exact dimensions with `ringSize`/`strokeWidth`,
+which have no effect on the bar shape.
+
+`variant` (`default`/`success`/`warning`/`error`) only recolors the
+indicator - the track stays neutral in both shapes, so the color always
+reads as how the progress is going, not the base fill.

package/knowledge/prompt-input.md

@@ -0,0 +1,337 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: prompt-input
+  sourceFile: packages/design-system/src/components/prompt-input.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: AttachmentChip
+      kind: component
+      typeText: "ForwardRefExoticComponent<AttachmentChipProps & RefAttributes<HTMLDivElement>>"
+    - name: AttachmentChipProps
+      kind: type
+    - name: characterCountTone
+      kind: function
+      typeText: "(length: number, max: number) => CharacterCountTone"
+    - name: CharacterCountTone
+      kind: type
+    - name: formatFileSize
+      kind: function
+      typeText: "(bytes: number) => string"
+    - name: isFileDrag
+      kind: function
+      typeText: "(types: readonly string[]) => boolean"
+    - name: PromptInput
+      kind: component
+      typeText: "ForwardRefExoticComponent<PromptInputProps & RefAttributes<HTMLDivElement>>"
+    - name: PromptInputAction
+      kind: component
+      typeText: "ForwardRefExoticComponent<PromptInputActionProps & RefAttributes<HTMLButtonElement>>"
+    - name: PromptInputActionProps
+      kind: type
+    - name: PromptInputProps
+      kind: type
+    - name: PromptInputSize
+      kind: type
+  primaryExport: PromptInput
+  subcomponents:
+    - AttachmentChip
+    - PromptInputAction
+  props:
+    AttachmentChip:
+      - name: error
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Replaces size and progress, and tints the chip."
+      - name: kind
+        type: "\"file\" | \"image\""
+        required: false
+        declaredIn: self
+      - name: name
+        type: string
+        required: true
+        declaredIn: self
+      - name: onRemove
+        type: "() => void"
+        required: true
+        declaredIn: self
+      - name: previewUrl
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Thumbnail for images."
+      - name: progress
+        type: number
+        required: false
+        declaredIn: self
+        doc: "0-100 while uploading; omit or 100 when done."
+      - name: size
+        type: number
+        required: true
+        declaredIn: self
+        doc: "Bytes; shown once the upload finishes."
+    PromptInput:
+      - name: attachments
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Above the field: usually a list of `AttachmentChip`s."
+      - name: busy
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "True while the assistant answers; Send becomes Stop."
+      - name: canSubmit
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Extra gate on sending, e.g. false while uploads are in progress."
+      - name: defaultValue
+        type: string
+        required: false
+        declaredIn: self
+      - name: disabled
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: disabledReason
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Shown under the field when `disabled`, e.g. why the assistant is unavailable."
+      - name: dropHint
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Extra line in the drop overlay, e.g. accepted types and size limit."
+      - name: endActions
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "End of the action row, before Send: voice input, status badges."
+      - name: hasAttachments
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Lets an empty field send, e.g. when files are attached."
+      - name: hint
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Muted note under the field when nothing more urgent applies, e.g. \"Waiting for uploads to finish.\""
+      - name: label
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accessible name of the field."
+      - name: maxLength
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Characters allowed; the counter appears from 80% and sending is blocked when over."
+      - name: onFilesDrop
+        type: "((files: File[]) => void)"
+        required: false
+        declaredIn: self
+        doc: "Receives files dropped on the composer, which shows a drop overlay while dragging. Ignored while `disabled`."
+      - name: onFilesPaste
+        type: "((files: File[]) => void)"
+        required: false
+        declaredIn: self
+        doc: "Receives files pasted into the field; without it, pasting files does nothing special."
+      - name: onStop
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: onSubmit
+        type: "(text: string) => void"
+        required: true
+        declaredIn: self
+        doc: "Called with the trimmed text on Enter or Send. The field then clears and keeps focus."
+      - name: onValueChange
+        type: "((value: string) => void)"
+        required: false
+        declaredIn: self
+      - name: placeholder
+        type: string
+        required: false
+        declaredIn: self
+      - name: size
+        type: PromptInputSize
+        required: false
+        declaredIn: self
+        doc: "`sm` is a tighter composer for narrow chat columns and side panels."
+      - name: toolbar
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Start of the action row: attach, tools. Use `PromptInputAction` for icon buttons."
+      - name: value
+        type: string
+        required: false
+        declaredIn: self
+    PromptInputAction:
+      - name: aurora
+        type: boolean
+        required: false
+        declaredIn: button
+        doc: "Decorative \"aurora\" - two soft, blurred orbs (primary + accent) drifting behind the label for a modern, glowing look. Designed for the `primary` variant. Ignored with `asChild` (it needs to inject its own children)."
+      - name: label
+        type: string
+        required: true
+        declaredIn: self
+        doc: "Accessible name, and the tooltip unless `tooltip` is set."
+      - name: pressed
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Renders as a toggle: sets `aria-pressed`."
+      - name: tooltip
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Longer tooltip text, e.g. accepted file types."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onSubmit\" | \"defaultValue\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+      default: md
+      on: PromptInput
+    kind:
+      kind: enum
+      options:
+        - image
+        - file
+      default: file
+      on: AttachmentChip
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - attachment-chip
+    - prompt-input
+  dependsOn:
+    internal:
+      - button
+      - input
+      - progress
+      - text
+      - tooltip
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts:
+    - name: PromptInputSizeContext
+      type: PromptInputSize
+      default: md
+  stories:
+    - exportName: Default
+      id: components-promptinput--default
+    - exportName: Busy
+      id: components-promptinput--busy
+    - exportName: NearTheLimit
+      id: components-promptinput--near-the-limit
+    - exportName: OverTheLimit
+      id: components-promptinput--over-the-limit
+    - exportName: Disabled
+      id: components-promptinput--disabled
+    - exportName: WithAttachments
+      id: components-promptinput--with-attachments
+    - exportName: Small
+      id: components-promptinput--small
+    - exportName: FileDrop
+      id: components-promptinput--file-drop
+  storybookTitle: Components/PromptInput
+  docsId: components-promptinput--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: c19fe6810c55
+  factsHash: "197ba009f45f"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "The prompt composer for an AI feature: an auto-growing field with Enter to send, Send or Stop, a character limit, and slots for attachments, tools and voice."
+useWhen:
+  - "people type a prompt to an assistant, with or without attachments"
+  - "the composer must switch to Stop while the assistant answers"
+  - "the assistant is unavailable and the composer should say why instead of disappearing"
+useInstead:
+  - id: input
+    when: "a plain text field that is not a prompt to an assistant; for a one-line question scoped to the page use PromptInput size=\"sm\""
+  - id: search
+    when: "people search or filter rather than ask an assistant"
+related:
+  - chat-message
+  - prompt-suggestions
+  - dropzone
+a11y:
+  notes:
+    - "The field is named by label (default \"Prompt\"); the hint line is linked with aria-describedby."
+    - "Over the limit the field is aria-invalid and the hint says how many characters to cut; the counter is a polite live region."
+    - "Send and Stop are icon buttons named \"Send message\" and \"Stop generating\"."
+    - "PromptInputAction is named by label; pass tooltip for longer help text and pressed for toggles such as voice input."
+    - "Wrap AttachmentChips in role=\"list\" with a label; each chip's remove button names the file."
+  radixHandles: false
+pitfalls:
+  - "onSubmit receives trimmed text and the field clears itself; in controlled mode it calls onValueChange(\"\") so keep value in sync."
+  - "Set hasAttachments so attachments alone can be sent, and canSubmit={false} while uploads run."
+  - "Pass onFilesDrop to accept dropped files; the composer shows its own drop overlay (add dropHint for limits) and ignores drags without files. Validate type and size in the handler."
+  - "Without onFilesPaste, pasted files are ignored and only text pastes."
+  - "Use PromptInputAction for icon buttons in toolbar and endActions so they match the round 36px Send button; it needs a TooltipProvider."
+canonicalSnippet: |
+  import { PromptInput } from "@adres/mgda-ui"
+
+  <PromptInput
+    onSubmit={send}
+    busy={replying}
+    onStop={stop}
+    placeholder="Ask about properties, prices or communities"
+  />
+reviewedAt: 2026-10-07
+reviewedAgainstContractHash: "c19fe6810c55"
+---
+
+## Usage
+
+`PromptInput` is the composer. The field grows to about eight lines then
+scrolls; Enter sends and Shift+Enter adds a line. `onSubmit` gets the trimmed
+text, after which the field clears and keeps focus. Leave it uncontrolled
+with `defaultValue`, or control it with `value` and `onValueChange` when
+something else writes into the field (voice input, a template chip).
+
+While `busy`, Send becomes Stop (`onStop`). The counter appears at 80% of
+`maxLength` (default 2000), turns amber at 90%, and over the limit the field
+turns invalid and sending is blocked. `disabled` with `disabledReason` keeps
+the composer visible and explains why. Put an attach button and tools menu in
+`toolbar`, voice input or status badges in `endActions`, and a list of
+`AttachmentChip`s in `attachments`; `hasAttachments`, `canSubmit` and `hint`
+tie sending to their state. `onFilesDrop` accepts files dropped anywhere on
+the composer and shows a dashed drop overlay while dragging, with `dropHint`
+for accepted types and limits; drags without files pass through. The container is a 24px rounded card with a
+borderless field and the action row underneath; `PromptInputAction` gives
+toolbar icons the same round 36px shape as Send.
+
+`size="sm"` is a tighter composer for narrow chat columns and side panels:
+smaller corners and padding, a 36px field, a close action row, 32px Send and
+Stop, and about six lines before scrolling. `PromptInputAction`s in the
+toolbar follow the composer's size.
+
+`characterCountTone` and `formatFileSize` are exported for custom composers.
+
+## Anatomy
+
+- `PromptInput` - rounded container with attachments, field, action row (toolbar, counter, end actions, Send or Stop) and hint.
+- `PromptInputAction` - round 36px outline icon button with a tooltip for the action row.
+- `AttachmentChip` - one file: thumbnail or icon, name, then upload progress, size or error, and a remove button.