@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/media-gallery.md

@@ -0,0 +1,158 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: media-gallery
+  sourceFile: packages/design-system/src/components/media-gallery.tsx
+  client: true
+  category: web-app-media
+  categoryFromBarrel: web-app-media
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Lightbox
+      kind: component
+      typeText: "({ media, index, onIndexChange, onClose, title }: LightboxProps) => Element"
+    - name: LightboxProps
+      kind: type
+    - name: MediaGallery
+      kind: component
+      typeText: "({ media, title, thumbnailCount, className }: MediaGalleryProps) => Element"
+    - name: MediaGalleryProps
+      kind: type
+    - name: MediaItem
+      kind: type
+    - name: MediaKind
+      kind: type
+  primaryExport: MediaGallery
+  subcomponents:
+    - Lightbox
+  props:
+    Lightbox:
+      - name: index
+        type: number
+        required: true
+        declaredIn: self
+      - name: media
+        type: "MediaItem[]"
+        required: true
+        declaredIn: self
+      - name: onClose
+        type: "() => void"
+        required: true
+        declaredIn: self
+      - name: onIndexChange
+        type: "(index: number) => void"
+        required: true
+        declaredIn: self
+      - name: title
+        type: string
+        required: false
+        declaredIn: self
+    MediaGallery:
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+      - name: media
+        type: "MediaItem[]"
+        required: true
+        declaredIn: self
+        doc: "Ordered media. The first item is the hero; the rest fill the thumbnails."
+      - name: thumbnailCount
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Thumbnails shown beside the hero (defaults to 4)."
+      - name: title
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Used for alt text and the lightbox's accessible title."
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - button
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-dialog"
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-mediagallery--default
+  storybookTitle: Components/MediaGallery
+  docsId: components-mediagallery--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "8f72385ce536"
+  factsHash: "9e472898d4c7"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A hero + thumbnail image/video grid that opens a fullscreen, keyboard-navigable lightbox with zoom/pan and inline video playback."
+useWhen:
+  - "showing a browsable set of photos, and optionally video or walkthrough clips, for a single listing or item - a property, product, or unit"
+  - "the user should be able to open any thumbnail into a fullscreen, zoomable, swipeable viewer"
+useInstead:
+  - id: slideshow
+    when: "the images should present one at a time in a single frame - a hero carousel, testimonial rotator - not a browsable grid with a separate fullscreen viewer"
+related:
+  - slideshow
+a11y:
+  notes:
+    - "Lightbox is built on Radix Dialog, so it inherits focus trapping, scroll lock, and Escape-to-close automatically, even though its dark immersive surface looks nothing like a typical dialog."
+    - "title is used for both the hero/thumbnail alt text and the lightbox's visually-hidden accessible title - pass a real, descriptive title (e.g. the property name), not a generic placeholder, since it is the only accessible name a screen reader gets for the whole gallery."
+  keyboard:
+    - "ArrowLeft/ArrowRight navigate between items while the lightbox is open; Escape closes it, inherited from Radix Dialog."
+  radixHandles: true
+pitfalls:
+  - "media[0] is always the hero tile - reordering the array changes which image is large and which are thumbnails; there is no separate hero flag on a MediaItem."
+  - "Only one walkthrough item is surfaced specially: MediaGallery finds the first item with type=\"walkthrough\" and adds a dedicated Walkthrough button over the hero - a second walkthrough item still appears as a normal thumbnail, it does not get its own button."
+  - "thumbnailCount only controls how many thumbnails render beside the hero (default 4); it does not limit how many items are browsable in the lightbox - all of media is always reachable there via the thumbnail strip and arrow keys."
+  - "Lightbox is exported and can be used standalone, but MediaGallery already renders it internally when a thumbnail is clicked - rendering both in the same tree only makes sense when building a custom trigger for the lightbox that bypasses the grid entirely."
+canonicalSnippet: |
+  import { MediaGallery } from "@adres/mgda-ui"
+
+  <MediaGallery
+    title="Unit 2304"
+    media={[
+      { type: "image", src: "/photos/exterior.jpg" },
+      { type: "image", src: "/photos/living-room.jpg" },
+      { type: "walkthrough", src: "/videos/tour.mp4", poster: "/photos/tour-poster.jpg", label: "Walkthrough" },
+    ]}
+  />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "8f72385ce536"
+---
+
+## Usage
+
+`MediaGallery` is for a browsable set of photos, and optionally video or
+walkthrough clips, belonging to a single listing or item - a property unit, a
+product, a place. Reach for `Slideshow` instead when the images should
+present one at a time in a single frame, like a hero carousel or testimonial
+rotator, rather than a grid the user browses into a fullscreen viewer.
+
+`media[0]` is always the large hero tile; the rest fill the thumbnail grid up
+to `thumbnailCount` (default 4), with a "+N Photos" overlay on the last
+visible thumbnail when more remain. Every item in `media` stays reachable in
+the fullscreen `Lightbox` regardless of `thumbnailCount`, via its thumbnail
+strip and arrow-key navigation.
+
+Give at most one item `type="walkthrough"` to get the dedicated "Walkthrough"
+button over the hero - `MediaGallery` only looks for the first one.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `MediaGallery` | The hero + thumbnail grid. Opens `Lightbox` internally when a tile is clicked. |
+| `Lightbox` | The fullscreen viewer. Built on Radix Dialog; handles zoom and pan for images, inline playback for video, and keyboard navigation. Exported separately for standalone use, though `MediaGallery` already renders it for you. |

