@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/entity-header.md

@@ -0,0 +1,166 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: entity-header
+  sourceFile: packages/design-system/src/components/entity-header.tsx
+  client: false
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: EntityHeader
+      kind: component
+      typeText: "ForwardRefExoticComponent<EntityHeaderProps & RefAttributes<HTMLDivElement>>"
+    - name: EntityHeaderProps
+      kind: type
+    - name: EntityHeaderSize
+      kind: type
+    - name: entityHeaderVariants
+      kind: variants
+      typeText: "TVReturnType<{ size: { md: { mark: string; }; lg: { mark: string; }; }; }, { root: string; identity: string; mark: string; text: string; subtitle: string; aside: string; }, undefined, { size: { md: { mark: string; }; lg:...[truncated]"
+    - name: entityInitials
+      kind: function
+      typeText: "(name: string) => string"
+  primaryExport: EntityHeader
+  subcomponents: []
+  props:
+    EntityHeader:
+      - name: actions
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Actions such as Edit or Contact, aligned with the details."
+      - name: as
+        type: HeadingAs
+        required: false
+        declaredIn: self
+        doc: "Heading level for the name. Defaults to `h2`."
+      - name: details
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Key facts beside the identity, typically `<DataList orientation=\"grid\">`."
+      - name: logo
+        type: "{ src: string; alt: string; }"
+        required: false
+        declaredIn: self
+        doc: "Logo image. Without it the mark shows initials from `name`."
+      - name: name
+        type: string
+        required: true
+        declaredIn: self
+        doc: "Organisation, company or property name."
+      - name: size
+        type: "\"lg\" | \"md\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: subtitle
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Secondary line, e.g. the legal name or a registration number."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"title\">"
+    - "VariantProps<typeof entityHeaderVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - md
+        - lg
+      default: lg
+      on: EntityHeader
+  variantSource: tv
+  compoundVariants: []
+  sizeMaps:
+    - NAME_SIZE
+  dataSlots:
+    - entity-header
+  dependsOn:
+    internal:
+      - heading
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+      - tailwind-variants
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-entityheader--default
+    - exportName: WithDetails
+      id: components-entityheader--with-details
+    - exportName: WithActions
+      id: components-entityheader--with-actions
+    - exportName: Medium
+      id: components-entityheader--medium
+  storybookTitle: Components/EntityHeader
+  docsId: components-entityheader--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: caa4ffb0e7be
+  factsHash: "1aa6f809d55f"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "The identity block for an organisation, brokerage or property: a logo or initials mark, the name as a heading, a secondary line, and slots for key details and actions."
+useWhen:
+  - "the top of a company, brokerage or agency page or dashboard"
+  - "showing who a record belongs to with its key facts (licences, registration, contact)"
+useInstead:
+  - id: page-header
+    when: "the page title is a task or section name rather than an organisation's identity"
+  - id: avatar
+    when: "only a small identity mark is needed, e.g. in a list row"
+related:
+  - data-list
+  - page-header
+  - avatar
+a11y:
+  notes:
+    - "The name renders as a real heading; set as to fit the page outline (h2 by default, h1 when it is the page title)."
+    - "Initials are decorative (aria-hidden) because the heading already names the organisation; a logo keeps its alt text."
+  radixHandles: false
+pitfalls:
+  - "Pass a logo with meaningful alt text, or omit it to fall back to initials; do not pass an empty alt for a logo that is the only visible name."
+  - "details is a free slot; use DataList orientation=\"grid\" for licence-style facts so they align in columns."
+  - "Initials take the first letter of the first two words; for names where that misleads, pass a logo."
+canonicalSnippet: |
+  import { EntityHeader } from "@adres/mgda-ui"
+
+  <EntityHeader
+    name="Remax RealEstate"
+    subtitle="Remax Real Estate Brokerage L.L.C."
+    details={brokerageDetails}
+  />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: caa4ffb0e7be
+---
+
+## Usage
+
+`EntityHeader` names an organisation and shows its key facts. The mark is the
+logo when given, otherwise initials from the name. `size` is `lg` by default
+(56px mark, `h2`-sized name) or `md` (48px, `h3`-sized). From `lg` up the
+identity and the details/actions sit in one row, bottom-aligned; below that
+they stack.
+
+Pair it with a grid `DataList` for licence-style details:
+
+```tsx
+<EntityHeader
+  name="Remax RealEstate"
+  subtitle="Remax Real Estate Brokerage L.L.C."
+  details={
+    <DataList orientation="grid" columns={4} size="sm">
+      <DataListItem>
+        <DataListLabel>Trade licence</DataListLabel>
+        <DataListValue>2120561384412A</DataListValue>
+      </DataListItem>
+    </DataList>
+  }
+/>
+```

package/knowledge/feature-grid.md

