@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/tooltip.md

@@ -0,0 +1,120 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: tooltip
+  sourceFile: packages/design-system/src/components/tooltip.tsx
+  client: true
+  category: web-app-overlays
+  categoryFromBarrel: web-app-overlays
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Tooltip
+      kind: component
+      radixSource: "@radix-ui/react-tooltip#Root"
+      typeText: "FC<TooltipProps>"
+    - name: TooltipContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<TooltipContentProps & RefAttributes<HTMLDivElement>>"
+    - name: TooltipContentProps
+      kind: type
+    - name: TooltipProvider
+      kind: component
+      radixSource: "@radix-ui/react-tooltip#Provider"
+      typeText: "FC<TooltipProviderProps>"
+    - name: TooltipTrigger
+      kind: component
+      radixSource: "@radix-ui/react-tooltip#Trigger"
+      typeText: "ForwardRefExoticComponent<TooltipTriggerProps & RefAttributes<HTMLButtonElement>>"
+  primaryExport: Tooltip
+  subcomponents:
+    - TooltipContent
+    - TooltipProvider
+    - TooltipTrigger
+  props: {}
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-tooltip"
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-tooltip--default
+  storybookTitle: Components/Tooltip
+  docsId: components-tooltip--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "31db1aa44d25"
+  factsHash: "24dfe7587e75"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A hover or focus-triggered label with no interactive content, built on Radix Tooltip."
+useWhen:
+  - "adding a short, supplementary label that appears on hover or keyboard focus - an icon button's name, a truncated value's full text"
+useInstead:
+  - id: popover
+    when: "the content needs to be interactive (buttons, links, a form) or triggered by a click"
+  - id: dropdown-menu
+    when: "the content is a list of selectable actions"
+related:
+  - popover
+a11y:
+  notes:
+    - "TooltipProvider must wrap the app (or at least the tooltip's subtree) once - it is not per-Tooltip, and a Tooltip will not work without an ancestor TooltipProvider."
+    - "Wrap the real trigger element with TooltipTrigger asChild the same way Popover/DropdownMenu do, so the tooltip's hover and focus handling attaches to the actual interactive element."
+    - "A tooltip is not a substitute for a real accessible name - an icon-only button still needs its own aria-label; the tooltip is supplementary, sighted-hover context, not the only source of the name for assistive tech."
+  keyboard:
+    - "Shows on keyboard focus as well as hover, and Escape dismisses it - unlike a pure CSS :hover tooltip, so keyboard-only users can still see it."
+  radixHandles: true
+pitfalls:
+  - "TooltipContent is a passive label, not a place for interactive elements - putting a button or link inside a tooltip is a misuse; reach for Popover instead."
+  - "Content shown must stay genuinely short - the intentionally fast (100ms) show and hide animation and single-line-oriented styling assume a brief label, not a paragraph."
+  - "A missing TooltipProvider ancestor is a common integration bug - the Tooltip renders without erroring but never actually shows, since Radix's tooltip context has no default provider."
+canonicalSnippet: |
+  import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@adres/mgda-ui"
+
+  <TooltipProvider>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Hover me</Button>
+      </TooltipTrigger>
+      <TooltipContent>Helpful tooltip text</TooltipContent>
+    </Tooltip>
+  </TooltipProvider>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "31db1aa44d25"
+---
+
+## Usage
+
+`Tooltip` is for a short, non-interactive label shown on hover or keyboard
+focus - an icon button's name, the full text behind a truncated value. Reach
+for `Popover` instead the moment the content needs to be interactive or open
+on click rather than hover.
+
+`TooltipProvider` wraps the app (or the relevant subtree) once; it is not
+per-`Tooltip`. Forgetting it is the most common integration mistake - the
+component renders without an error but the tooltip never appears.
+
+A tooltip is supplementary context, not the accessible name itself - an
+icon-only trigger still needs its own `aria-label` for assistive tech.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `TooltipProvider` | Wraps the app or subtree once. Required for any `Tooltip` inside it to work. |
+| `Tooltip` | Root. Holds open state for one tooltip instance. |
+| `TooltipTrigger` | Shows the tooltip on hover or focus. Use `asChild` to wrap a real `Button` or icon. |
+| `TooltipContent` | The label. Renders its own portal and positioning; keep its content brief. |

package/knowledge/top-nav.md

