@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/cta.md

@@ -0,0 +1,118 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: cta
+  sourceFile: packages/design-system/src/components/cta.tsx
+  client: true
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: CTA
+      kind: component
+      typeText: "ForwardRefExoticComponent<CTAProps & RefAttributes<HTMLElement>>"
+    - name: CTAProps
+      kind: type
+  primaryExport: CTA
+  subcomponents: []
+  props:
+    CTA:
+      - name: actions
+        type: ReactNode
+        required: true
+        declaredIn: self
+      - name: description
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: emphasis
+        type: "\"primary\" | \"subtle\""
+        required: false
+        declaredIn: self
+        doc: "Visual emphasis - 'subtle' uses muted surface, 'primary' uses brand surface."
+      - name: title
+        type: ReactNode
+        required: true
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLElement>, \"title\">"
+  variants:
+    emphasis:
+      kind: enum
+      options:
+        - primary
+        - subtle
+      default: subtle
+      on: CTA
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-cta--default
+    - exportName: Primary
+      id: components-cta--primary
+  storybookTitle: Components/CTA
+  docsId: components-cta--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "03902c637b57"
+  factsHash: "0a48dcfc8d34"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A closing call-to-action section for marketing pages - a centered headline, optional description, and an action row, in two emphasis levels."
+useWhen:
+  - "closing out a marketing page with one clear next action - \"Get started\", \"Book a demo\", a final conversion push"
+useInstead:
+  - id: feature-grid
+    when: "the section should showcase several product features, not drive toward one action"
+related:
+  - feature-grid
+a11y:
+  notes:
+    - "Renders a real section with an h2 title - it composes into the page's heading hierarchy, so ensure only one h1 precedes it and this genuinely reads as a section-level heading."
+    - "actions is untyped ReactNode - the component adds no button semantics itself, so whatever is passed, typically one or more Button components, needs its own real interactive markup and accessible naming."
+  radixHandles: false
+pitfalls:
+  - "emphasis=\"primary\" swaps to the brand surface and inverts foreground text automatically - passing your own text color classes via className on children can fight this inversion rather than complementing it."
+  - "title accepts ReactNode, not just a string, but the component renders it directly inside an h2 with no wrapping - passing block-level content there can produce invalid heading markup."
+  - "There is no built-in max-width constraint on actions beyond flex-wrap - a long list of action buttons wraps rather than overflowing, but a page with many CTAs should still keep this section to one, maybe two, clear actions for it to read as intended."
+canonicalSnippet: |
+  import { Button, CTA } from "@adres/mgda-ui"
+
+  const heading = "Ready to get started?"
+
+  <CTA
+    title={heading}
+    emphasis="primary"
+    actions={<Button variant="secondary">Book a demo</Button>}
+  />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "03902c637b57"
+---
+
+## Usage
+
+`CTA` is a closing call-to-action section for marketing pages - a centered
+headline, optional supporting text, and an action row, meant to drive toward
+one clear next step. Reach for `FeatureGrid` instead when the section should
+showcase several product features rather than push toward one action.
+
+`emphasis="subtle"` (default) uses a muted surface for a CTA that sits
+mid-page among other sections; `emphasis="primary"` uses the brand surface
+with inverted foreground text for a stronger, usually page-closing, moment.
+
+`actions` is untyped `ReactNode` - the component adds no button semantics of
+its own, so pass real interactive elements, typically one or two `Button`s,
+rather than plain text or links without their own accessible markup.

package/knowledge/data-list.md