@@ -0,0 +1,120 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: feature-grid
+  sourceFile: packages/design-system/src/components/feature-grid.tsx
+  client: true
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Feature
+      kind: type
+    - name: FeatureGrid
+      kind: component
+      typeText: "ForwardRefExoticComponent<FeatureGridProps & RefAttributes<HTMLElement>>"
+    - name: FeatureGridProps
+      kind: type
+  primaryExport: FeatureGrid
+  subcomponents: []
+  props:
+    FeatureGrid:
+      - name: columns
+        type: "2 | 3 | 4"
+        required: false
+        declaredIn: self
+        doc: "Number of columns at the largest breakpoint. Default 3."
+      - name: description
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: eyebrow
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: features
+        type: "Feature[]"
+        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:
+      - motion/react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-featuregrid--default
+  storybookTitle: Components/FeatureGrid
+  docsId: components-featuregrid--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "7a20bb0c641d"
+  factsHash: "31fa73977abb"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A marketing feature showcase - an optional eyebrow/title/description header above a responsive grid of icon, title, and description cards, with scroll-triggered stagger animation."
+useWhen:
+  - "showcasing several distinct product features or benefits together, each with its own icon, title, and description"
+useInstead:
+  - id: cta
+    when: "the section should drive toward one action rather than showcase several features side by side"
+related:
+  - cta
+a11y:
+  notes:
+    - "Renders a real ul/li list for the features and an h2 for the section title when provided - the semantic list conveys a set of related items to assistive tech even without visible bullets."
+    - "Feature icons are decorative by convention here - the component adds no aria-hidden itself, so pass an icon element that is already inert (most icon libraries default to this) rather than one carrying its own accessible name that would compete with the feature's title."
+  radixHandles: false
+pitfalls:
+  - "The header block (eyebrow/title/description) only renders at all when at least one of the three is provided - omitting all three does not leave empty space, it removes the block's margin too, so the grid sits flush at the top."
+  - "columns only changes the desktop breakpoint's column count - tablet is always a fixed 2-column layout and mobile is always 1, regardless of columns."
+  - "The stagger entrance animation runs on scroll-into-view, not on mount - a FeatureGrid already in the viewport on page load still needs to cross the configured viewport margin to trigger, so it can appear to animate oddly if only partially visible at load."
+canonicalSnippet: |
+  import { FeatureGrid } from "@adres/mgda-ui"
+
+  const sectionTitle = "Everything you need"
+  const items = [
+    { title: "Fast", description: "Optimized for speed." },
+    { title: "Secure", description: "Encrypted by default." },
+    { title: "Reliable", description: "99.9% uptime." },
+  ]
+
+  <FeatureGrid title={sectionTitle} columns={3} features={items} />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "7a20bb0c641d"
+---
+
+## Usage
+
+`FeatureGrid` showcases several distinct product features or benefits
+together, each with its own icon, title, and description, above an optional
+eyebrow/title/description section header. Reach for `CTA` instead when the
+section should drive toward one action rather than showcase several
+features side by side.
+
+`columns` (2/3/4, default 3) only changes the desktop breakpoint's column
+count - the grid is always 1 column on mobile and 2 on tablet regardless of
+this prop.
+
+The header block only renders when at least one of `eyebrow`/`title`/
+`description` is provided - omit all three for a bare grid with no leading
+margin, rather than passing empty strings.

package/knowledge/feedback-bar.md

@@ -0,0 +1,127 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: feedback-bar
+  sourceFile: packages/design-system/src/components/feedback-bar.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: FeedbackBar
+      kind: component
+      typeText: "ForwardRefExoticComponent<FeedbackBarProps & RefAttributes<HTMLDivElement>>"
+    - name: FeedbackBarProps
+      kind: type
+  primaryExport: FeedbackBar
+  subcomponents: []
+  props:
+    FeedbackBar:
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional mark before the title, such as the assistant's logo."
+      - name: onClose
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Shows the close button. Hide the bar yourself when it fires."
+      - name: onHelpful
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: onNotHelpful
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: title
+        type: string
+        required: true
+        declaredIn: self
+        doc: "The question, e.g. \"Was this helpful?\". Also names the group."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - feedback-bar
+  dependsOn:
+    internal:
+      - button
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-feedbackbar--default
+    - exportName: WithIcon
+      id: components-feedbackbar--with-icon
+    - exportName: WithoutClose
+      id: components-feedbackbar--without-close
+  storybookTitle: Components/FeedbackBar
+  docsId: components-feedbackbar--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: ee4aafc6ae23
+  factsHash: b6acfc13fd70
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "A compact \"Was this helpful?\" prompt: a title with an optional icon, thumbs up and down, and an optional close."
+useWhen:
+  - "one quick helpful or not question for a whole conversation, help article or page"
+  - "a dismissible feedback prompt that should not compete with the content"
+useInstead:
+  - id: answer-actions
+    when: "each assistant answer needs copy, rating with reasons, regenerate or report"
+  - id: message-actions
+    when: "only copy, thumbs and regenerate are needed under each message"
+related:
+  - answer-actions
+  - message-actions
+a11y:
+  notes:
+    - "The bar is a group named by its title, so the question is read before the buttons."
+    - "Thumbs are labelled \"Helpful\" and \"Not helpful\"; close is labelled \"Close\"."
+    - "The icon is decorative and aria-hidden."
+  radixHandles: false
+pitfalls:
+  - "The bar keeps no state; hide it or swap in a thank-you from onHelpful, onNotHelpful and onClose."
+  - "The close button only appears when onClose is passed."
+  - "Show it once per conversation or page, not under every answer."
+canonicalSnippet: |
+  import { FeedbackBar } from "@adres/mgda-ui"
+
+  {showFeedback && (
+    <FeedbackBar
+      title="Was this helpful?"
+      onHelpful={() => rate("up")}
+      onNotHelpful={() => rate("down")}
+      onClose={() => setShowFeedback(false)}
+    />
+  )}
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: ee4aafc6ae23
+---
+
+## Usage
+
+`FeedbackBar` asks one question, usually "Was this helpful?", with thumbs up
+and down. Put it once at the end of a conversation, help article or page.
+Pass `icon` for a mark before the title, such as the assistant's logo, and
+`onClose` to add a close button behind a divider.
+
+The bar keeps no state. Handle `onHelpful` and `onNotHelpful` to record the
+answer, then hide the bar or replace it with a thank-you line.
+
+## Anatomy
+
+- `FeedbackBar` - bordered bar: optional icon and title, thumbs up and down, optional close.

