@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/testimonials.md

@@ -0,0 +1,115 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: testimonials
+  sourceFile: packages/design-system/src/components/testimonials.tsx
+  client: true
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Testimonial
+      kind: type
+    - name: Testimonials
+      kind: component
+      typeText: "({ className, eyebrow, title, items, columns, ...props }: TestimonialsProps) => Element"
+    - name: TestimonialsProps
+      kind: type
+  primaryExport: Testimonials
+  subcomponents: []
+  props:
+    Testimonials:
+      - name: columns
+        type: "2 | 3"
+        required: false
+        declaredIn: self
+      - name: eyebrow
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: items
+        type: "Testimonial[]"
+        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:
+      - card
+    lib:
+      - cn
+      - motion
+    hooks:
+      - use-reduced-motion
+    external:
+      - lucide-react
+      - motion/react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-testimonials--default
+  storybookTitle: Components/Testimonials
+  docsId: components-testimonials--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "5bfb9becebf2"
+  factsHash: "960d8c79406f"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A grid of customer testimonial cards - quote, avatar or initial, name, role and company, and an optional star rating - with scroll-triggered stagger animation."
+useWhen:
+  - "showcasing customer quotes as social proof on a marketing page"
+useInstead:
+  - id: logo-cloud
+    when: "the social proof is company or brand logos, not attributed quotes"
+related:
+  - logo-cloud
+a11y:
+  notes:
+    - "Each card is a real figure/blockquote/figcaption - the quote, attribution, and card grouping all carry correct semantic structure without extra ARIA."
+    - "The star rating renders as plain decorative star icons with no accessible text equivalent, e.g. \"4 out of 5 stars\" - if the rating value itself needs to be announced to assistive tech, that is currently missing and would need to be added at the call site."
+  radixHandles: false
+pitfalls:
+  - "avatar is optional - when omitted, the component falls back to a colored circle showing the first letter of name, not a placeholder image. Keep name meaningful even when no avatar is supplied, since it drives that fallback."
+  - "rating is on a 1-5 scale rendered as 5 stars total - passing a value outside that range still renders exactly 5 stars, just all filled or all unfilled depending on the comparison, since there is no clamping or validation."
+  - "role and company are joined with a middot only when at least one is present - passing just one of the two omits the separator entirely rather than leaving a dangling one."
+  - "columns only accepts 2 or 3 - there is no single-column or 4-plus option, unlike FeatureGrid's wider 2/3/4 range."
+canonicalSnippet: |
+  import { Testimonials } from "@adres/mgda-ui"
+
+  const quotes = [
+    { quote: "This tool transformed our workflow.", name: "Jane Cooper", role: "CTO", company: "Acme", rating: 5 },
+    { quote: "Setup took minutes, not weeks.", name: "Alex Kim", role: "Founder", company: "Globex" },
+  ]
+
+  <Testimonials items={quotes} columns={2} />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "5bfb9becebf2"
+---
+
+## Usage
+
+`Testimonials` showcases customer quotes as social proof on a marketing
+page - a grid of cards, each with a quote, attribution (avatar or initial
+fallback, name, role and company), and an optional star rating. Reach for
+`LogoCloud` instead when the social proof is company or brand logos rather
+than attributed quotes.
+
+`avatar` is optional; omitting it falls back to a colored circle showing the
+first letter of `name`, so keep `name` meaningful even without a photo.
+`role` and `company` are joined with a middot only when at least one is
+present - passing just one omits the separator rather than leaving a
+dangling one. `columns` only accepts `2` or `3`, a narrower range than
+`FeatureGrid`'s.

package/knowledge/text-link.md