@@ -0,0 +1,173 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: data-list
+  sourceFile: packages/design-system/src/components/data-list.tsx
+  client: true
+  category: web-app-data
+  categoryFromBarrel: web-app-data
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: DataList
+      kind: component
+      typeText: "ForwardRefExoticComponent<DataListProps & RefAttributes<HTMLDListElement>>"
+    - name: DataListColumns
+      kind: type
+    - name: DataListItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: DataListLabel
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement>>"
+    - name: DataListOrientation
+      kind: type
+    - name: DataListProps
+      kind: type
+    - name: DataListSize
+      kind: type
+    - name: DataListValue
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement>>"
+  primaryExport: DataList
+  subcomponents:
+    - DataListItem
+    - DataListLabel
+    - DataListValue
+  props:
+    DataList:
+      - name: columns
+        type: DataListColumns
+        required: false
+        declaredIn: self
+        doc: "Columns from `sm` up when `orientation=\"grid\"`; two below `sm`."
+      - name: orientation
+        type: DataListOrientation
+        required: false
+        declaredIn: self
+        doc: "`grid` lays items out in columns, label above value, without dividers - for short facts such as licence numbers or key dates."
+      - name: size
+        type: DataListSize
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDListElement>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: DataList
+    orientation:
+      kind: enum
+      options:
+        - grid
+        - horizontal
+        - vertical
+      default: horizontal
+      on: DataList
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - GRID_COLUMNS
+    - ITEM_GAP
+    - ITEM_GAP_X
+    - ITEM_PADDING
+    - LABEL_MIN_WIDTH
+    - LABEL_TEXT
+    - VALUE_TEXT
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts:
+    - name: DataListContext
+      type: DataListContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-datalist--default
+    - exportName: Grid
+      id: components-datalist--grid
+  storybookTitle: Components/DataList
+  docsId: components-datalist--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "767a2e901e81"
+  factsHash: e022b7c1ee6d
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A semantic label/value summary list (dl/dt/dd), for a flat set of fields - not a table, not expandable sections."
+useWhen:
+  - "showing a flat set of read-only label/value pairs - a record summary, metadata panel, review-before-submit screen"
+useInstead:
+  - id: table
+    when: "there are multiple comparable records with the same fields, not a single record's fields"
+  - id: accordion
+    when: "any of the fields need to expand or collapse rather than always being visible"
+related:
+  - table
+  - accordion
+a11y:
+  notes:
+    - "Uses real dl/dt/dd elements, so the label/value relationship is conveyed to assistive tech natively - no extra ARIA is needed."
+  radixHandles: false
+pitfalls:
+  - "orientation=\"horizontal\" (default) is itself responsive - it stacks label above value on mobile and only becomes a side-by-side row from the sm breakpoint up. orientation=\"vertical\" always stacks, at every width."
+  - "orientation=\"grid\" lays short facts in columns (columns 2, 3 or 4 from sm up; always two below sm), label above value, with no dividers. Use it for licence numbers or key dates beside a header; long values belong in the default list."
+  - "columns only applies to orientation=\"grid\"; on the other orientations it is ignored."
+  - "size drives five separate maps at once (item padding, label/value gap, label min-width, label and value type scale) - the md size intentionally uses a non-token half-step (py-2.5) specifically to match Table's md row height, so do not round it to a token value when customizing."
+  - "Horizontal rows share one subgrid track, so the label column sizes to the widest label across every row. min-width applies from sm up only as a floor when every label is short; a long label (e.g. a translated string) can still grow past it rather than wrap or clip."
+canonicalSnippet: |
+  import { DataList, DataListItem, DataListLabel, DataListValue } from "@adres/mgda-ui"
+
+  <DataList size="md">
+    <DataListItem>
+      <DataListLabel>Status</DataListLabel>
+      <DataListValue>Active</DataListValue>
+    </DataListItem>
+    <DataListItem>
+      <DataListLabel>Created</DataListLabel>
+      <DataListValue>Jan 12, 2026</DataListValue>
+    </DataListItem>
+  </DataList>
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "767a2e901e81"
+---
+
+## Usage
+
+`DataList` is for a flat set of read-only label/value pairs describing one
+record - a summary panel, metadata block, or review screen. Reach for `Table`
+instead once there are multiple records sharing the same fields, and
+`Accordion` if any field's value needs to expand or collapse rather than
+always being visible.
+
+`orientation="horizontal"` (default) is itself responsive: label above value
+on mobile, a baseline-aligned row from the `sm` breakpoint up. Use
+`orientation="vertical"` to always stack, at every width, regardless of
+screen size.
+
+`size` scales padding, the label/value gap, the label's minimum width (so
+short labels form an aligned column without clipping a long one), and both
+elements' type together - set it once on `DataList` rather than on the
+sub-components.
+
+## Anatomy
+
+`DataList` renders real semantic `<dl>`/`<dt>`/`<dd>` elements throughout.
+
+| Part | Role |
+| --- | --- |
+| `DataList` | The `<dl>` root. Owns `size` and `orientation`, shared via context. |
+| `DataListItem` | One row: a `<div>` grouping one label and its value. |
+| `DataListLabel` | The `<dt>`. Gets a minimum width in horizontal orientation so a column of labels aligns. |
+| `DataListValue` | The `<dd>`. |