package/knowledge/footer.md

@@ -0,0 +1,116 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: footer
+  sourceFile: packages/design-system/src/components/footer.tsx
+  client: false
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Footer
+      kind: component
+      typeText: "({ className, brand, tagline, columns, legal, social, ...props }: FooterProps) => Element"
+    - name: FooterColumn
+      kind: type
+    - name: FooterLink
+      kind: type
+    - name: FooterProps
+      kind: type
+  primaryExport: Footer
+  subcomponents: []
+  props:
+    Footer:
+      - name: brand
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: columns
+        type: "FooterColumn[]"
+        required: false
+        declaredIn: self
+      - name: legal
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: social
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: tagline
+        type: ReactNode
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "React.HTMLAttributes<HTMLElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-footer--default
+  storybookTitle: Components/Footer
+  docsId: components-footer--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: e9fe69ab9f52
+  factsHash: "9f015cae8e69"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The page-level footer: an optional brand/tagline/social block, a responsive column grid of link groups, and a legal line."
+useWhen:
+  - "every marketing (and typically app-level) page needs a consistent closing footer with navigation links, brand, and legal text"
+related:
+  - logo-cloud
+a11y:
+  notes:
+    - "columns renders each link as a real anchor and each column as its own list - no extra ARIA is needed for the link groups themselves, but give the footer's own landmark role thought: a footer at the page root is an automatic contentinfo landmark, one nested inside another sectioning element is not."
+  radixHandles: false
+pitfalls:
+  - "The grid only switches to the multi-column brand+links layout when columns is a non-empty array - passing an empty array, or omitting it, collapses to a single column, silently dropping the intended side-by-side layout rather than rendering empty column slots."
+  - "The column grid caps visually at 4 columns via a CSS variable - passing more than 4 FooterColumn entries still renders all of them, just wrapped or compressed rather than each getting its own dedicated grid track."
+  - "legal and social are both freeform ReactNode with no built-in structure - legal is typically a copyright line, social is typically a row of icon links, but the component enforces neither; get the semantics (real links, accessible icon labels) right in what is passed."
+canonicalSnippet: |
+  import { Footer } from "@adres/mgda-ui"
+
+  const columns = [
+    { heading: "Product", links: [{ label: "Features", href: "/features" }] },
+    { heading: "Company", links: [{ label: "About", href: "/about" }] },
+  ]
+  const legalText = "(c) 2026 Adres. All rights reserved."
+
+  <Footer columns={columns} legal={legalText} />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: e9fe69ab9f52
+---
+
+## Usage
+
+`Footer` is the page-level closing footer - an optional brand/tagline/social
+block on the left, a responsive grid of link-group columns, and a legal
+line underneath. Reach for `LogoCloud` separately, often placed just above
+or inside a footer, when the goal is showing partner or customer logos as a
+trust signal, not navigation links.
+
+The multi-column layout only activates when `columns` is a non-empty array -
+an empty or omitted `columns` collapses to a single column with just the
+brand block, rather than reserving empty grid space. The column count caps
+visually at 4 via a CSS variable, so a fifth or later column still renders,
+just without its own dedicated grid track.
+
+`legal` and `social` are both freeform `ReactNode` with no enforced
+structure - typically a copyright string and a row of icon links
+respectively, but get their real semantics (actual links, accessible icon
+labels) right in what is passed, since the component adds none itself.