@@ -0,0 +1,192 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: text-link
+  sourceFile: packages/design-system/src/components/text-link.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: TextLink
+      kind: component
+      typeText: "ForwardRefExoticComponent<TextLinkProps & RefAttributes<HTMLAnchorElement>>"
+    - name: TextLinkColor
+      kind: type
+    - name: TextLinkProps
+      kind: type
+    - name: TextLinkSize
+      kind: type
+    - name: TextLinkUnderline
+      kind: type
+    - name: textLinkVariants
+      kind: variants
+      typeText: "TVReturnType<{ color: { primary: \"ax:text-primary-foreground\"; default: \"ax:text-foreground\"; muted: \"ax:text-muted-foreground ax:hover:text-foreground\"; }; underline: { hover: \"ax:no-underline ax:hover:underline\"; alway...[truncated]"
+  primaryExport: TextLink
+  subcomponents: []
+  props:
+    TextLink:
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render the child instead of an `<a>`, e.g. a framework router link."
+      - name: color
+        type: "\"default\" | \"muted\" | \"primary\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: external
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Opens in a new tab with `rel=\"noopener noreferrer\"` and announces that to screen readers."
+      - name: size
+        type: "\"1\" | \"2\" | \"3\" | \"4\" | \"5\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: underline
+        type: "\"always\" | \"hover\" | \"none\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: weight
+        type: "\"medium\" | \"regular\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, \"color\">"
+    - "VariantProps<typeof textLinkVariants>"
+  variants:
+    color:
+      kind: enum
+      options:
+        - primary
+        - default
+        - muted
+      default: primary
+      on: TextLink
+    underline:
+      kind: enum
+      options:
+        - hover
+        - always
+        - none
+      default: hover
+      on: TextLink
+    size:
+      kind: enum
+      options:
+        - "1"
+        - "2"
+        - "3"
+        - "4"
+        - "5"
+      default: null
+      on: TextLink
+    weight:
+      kind: enum
+      options:
+        - regular
+        - medium
+      default: medium
+      on: TextLink
+  variantSource: tv
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - text-link
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-slot"
+      - react
+      - tailwind-variants
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-textlink--default
+    - exportName: InSentence
+      id: components-textlink--in-sentence
+    - exportName: Colors
+      id: components-textlink--colors
+    - exportName: External
+      id: components-textlink--external
+  storybookTitle: Components/TextLink
+  docsId: components-textlink--documentation
+  argTypeOptions:
+    color:
+      - primary
+      - default
+      - muted
+    underline:
+      - hover
+      - always
+      - none
+    weight:
+      - regular
+      - medium
+  resolvedCleanly: true
+  contractHash: "371061b97da3"
+  factsHash: "1143f8a3c08f"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "Inline text link with no box: inherits the surrounding text size, with primary, default or muted colour and a hover, always or no underline."
+useWhen:
+  - "a link sits inside a sentence or label, such as 'Don't have an account? Create one'"
+  - "a standalone small link such as 'Forgot password?' beside a field label"
+  - "a link opens an external page in a new tab, via external"
+useInstead:
+  - id: button
+    when: "the control should look like a button"
+related:
+  - text
+  - button
+a11y:
+  notes:
+    - "external adds target=_blank, rel=noopener noreferrer and a screen-reader-only '(opens in a new tab)' hint on a plain anchor."
+    - "With asChild the child owns its own content, so the external hint is not injected; add it to the child yourself."
+    - "The focus-visible ring is part of the base classes. Do not remove it through className."
+  radixHandles: false
+pitfalls:
+  - "size is omitted by default so the link inherits the surrounding text size. Set it only when the link stands alone."
+  - "With a framework router, pass the router link as the child via asChild; do not nest an anchor inside TextLink."
+  - "For an action that should look like a link (Retry, Undo), pass a <button type=\"button\"> through asChild so it keeps button semantics."
+canonicalSnippet: |
+  import { TextLink, Text } from "@adres/mgda-ui"
+
+  <Text as="p" size="2" color="muted">
+    Don't have an account? <TextLink href="/sign-up">Create one</TextLink>
+  </Text>
+reviewedAt: 2026-10-05
+reviewedAgainstContractHash: "371061b97da3"
+---
+
+## Usage
+
+`TextLink` is the only link style in the system; `Button` has no `link`
+variant. It carries no height or padding, so it sits inside a sentence without
+shifting the line, and inherits the surrounding size unless `size` is set.
+For a link-looking action, give it a `<button type="button">` through
+`asChild` so the control keeps button semantics.
+
+With Next.js, compose the router link through `asChild`:
+
+```tsx
+import NextLink from "next/link"
+
+<TextLink asChild>
+  <NextLink href="/sign-up">Create one</NextLink>
+</TextLink>
+```
+
+The default colour is `primary`, which uses the readable `primary-foreground`
+token. `muted` suits secondary links like "Forgot password?" and darkens on
+hover.