package/knowledge/data-table.md

@@ -0,0 +1,220 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: data-table
+  sourceFile: packages/design-system/src/components/data-table.tsx
+  client: true
+  category: web-app-data
+  categoryFromBarrel: web-app-data
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ColumnDef
+      kind: type
+    - name: DataTable
+      kind: component
+      typeParameters:
+        - T
+      typeText: "<T>({ columns, data, size, className, rowKey, rowClassName, onRowClick, emptyMessage, headless, ...props }: DataTableProps<T>) => Element"
+    - name: DataTableAlign
+      kind: type
+    - name: DataTableProps
+      kind: type
+    - name: DataTableSize
+      kind: type
+    - name: rowStyle
+      kind: const
+      typeText: "{ readonly title: \"ax:font-medium ax:text-foreground-strong\"; readonly default: \"ax:font-normal ax:text-foreground\"; readonly muted: \"ax:font-normal ax:text-muted-foreground\"; }"
+    - name: SortDirection
+      kind: type
+  primaryExport: DataTable
+  subcomponents: []
+  props:
+    DataTable:
+      - name: columns
+        type: "ColumnDef<T>[]"
+        required: true
+        declaredIn: self
+      - name: data
+        type: "T[]"
+        required: true
+        declaredIn: self
+      - name: emptyMessage
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Shown when data is empty."
+      - name: headless
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Hide the header row entirely."
+      - name: onRowClick
+        type: "((row: T, index: number) => void)"
+        required: false
+        declaredIn: self
+        doc: "Row click handler. When provided, rows become clickable (cursor + role). Interactive children (buttons, links, menu triggers) should stopPropagation if they need to bypass the row click."
+      - name: rowClassName
+        type: "((row: T, index: number) => string | undefined)"
+        required: false
+        declaredIn: self
+        doc: "Per-row className. Lets callers visually mark rows (placeholders, status-specific tinting, etc.)."
+      - name: rowKey
+        type: "((row: T, index: number) => string | number)"
+        required: false
+        declaredIn: self
+        doc: "Key-accessor for React list rendering. Defaults to row index."
+      - name: size
+        type: DataTableSize
+        required: false
+        declaredIn: self
+        doc: "Visual density. Matches the Table component's size scale."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"onClick\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: DataTable
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - CELL_PADDING
+    - CELL_TYPOGRAPHY
+  dataSlots:
+    - data-table
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-datatable--default
+  storybookTitle: Components/DataTable
+  docsId: components-datatable--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: d808fb84c598
+  factsHash: ce8594f5a4f4
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A column-driven table with built-in client-side sorting, density sizes and an empty state."
+useWhen:
+  - "rendering rows of records where columns are defined in data, not markup"
+  - "you want click-to-sort without wiring the state yourself"
+  - "rows should be clickable to open a detail view"
+useInstead:
+  - id: table
+    when: "you want to write the markup by hand, or need row spans, grouped headers, or a footer"
+  - id: data-list
+    when: "you are showing label and value pairs for a single record rather than many rows"
+  - id: empty-state
+    when: "the whole surface has no data and deserves a full illustration rather than one line in a cell"
+related:
+  - table
+  - data-list
+  - empty-state
+  - skeleton
+composesWith:
+  - badge
+  - button
+  - dropdown-menu
+tokens:
+  - "--card"
+  - "--border"
+  - "--muted"
+  - "--muted-foreground"
+  - "--foreground"
+  - "--foreground-strong"
+a11y:
+  notes:
+    - "aria-sort is set on the sorted header, so assistive technology reports the direction correctly."
+    - "Sortable headers are th elements with an onClick, not buttons, so sorting cannot be triggered from the keyboard. This is a known gap in the component, not something a caller can fix by passing a prop."
+    - "Clickable rows have the same problem: onRowClick attaches to the tr with a pointer cursor but no role, tabIndex or key handler, so the interaction is mouse-only. Where keyboard access matters, put a real Button or link inside a cell instead of relying on onRowClick."
+  requiredProps:
+    - "columns and data, both required"
+  keyboard:
+    - "None for sorting or row activation, see the notes above. Interactive elements you place inside cells keep their own keyboard behaviour."
+  radixHandles: false
+pitfalls:
+  - "Sorting stringifies whatever accessor returns: String(accessor(row)) compared with localeCompare. If an accessor returns JSX, every value becomes \"[object Object]\" and the column silently does not sort. Give a sortable column an accessor that returns a string or number, and render the JSX in a separate non-sortable column."
+  - "Because the comparison is string-based, dates sort lexicographically. \"10 Jan\" lands before \"2 Feb\". Sort on an ISO date string or a timestamp instead."
+  - "Sort state is internal, so it resets whenever the component remounts and cannot be controlled, read, or initialised from outside."
+  - "Sorting is client-side over the data array you pass, so it only ever orders the current page. Combined with server pagination it sorts within the page and looks broken."
+  - "The click sequence is tri-state: ascending, then descending, then back to unsorted original order. The third click is easy to mistake for a bug."
+  - "onClick is deliberately omitted from the props type. Use onRowClick for rows, and note that interactive children need stopPropagation to avoid also firing it."
+  - "headless hides the header row, which also removes the only sorting affordance."
+rtl: "Good. Column align uses logical start and end, which flip correctly, and ColumnDef.align documents that. Only align: center is direction-neutral."
+brandNotes: "The shell uses --card with a --border ring and a --muted header, so brand changes flow through without touching the component. The exported rowStyle map carries weight and colour only, deliberately no font size, so density stays owned by the size prop."
+canonicalSnippet: |
+  import { DataTable, rowStyle, type ColumnDef } from "@adres/mgda-ui"
+
+  type Unit = { id: string; name: string; sqft: number }
+
+  const columns: ColumnDef<Unit>[] = [
+    { key: "name", header: "Unit", accessor: (u) => u.name, sortable: true },
+    { key: "sqft", header: "Area", accessor: (u) => u.sqft, sortable: true, align: "end" },
+  ]
+
+  <DataTable
+    columns={columns}
+    data={units}
+    size="md"
+    rowKey={(u) => u.id}
+    onRowClick={(u) => open(u.id)}
+    emptyMessage="No units yet."
+  />
+reviewedAt: 2026-09-29
+reviewedAgainstContractHash: d808fb84c598
+---
+
+## Usage
+
+DataTable trades flexibility for speed: you describe columns as data and get sorting,
+density, an empty state and clickable rows without writing markup. When you need
+control over the markup itself, drop to `Table`.
+
+It is generic over the row type, so `ColumnDef<T>` gives you a typed `accessor` and
+`onRowClick` receives the row, not an index. Keep the generic inferred by typing the
+column array rather than casting inside the accessors.
+
+### The sorting trap
+
+This is the single most important thing to know about this component. Sorting
+compares `String(accessor(row))`, so an accessor that returns JSX produces
+`"[object Object]"` for every row and the column quietly refuses to order.
+
+```tsx
+// Broken: sorts by "[object Object]"
+{ key: "status", header: "Status", sortable: true,
+  accessor: (u) => <Badge>{u.status}</Badge> }
+
+// Correct: sort on the value, render the chip in its own column
+{ key: "status", header: "Status", sortable: true, accessor: (u) => u.status }
+```
+
+The same reasoning applies to dates and any formatted number: sort on the raw value,
+present the formatted one.
+
+### Density and row text
+
+`size` sets cell padding and cell typography together, matching `Table`'s scale so the
+two components stay visually in sync. Use the exported `rowStyle` map inside accessors
+to vary weight and colour, never size:
+
+```tsx
+accessor: (u) => <span className={rowStyle.muted}>{u.ref}</span>
+```
+
+`rowStyle` deliberately carries no font size, so the table's `size` prop stays the
+single source of density.