package/knowledge/message-actions.md

@@ -0,0 +1,175 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: message-actions
+  sourceFile: packages/design-system/src/components/message-actions.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: MessageAction
+      kind: component
+      typeText: "ForwardRefExoticComponent<MessageActionProps & RefAttributes<HTMLButtonElement>>"
+    - name: MessageActionProps
+      kind: type
+    - name: MessageActions
+      kind: component
+      typeText: "ForwardRefExoticComponent<MessageActionsProps & RefAttributes<HTMLDivElement>>"
+    - name: MessageActionsProps
+      kind: type
+    - name: MessageRating
+      kind: type
+  primaryExport: MessageActions
+  subcomponents:
+    - MessageAction
+  props:
+    MessageAction:
+      - 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 tooltip text."
+      - name: pressed
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Renders as a toggle: sets `aria-pressed` and tints the icon."
+    MessageActions:
+      - name: copyText
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Text the Copy action writes to the clipboard. Omit to hide Copy."
+      - name: onCopy
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+      - name: onRate
+        type: "((rating: MessageRating) => void)"
+        required: false
+        declaredIn: self
+        doc: "Called with the clicked rating; the caller decides whether a second click clears it. Omit to hide rating."
+      - name: onRegenerate
+        type: "(() => void)"
+        required: false
+        declaredIn: self
+        doc: "Omit to hide Regenerate."
+      - name: rating
+        type: MessageRating
+        required: false
+        declaredIn: self
+      - name: regenerateDisabled
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: regenerating
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Spins the Regenerate icon and disables it."
+      - name: revealOnHover
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Hides the row until the message is hovered or the row holds focus. Needs a `group/message` ancestor (ChatMessage sets one); touch screens always show it."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    rating:
+      kind: enum
+      options:
+        - up
+        - down
+      default: null
+      on: MessageActions
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - message-actions
+  dependsOn:
+    internal:
+      - button
+      - tooltip
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-messageactions--default
+    - exportName: CopyOnly
+      id: components-messageactions--copy-only
+    - exportName: Regenerating
+      id: components-messageactions--regenerating
+    - exportName: WithExtraAction
+      id: components-messageactions--with-extra-action
+  storybookTitle: Components/MessageActions
+  docsId: components-messageactions--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "904203824709"
+  factsHash: "43769f63eb08"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "The row of icon actions under an assistant message: copy, rate up or down, and regenerate, with room for extra actions."
+useWhen:
+  - "an assistant answer needs copy, thumbs up or down, or regenerate"
+  - "a chat or AI surface needs a consistent icon action with a tooltip under a message"
+useInstead:
+  - id: button-group
+    when: "the actions are labelled buttons, not icon-only message actions"
+related:
+  - tooltip
+  - button
+a11y:
+  notes:
+    - "Every action is an icon-only button named by its label, which is also the tooltip text."
+    - "Ratings are toggles with aria-pressed; pass rating so the pressed state is announced."
+    - "Pass role=\"toolbar\" and an aria-label when the row is the main action bar of an answer."
+    - "With revealOnHover the row still takes keyboard focus and shows while focused; touch screens always show it."
+  radixHandles: true
+pitfalls:
+  - "Tooltips need a TooltipProvider above the row; apps usually mount one in the root layout."
+  - "onRate gets the clicked value, not the next state. Clear the rating yourself when the same value is clicked twice."
+  - "revealOnHover needs a group/message ancestor; ChatMessage provides one. Leave it off on the latest answer so its actions stay visible."
+canonicalSnippet: |
+  import { MessageActions } from "@adres/mgda-ui"
+
+  <MessageActions
+    copyText={answer}
+    rating={rating}
+    onRate={(next) => setRating(rating === next ? null : next)}
+    onRegenerate={regenerate}
+  />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "904203824709"
+---
+
+## Usage
+
+`MessageActions` sits under an assistant message. Each built-in action shows
+only when its prop is set: `copyText` adds Copy (with a short "Copied"
+confirmation), `onRate` adds thumbs up and down, `onRegenerate` adds
+Regenerate. Rating is controlled: keep it in state and decide what a second
+click on the same thumb does. Extra actions such as a version pager or a More
+menu go in `children` after the built-in ones. Buttons are round ghost icons.
+Set `revealOnHover` to hide the row until the message is hovered or the row
+is focused, as on older turns in a long thread.
+
+## Anatomy
+
+- `MessageActions` - the row; renders the built-in actions, then `children`.
+- `MessageAction` - one icon-only ghost button with a tooltip. Set `pressed`
+  to make it a toggle. Use it for extra actions so they match the row.