package/knowledge/text.md

@@ -0,0 +1,194 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: text
+  sourceFile: packages/design-system/src/components/text.tsx
+  client: false
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Text
+      kind: component
+      typeText: "ForwardRefExoticComponent<TextProps & RefAttributes<HTMLElement>>"
+    - name: TextAlign
+      kind: type
+    - name: TextAs
+      kind: type
+    - name: TextColor
+      kind: type
+    - name: TextProps
+      kind: type
+    - name: TextSize
+      kind: type
+    - name: TextWeight
+      kind: type
+    - name: TextWrap
+      kind: type
+  primaryExport: Text
+  subcomponents: []
+  props:
+    Text:
+      - name: align
+        type: "\"center\" | \"left\" | \"right\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: as
+        type: TextAs
+        required: false
+        declaredIn: self
+      - name: color
+        type: "\"accent\" | \"default\" | \"destructive\" | \"muted\" | \"primary\" | \"strong\" | \"success\" | \"warning\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: size
+        type: "\"1\" | \"2\" | \"3\" | \"4\" | \"5\" | \"6\" | \"7\" | \"8\" | \"9\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: truncate
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: weight
+        type: "\"bold\" | \"light\" | \"medium\" | \"regular\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: wrap
+        type: TextWrap
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLElement>, \"color\">"
+    - "VariantProps<typeof textVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - "1"
+        - "2"
+        - "3"
+        - "4"
+        - "5"
+        - "6"
+        - "7"
+        - "8"
+        - "9"
+      default: "3"
+      on: Text
+    weight:
+      kind: enum
+      options:
+        - light
+        - regular
+        - medium
+        - bold
+      default: regular
+      on: Text
+    align:
+      kind: enum
+      options:
+        - left
+        - center
+        - right
+      default: null
+      on: Text
+    color:
+      kind: enum
+      options:
+        - default
+        - muted
+        - strong
+        - primary
+        - accent
+        - success
+        - warning
+        - destructive
+      default: default
+      on: Text
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - WRAP_CLASS
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-text--default
+    - exportName: Muted
+      id: components-text--muted
+    - exportName: Scale
+      id: components-text--scale
+  storybookTitle: Components/Text
+  docsId: components-text--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "0cfc9a417441"
+  factsHash: e8cc808f5db3
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The generic polymorphic text primitive - size, weight, color, and alignment as props, rendered as any inline or block tag via as."
+useWhen:
+  - "a piece of text needs size, weight, color, or alignment set through props instead of raw Tailwind classes"
+  - "the same text styling needs to render as a different HTML tag depending on context, via as"
+useInstead:
+  - id: heading
+    when: "the text is a heading; Text cannot render h1-h6"
+  - id: text-link
+    when: "the text is a link"
+  - id: blockquote
+    when: "the content is specifically a longer quotation, not general text"
+  - id: quote
+    when: "the content is a short inline quotation"
+related:
+  - heading
+  - text-link
+  - blockquote
+  - quote
+a11y:
+  notes:
+    - "as picks the rendered tag but not its semantics beyond that tag's native meaning - as=\"label\" renders a real <label>, but Text does not wire htmlFor/id association the way Input's Field does; that association is still the caller's job."
+  radixHandles: false
+pitfalls:
+  - "size is a numeric string scale (\"1\" through \"9\"), unrelated to Button/Input's sm/md/lg scale or Card's padding scale - there is no shared size vocabulary across these primitives."
+  - "size maps to the t-* typography utilities in typography.css (1->t-body-xs, 2->t-body-sm, 3->t-body-md, 4->t-body-lg, 5->t-body-xl, 6->t-h1, 7->t-display-sm, 8->t-display-md, 9->t-display-xl), so it inherits the canonical scale's line-height, weight, and tracking rather than raw text-* utilities. Prefer raw t-* classes with semantic HTML for new hand-authored UI; reach for the size prop only when the polymorphic prop API is actually needed."
+canonicalSnippet: |
+  import { Text } from "@adres/mgda-ui"
+
+  <Text as="p" size="4" weight="medium" color="muted">
+    Track progress across your team.
+  </Text>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "0cfc9a417441"
+---
+
+## Usage
+
+`Text` is the generic, polymorphic text primitive - reach for it any time text
+needs `size`/`weight`/`color`/`align` set through props rather than raw
+Tailwind classes, or needs to render as a different tag (`as="p"`, `"span"`,
+`"label"`, `"strong"`, `"em"`, `"div"`) depending on where it's used. It has no
+semantic meaning of its own beyond whatever tag `as` renders - reach for
+`Blockquote` or `Quote` instead when the content is actually a quotation.
+
+`size` is a numeric string scale (`"1"` through `"9"`, default `"3"`), not the
+`sm`/`md`/`lg` scale used elsewhere in the system - it has its own vocabulary,
+independent of `Button`, `Input`, or `Card`. Each numeric size maps to a `t-*`
+utility class from `typography.css` (the canonical typography scale), so
+`Text` and hand-authored markup using `t-*` classes directly stay visually in
+sync, including brand-specific `t-*` overrides. For new hand-authored UI,
+prefer raw `t-*` classes plus semantic HTML unless the prop-driven API is
+needed.