@@ -0,0 +1,138 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: top-nav
+  sourceFile: packages/design-system/src/components/top-nav.tsx
+  client: true
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Breadcrumbs
+      kind: component
+      typeText: "ForwardRefExoticComponent<BreadcrumbsProps & RefAttributes<HTMLElement>>"
+    - name: BreadcrumbsProps
+      kind: type
+    - name: TopNav
+      kind: component
+      typeText: "ForwardRefExoticComponent<TopNavProps & RefAttributes<HTMLElement>>"
+    - name: TopNavProps
+      kind: type
+  primaryExport: TopNav
+  subcomponents:
+    - Breadcrumbs
+  props:
+    Breadcrumbs:
+      - name: items
+        type: "{ label: string; href?: string | undefined; }[]"
+        required: true
+        declaredIn: self
+      - name: separator
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Custom separator. Default: '/'."
+    TopNav:
+      - name: end
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Right-aligned slot (search, notifications, user menu)."
+      - name: start
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Left-aligned slot (typically breadcrumbs or a page title)."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-topnav--default
+  storybookTitle: Components/TopNav
+  docsId: components-topnav--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "86f108bd34b0"
+  factsHash: f68fb2177011
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A sticky top app-shell bar with start/center/end slots, plus a Breadcrumbs helper for the start slot."
+useWhen:
+  - "the app needs a persistent top bar (alongside or instead of a side Sidebar) for page context, search, and account/notification actions"
+  - "a breadcrumb trail for the current location (use the co-located Breadcrumbs)"
+useInstead:
+  - id: page-header
+    when: "you need an in-content h1 + subtitle + actions row, not a sticky app-shell bar"
+  - id: sidebar
+    when: "the primary navigation should live in a persistent side column instead of (or in addition to) a top bar"
+related:
+  - page-header
+  - sidebar
+composesWith:
+  - search
+  - button
+tokens:
+  - "--border"
+  - "--background"
+  - "--muted-foreground"
+  - "--foreground"
+a11y:
+  notes:
+    - "TopNav renders a <header> with sticky top-0 positioning, so it stays a proper page landmark - don't nest a second <header> inside its start/end/children slots."
+    - "Breadcrumbs renders <nav aria-label=\"Breadcrumb\"> with an <ol>, and marks the current page's item with aria-current=\"page\" - the separator between items is aria-hidden."
+  requiredProps:
+    - "Breadcrumbs requires items; each entry needs label, and href only when that crumb should be a link"
+  keyboard:
+    - "Breadcrumb links are plain <a> elements - reachable and activatable via native link semantics. The current (last) item renders as plain text, not a link, so it is not a separate tab stop."
+  radixHandles: false
+pitfalls:
+  - "TopNav's children prop is a third, center-aligned slot distinct from start/end - passing your page title as children centers it, which reads oddly next to breadcrumbs in start; most layouts want the title in start and leave children empty."
+  - "Breadcrumbs' last item is rendered as plain text even if it has an href - the component always treats the final entry as the current page, so a trailing href is silently unused for navigation."
+subcomponentNotes:
+  Breadcrumbs: "A separate, standalone nav landmark - typically passed into TopNav's start slot, but composable anywhere a breadcrumb trail is needed."
+rtl: "Layout uses flex with gap only (no physical left/right), so both TopNav's three slots and Breadcrumbs' item row mirror correctly under RTL with no extra work."
+canonicalSnippet: |
+  import { TopNav, Breadcrumbs, Search } from "@adres/mgda-ui"
+
+  <TopNav
+    start={<Breadcrumbs items={[{ label: "Courses", href: "/courses" }, { label: "Algebra I" }]} />}
+    end={<Search placeholder="Search" />}
+  />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "86f108bd34b0"
+---
+
+## Usage
+
+TopNav is a sticky, blurred-background app-shell bar with three slots:
+`start` (typically breadcrumbs or a page title), `children` (centered - use
+sparingly, most layouts leave it empty), and `end` (search, notifications, a
+user menu). It works standalone or alongside a `Sidebar` - the two don't
+share any state.
+
+`Breadcrumbs` is exported from the same file because it's the most common
+`start` slot content, but it's fully independent and can be used anywhere a
+breadcrumb trail is needed.
+
+## Anatomy
+
+- **TopNav** - the sticky bar itself: `start` / `children` / `end` slots in a
+  three-way flex row.
+- **Breadcrumbs** - a standalone `<nav>` landmark rendering an ordered list
+  of crumbs; the last item is always the current page (plain text, not a
+  link) regardless of whether it has an `href`.