package/knowledge/nav-sidebar.md

@@ -0,0 +1,225 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: nav-sidebar
+  sourceFile: packages/design-system/src/components/nav-sidebar.tsx
+  client: true
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: NavItem
+      kind: type
+    - name: NavSection
+      kind: type
+    - name: NavSidebar
+      kind: component
+      typeText: "({ sections, currentPath, brand, footer, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange, hideCollapseToggle, expandedItems: expandedProp, defaultExpandedItems, onExpandedItemsChange, LinkComponent, expandS...[truncated]"
+    - name: NavSidebarProps
+      kind: type
+    - name: NavSubItem
+      kind: type
+  primaryExport: NavSidebar
+  subcomponents: []
+  props:
+    NavSidebar:
+      - name: brand
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional brand slot rendered in the sidebar header. Typically a logo with an optional sub-label. Hidden in collapsed mode (the collapse toggle takes the slot instead) - the consumer is responsible for rendering a compact mark separately if needed."
+      - name: collapsed
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: collapseItemLabel
+        type: "((label: string) => string)"
+        required: false
+        declaredIn: self
+      - name: collapseSidebarLabel
+        type: string
+        required: false
+        declaredIn: self
+      - name: currentPath
+        type: string
+        required: true
+        declaredIn: self
+        doc: "The application's current pathname - used to compute active rows and to auto-open the active branch on first render. Pass `usePathname()` from your router."
+      - name: defaultCollapsed
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: defaultExpandedItems
+        type: "Record<string, boolean>"
+        required: false
+        declaredIn: self
+      - name: expandedItems
+        type: "Record<string, boolean>"
+        required: false
+        declaredIn: self
+        doc: "Map of item href → explicit open state. Items not present in the map fall back to auto-open-when-active."
+      - name: expandItemLabel
+        type: "((label: string) => string)"
+        required: false
+        declaredIn: self
+        doc: "Called with `(label)` to format aria-labels for chevron toggle buttons. Defaults to `\"Expand {label}\"` / `\"Collapse {label}\"`."
+      - name: expandSidebarLabel
+        type: string
+        required: false
+        declaredIn: self
+      - name: footer
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional footer slot, typically a `SidebarUserCard`."
+      - name: hideCollapseToggle
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Hide the built-in collapse toggle. Useful when the consumer controls collapse from elsewhere (e.g. a media-query hook on mobile)."
+      - name: LinkComponent
+        type: "ElementType<any, keyof IntrinsicElements>"
+        required: false
+        declaredIn: self
+        doc: "Component used to render navigable rows. Defaults to a plain anchor; pass your router's link component (e.g. Next.js `<Link>`) to get client-side navigation. Receives standard anchor props."
+      - name: onCollapsedChange
+        type: "((collapsed: boolean) => void)"
+        required: false
+        declaredIn: self
+      - name: onExpandedItemsChange
+        type: "((next: Record<string, boolean>) => void)"
+        required: false
+        declaredIn: self
+      - name: sections
+        type: "NavSection[]"
+        required: true
+        declaredIn: self
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - sidebar
+      - tooltip
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-navsidebar--default
+    - exportName: WithCounts
+      id: components-navsidebar--with-counts
+  storybookTitle: Components/NavSidebar
+  docsId: components-navsidebar--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "5c27ead74713"
+  factsHash: "7380688639b1"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "Config-driven app sidebar navigation: active-state routing, nested items, and a collapse toggle, built on Sidebar."
+useWhen:
+  - "the app's primary nav is a persistent left column driven by a route/pathname"
+  - "sections have nested sub-items that should expand under a parent"
+  - "you want a built-in collapse-to-icon-rail toggle instead of building one"
+useInstead:
+  - id: sidebar
+    when: "the built-in routing/active-state/collapse behavior doesn't fit and you need to compose the raw structural pieces yourself"
+  - id: top-nav
+    when: "the app's primary navigation is horizontal, not a side column"
+related:
+  - sidebar
+  - button
+  - tooltip
+composesWith:
+  - sidebar
+  - button
+tokens:
+  - "--card"
+  - "--border"
+  - "--foreground"
+  - "--primary-foreground"
+  - "--muted-foreground"
+  - "--accent"
+  - "--ring"
+a11y:
+  notes:
+    - "Renders a Sidebar underneath, so it inherits the aria-label=\"Primary\" landmark - don't nest a second NavSidebar/Sidebar on the same page."
+    - "Each nav row sets aria-current=\"page\" when active, computed from currentPath, not from the browser's own navigation state."
+    - "The chevron toggle for items with children is a sibling <button>, not part of the link, so it has its own focus stop, aria-expanded, and an aria-label from expandItemLabel/collapseItemLabel."
+    - "In collapsed mode a row shows its label in a Tooltip and names the link with aria-label (label plus count, e.g. \"Drafts, 4 items\"), since the visible text is gone - keep item.label short."
+  requiredProps:
+    - "sections and currentPath are required; currentPath must come from the consumer's router (e.g. usePathname())"
+  keyboard:
+    - "Rows are rendered through LinkComponent (a plain <a> by default), so they take part in tab order and activate with Enter."
+    - "The children-toggle chevron is a real <button>, reachable and activatable with Enter/Space independently of the row's own link."
+  radixHandles: false
+pitfalls:
+  - "currentPath must be supplied by the consumer (e.g. usePathname()) - NavSidebar does not read the URL itself, so a stale or hardcoded value freezes active-state and auto-open detection."
+  - "exact on a NavItem changes active-match from prefix (pathname.startsWith(href + \"/\")) to exact equality - a parent item covering /courses/* needs exact left unset, not exact: true."
+  - "expandedItems/onExpandedItemsChange only overrides items present in the map; items absent from it still fall back to auto-open-when-active, so partially controlling open state is intentional, not a bug."
+  - "dot on an item with children is silently not rendered - the chevron owns that trailing space, so a badge count belongs on the item's own row only when it has no children."
+  - "count follows the same rule: it renders on items without children, is hidden at 0, and moves into the tooltip (\"Drafts · 4\") when the sidebar is collapsed."
+subcomponentNotes:
+  NavItem: "One top-level entry: href, label, icon, optional exact, dot, count, and children (NavSubItem[]) for a nested submenu."
+  NavSection: "A group of NavItems with an optional label, rendered as a small caption above the group while expanded and hidden when collapsed. Every section after the first also gets a divider."
+  NavSubItem: "A nested row under an item with children: href, label, and an optional trailing count."
+rtl: "Inherits Sidebar's logical properties; the chevron's rotation includes an explicit rtl: variant (-rotate-90 rtl:rotate-90) so it points the correct direction when the layout mirrors."
+canonicalSnippet: |
+  import { NavSidebar } from "@adres/mgda-ui"
+  import Link from "next/link"
+  import { usePathname } from "next/navigation"
+  import { Home, Book } from "lucide-react"
+
+  <NavSidebar
+    LinkComponent={Link}
+    currentPath={usePathname()}
+    brand={<img src="/logo.svg" alt="Acme" className="ax:h-6" />}
+    sections={[
+      {
+        items: [
+          { href: "/dashboard", label: "Dashboard", icon: <Home /> },
+          {
+            href: "/courses",
+            label: "Courses",
+            icon: <Book />,
+            children: [
+              { href: "/courses", label: "All courses" },
+              { href: "/courses/categories", label: "Categories" },
+            ],
+          },
+        ],
+      },
+    ]}
+  />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "5c27ead74713"
+---
+
+## Usage
+
+NavSidebar is the opinionated, route-aware layer on top of `Sidebar`: it takes
+a declarative `sections`/`items` config plus the current pathname, and
+computes active state, auto-opens the branch containing the active route, and
+renders a chevron toggle for items with nested children. It also owns the
+collapse-to-icon-rail toggle button that `Sidebar` itself leaves to the
+consumer.
+
+Collapse state and per-item open overrides can be either controlled (pass
+`collapsed`/`expandedItems` plus their `onChange` callbacks) or left
+uncontrolled (the component manages its own state, seeded from
+`defaultCollapsed`/`defaultExpandedItems`). Reach for the controlled form only
+when something outside the component needs to react to or drive that state -
+for example, collapsing on a media query.
+
+Pass a router's link component via `LinkComponent` (defaults to a plain `<a>`)
+to get client-side navigation instead of full page loads.