package/knowledge/thinking-bar.md

@@ -0,0 +1,115 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: thinking-bar
+  sourceFile: packages/design-system/src/components/thinking-bar.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ThinkingBar
+      kind: component
+      typeText: "ForwardRefExoticComponent<ThinkingBarProps & RefAttributes<HTMLDivElement>>"
+    - name: ThinkingBarProps
+      kind: type
+  primaryExport: ThinkingBar
+  subcomponents: []
+  props:
+    ThinkingBar:
+      - name: onClick
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Makes the label a button with a chevron, e.g. to open the reasoning."
+      - name: onStop
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Adds a stop action on the right, e.g. to answer without more thinking."
+      - name: stopLabel
+        type: string
+        required: false
+        declaredIn: self
+      - name: text
+        type: string
+        required: false
+        declaredIn: self
+        doc: "The status, present tense."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onClick\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - thinking-bar
+  dependsOn:
+    internal:
+      - shimmer-text
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-thinkingbar--default
+    - exportName: WithActions
+      id: components-thinkingbar--with-actions
+  storybookTitle: Components/ThinkingBar
+  docsId: components-thinkingbar--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "4d1a4990330b"
+  factsHash: c52823a95ecd
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "One line that says the assistant is thinking: a shimmering status, an optional button to see more, and an optional action to stop and answer now."
+useWhen:
+  - "an assistant is thinking before it answers and one status line is enough"
+  - "people should be able to skip the thinking and get an answer now"
+useInstead:
+  - id: thinking-steps
+    when: "people should see the named steps the assistant is working through"
+  - id: reasoning
+    when: "the model's reasoning text should be readable as it streams"
+related:
+  - shimmer-text
+  - reasoning
+  - thinking-steps
+a11y:
+  notes:
+    - "Without onClick the status is plain text; with it, the label is a button and the chevron is aria-hidden."
+    - "The stop action is a real button named by stopLabel."
+    - "The bar is not a live region; announce thinking and done in a separate polite live region if needed."
+  radixHandles: false
+pitfalls:
+  - "Remove the bar once the answer starts; it is only for the thinking phase."
+  - "Word text in the present tense, such as \"Thinking\" or \"Searching listings\"."
+  - "Pass onStop only when stopping really returns an answer; otherwise leave it out."
+canonicalSnippet: |
+  import { ThinkingBar } from "@adres/mgda-ui"
+
+  {thinking && (
+    <ThinkingBar text="Thinking" onClick={openReasoning} onStop={answerNow} />
+  )}
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "4d1a4990330b"
+---
+
+## Usage
+
+`ThinkingBar` sits where the answer will appear while the assistant thinks.
+`text` is the shimmering status ("Thinking" by default). Pass `onClick` to
+make the status a button with a chevron, for example to open the reasoning,
+and `onStop` to add a dotted-underline action on the right, "Answer now" by
+default or `stopLabel`.
+
+## Anatomy
+
+- `ThinkingBar` - shimmering status (or status button with chevron) and an optional stop action.