@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/shimmer-text.md

@@ -0,0 +1,140 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: shimmer-text
+  sourceFile: packages/design-system/src/components/shimmer-text.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: shimmerGradient
+      kind: function
+      typeText: "(spread: number) => string"
+    - name: ShimmerText
+      kind: component
+      typeText: "ForwardRefExoticComponent<ShimmerTextProps & RefAttributes<HTMLElement>>"
+    - name: ShimmerTextAs
+      kind: type
+    - name: ShimmerTextProps
+      kind: type
+  primaryExport: ShimmerText
+  subcomponents: []
+  props:
+    ShimmerText:
+      - name: as
+        type: ShimmerTextAs
+        required: false
+        declaredIn: self
+      - name: duration
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Seconds for one sweep."
+      - name: spread
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Width of the highlight as a percentage either side of centre, clamped to 5-45."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLElement>"
+  variants:
+    as:
+      kind: enum
+      options:
+        - div
+        - h2
+        - h3
+        - p
+        - span
+        - h1
+        - h4
+        - h5
+        - h6
+        - strong
+      default: null
+      on: ShimmerText
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - shimmer-text
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-shimmertext--default
+    - exportName: Heading
+      id: components-shimmertext--heading
+    - exportName: SlowWide
+      id: components-shimmertext--slow-wide
+  storybookTitle: Components/ShimmerText
+  docsId: components-shimmertext--documentation
+  argTypeOptions:
+    as:
+      - span
+      - p
+      - div
+      - strong
+      - h1
+      - h2
+      - h3
+      - h4
+      - h5
+      - h6
+  resolvedCleanly: true
+  contractHash: a190e87b4e79
+  factsHash: "98e1f6414f0c"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "Text with a highlight sweeping across it, for work in progress such as \"Thinking\" or \"Searching listings\". Set the element, sweep duration and highlight width."
+useWhen:
+  - "a short label stands for work that is still happening, such as an assistant thinking or a search running"
+  - "a custom AI layout needs the same in-progress shimmer as ThinkingSteps and Reasoning"
+useInstead:
+  - id: spinner
+    when: "there is no label, or the wait is not tied to text"
+  - id: skeleton
+    when: "content is loading and you want to hold its shape"
+related:
+  - thinking-steps
+  - reasoning
+a11y:
+  notes:
+    - "The shimmer is decorative; the text itself must say what is happening."
+    - "The sweep stops under reduced motion and the text stays readable."
+    - "It is not a live region; announce state changes separately if they matter."
+  radixHandles: false
+pitfalls:
+  - "Use it only while the work is running; swap to plain text once done."
+  - "Keep it to a short label, not a paragraph; a long sweep is hard to read."
+  - "It sets its own colour through the gradient; text colour classes have no effect."
+canonicalSnippet: |
+  import { ShimmerText } from "@adres/mgda-ui"
+
+  {searching ? <ShimmerText>Searching listings</ShimmerText> : "Searched 128 listings"}
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: a190e87b4e79
+---
+
+## Usage
+
+`ShimmerText` renders its children with a bright band sweeping across muted
+text. `as` picks the element (`span` by default), `duration` sets seconds per
+sweep (2.5 by default) and `spread` sets the band's width as a percentage
+either side of centre, from 5 to 45 (20 by default). `shimmerGradient`
+returns the gradient for custom elements.
+
+ThinkingSteps and Reasoning use it for their labels while running.
+
+## Anatomy
+
+- `ShimmerText` - the shimmering text element.

package/knowledge/sidebar.md

@@ -0,0 +1,227 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: sidebar
+  sourceFile: packages/design-system/src/components/sidebar.tsx
+  client: true
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Sidebar
+      kind: component
+      typeText: "ForwardRefExoticComponent<SidebarProps & RefAttributes<HTMLElement>>"
+    - name: SidebarItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<SidebarItemProps & RefAttributes<HTMLAnchorElement>>"
+    - name: SidebarItemProps
+      kind: type
+    - name: SidebarProps
+      kind: type
+    - name: SidebarSection
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & { label?: ReactNode; collapsed?: boolean | undefined; } & RefAttributes<HTMLDivElement>>"
+    - name: SidebarUserCard
+      kind: component
+      typeText: "ForwardRefExoticComponent<SidebarUserCardProps & RefAttributes<HTMLDivElement>>"
+    - name: SidebarUserCardProps
+      kind: type
+  primaryExport: Sidebar
+  subcomponents:
+    - SidebarItem
+    - SidebarSection
+    - SidebarUserCard
+  props:
+    Sidebar:
+      - name: brand
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional logo / brand mark slot at the top."
+      - name: collapsed
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Collapsed state - controlled. When undefined, sidebar is always open."
+      - name: footer
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional footer slot (typically a `SidebarUserCard`)."
+      - name: width
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Sidebar width in rem; default 16rem (256px)."
+    SidebarItem:
+      - name: active
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render as the child element (e.g. a Next.js `<Link>`). The child receives the className, ref, and event props so it behaves as the sidebar row while keeping its own navigation behaviour."
+      - name: collapsed
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+    SidebarSection:
+      - name: collapsed
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: label
+        type: ReactNode
+        required: false
+        declaredIn: self
+    SidebarUserCard:
+      - name: action
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Trailing slot - typically a DropdownMenu trigger for settings/logout."
+      - name: avatar
+        type: ReactNode
+        required: true
+        declaredIn: self
+        doc: "Avatar element (typically `<Avatar>` from the DS)."
+      - name: collapsed
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Hides the name/role/action when the parent Sidebar is collapsed."
+      - name: name
+        type: ReactNode
+        required: true
+        declaredIn: self
+        doc: "Display name."
+      - name: role
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Role / sub-label rendered under the name (e.g. \"Company Admin\")."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal:
+      - tooltip
+    lib:
+      - cn
+    hooks:
+      - use-reduced-motion
+    external:
+      - "@radix-ui/react-slot"
+      - motion/react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-sidebar--default
+  storybookTitle: Components/Sidebar
+  docsId: components-sidebar--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: bd9b677804d5
+  factsHash: "9c211fee9f28"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The structural app-shell nav column: brand, scrollable body, footer, with a collapse animation."
+useWhen:
+  - "building a persistent left-hand app navigation shell"
+  - "you need the raw structural pieces (brand/body/footer, a row, a labeled section, a user footer card) to compose a custom nav"
+useInstead:
+  - id: nav-sidebar
+    when: "you want ready-made active-state routing, nested items, and a collapse toggle instead of assembling them yourself"
+  - id: top-nav
+    when: "the app's primary navigation is horizontal, not a side column"
+related:
+  - nav-sidebar
+  - tooltip
+composesWith:
+  - tooltip
+tokens:
+  - "--border"
+  - "--card"
+  - "--card-foreground"
+  - "--primary"
+  - "--primary-foreground"
+  - "--muted"
+  - "--muted-foreground"
+  - "--ring"
+a11y:
+  notes:
+    - "Sidebar renders <aside aria-label=\"Primary\">, so a page with more than one landmark should not add a second aside labeled the same way."
+    - "SidebarItem shows the label as a Tooltip when collapsed, so keep children to a short string in that mode - a Tooltip cannot usefully render a paragraph."
+    - "The width-collapse animation is suppressed under prefers-reduced-motion via the useReducedMotion hook, falling back to a plain <aside> with no motion.aside."
+  requiredProps:
+    - "SidebarUserCard requires avatar and name; role and action are optional"
+  keyboard:
+    - "SidebarItem is a native <a> by default, so it is reachable and activatable via standard link semantics."
+    - "asChild hands the row to the child (e.g. a router Link), so the item keeps the visual row treatment while the child owns actual navigation and focus behavior."
+  radixHandles: false
+pitfalls:
+  - "collapsed on Sidebar is controlled-only: passing undefined means the sidebar is always expanded, there is no internal uncontrolled fallback. Reach for NavSidebar if you want the collapse state managed for you."
+  - "SidebarItem's asChild uses Radix Slot, so it accepts exactly one child element - wrapping multiple children or a fragment throws the same way any other Slot consumer does."
+  - "width is a plain number of rem, not a CSS length string - passing \"16rem\" instead of 16 breaks the inline width calculation."
+subcomponentNotes:
+  SidebarItem: "A row inside Sidebar. Renders <a> by default; pass asChild to wrap a router Link. Reserves a 2px start-edge bar on every row (active or not) so activating never shifts the label."
+  SidebarSection: "Groups SidebarItems with an optional overline label, hidden automatically when collapsed is true."
+  SidebarUserCard: "Conventional footer block: avatar + name + role + optional trailing action. Collapses to avatar-only when collapsed is true."
+rtl: "Uses logical properties (border-e, ps-*/pe-*, border-s-2) throughout, so the column and its active-state bar flip correctly under RTL without extra work."
+canonicalSnippet: |
+  import { Sidebar, SidebarSection, SidebarItem, SidebarUserCard, Avatar } from "@adres/mgda-ui"
+  import { Home, Book } from "lucide-react"
+
+  <Sidebar
+    brand={<img src="/logo.svg" alt="Acme" className="ax:h-6" />}
+    footer={<SidebarUserCard avatar={<Avatar />} name="Sara Ahmed" role="Company Admin" />}
+  >
+    <SidebarSection label="Main menu">
+      <SidebarItem icon={<Home />} active>Dashboard</SidebarItem>
+      <SidebarItem icon={<Book />}>Courses</SidebarItem>
+    </SidebarSection>
+  </Sidebar>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: bd9b677804d5
+---
+
+## Usage
+
+Sidebar is the low-level structural primitive: a fixed-width column with a brand
+slot, a scrollable body, and an optional footer, plus a spring-animated
+collapse transition. It does not know about routes, active state, or nested
+menus - that behavior lives one level up in `NavSidebar`. Reach for `Sidebar`
+directly only when you're building a custom navigation shell that doesn't fit
+`NavSidebar`'s config-driven model.
+
+`collapsed` is controlled: passing it drives the width animation between the
+full `width` (default 16rem) and a fixed 4rem icon rail. Passing nothing
+leaves the sidebar permanently expanded - there is no internal toggle.
+
+## Anatomy
+
+- **Sidebar** - the column itself: brand header, scrollable `<nav>` body,
+  footer. Wraps its content in a `TooltipProvider` so collapsed `SidebarItem`s
+  can show their label as a tooltip without the consumer wrapping the app root.
+- **SidebarSection** - groups a set of `SidebarItem`s under an optional
+  overline label; the label (and its own spacing) disappears when the parent
+  is collapsed.
+- **SidebarItem** - a single nav row. Shows an icon, and either the label text
+  (expanded) or a tooltip carrying the label (collapsed). `active` renders the
+  tinted background and start-edge accent bar.
+- **SidebarUserCard** - the conventional footer block: avatar, name, an
+  optional role sub-label, and an optional trailing action slot (typically a
+  `DropdownMenu` trigger). Collapses to just the avatar.

package/knowledge/skeleton.md

@@ -0,0 +1,142 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: skeleton
+  sourceFile: packages/design-system/src/components/skeleton.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Skeleton
+      kind: component
+      typeText: "ForwardRefExoticComponent<SkeletonProps & RefAttributes<HTMLDivElement>>"
+    - name: SkeletonProps
+      kind: type
+    - name: SkeletonText
+      kind: component
+      typeText: "ForwardRefExoticComponent<SkeletonTextProps & RefAttributes<HTMLDivElement>>"
+    - name: SkeletonTextProps
+      kind: type
+    - name: SkeletonVariant
+      kind: type
+  primaryExport: Skeleton
+  subcomponents:
+    - SkeletonText
+  props:
+    Skeleton:
+      - name: variant
+        type: "\"none\" | \"pulse\" | \"shimmer\""
+        required: false
+        declaredIn: self
+        variantKey: true
+    SkeletonText:
+      - name: lineClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Line height - applied to every line. Default `h-3`."
+      - name: lines
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Number of text lines to render. Default 3."
+      - name: variant
+        type: SkeletonVariant
+        required: false
+        declaredIn: self
+        doc: "Animation variant - applied to every line."
+        variantKey: true
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+    - "VariantProps<typeof skeletonVariants>"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - pulse
+        - shimmer
+        - none
+      default: pulse
+      on: Skeleton
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-skeleton--default
+  storybookTitle: Components/Skeleton
+  docsId: components-skeleton--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: dcb07facc093
+  factsHash: bd7402c31120
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A placeholder block that mimics the shape of content still loading, plus SkeletonText for stacked paragraph-line placeholders."
+useWhen:
+  - "content is loading asynchronously and a shape-matched placeholder reduces layout shift and perceived wait"
+  - "specifically placeholdering multiple lines of text (SkeletonText)"
+useInstead:
+  - id: empty-state
+    when: "there is no content to eventually load - a genuinely empty result, not something still loading"
+  - id: spinner
+    when: "the eventual content's shape is not known or not worth matching - a spinner is a lighter-weight indicator for a short or generic wait"
+related:
+  - empty-state
+  - spinner
+a11y:
+  notes:
+    - "Both Skeleton and SkeletonText render aria-hidden=\"true\" and never announce to screen readers - pair them with a real loading indication elsewhere (aria-busy, or a visually-hidden status message) if the loading state itself needs to be announced."
+  radixHandles: false
+pitfalls:
+  - "variant defaults to \"pulse\"; \"shimmer\" is heavier (an animated gradient overlay) and reads better on large blocks like hero images or card previews than on small text-line placeholders - picking shimmer for tiny skeletons can look busier than pulse."
+  - "Skeleton has no built-in size - width and height come entirely from className or inherited layout, so an unsized Skeleton with no explicit dimensions collapses to a zero-height block."
+  - "SkeletonText's last line is always forced to a shorter fixed width regardless of lines, to read as a paragraph ending - you cannot make every line the same width through lineClassName alone."
+canonicalSnippet: |
+  import { Skeleton, SkeletonText } from "@adres/mgda-ui"
+
+  <div className="ax:flex ax:items-center ax:gap-md">
+    <Skeleton className="ax:size-10 ax:rounded-full" />
+    <SkeletonText lines={2} className="ax:flex-1" />
+  </div>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: dcb07facc093
+---
+
+## Usage
+
+`Skeleton` is a shape, not a component with intrinsic sizing - give it width
+and height (or `size-*`) through `className` to match whatever content it's
+standing in for: a circle for an avatar, a rectangle for an image, a short bar
+for a badge.
+
+Reach for `SkeletonText` instead of stacking `Skeleton` lines by hand when
+placeholdering a paragraph - it renders `lines` bars with naturally varied
+widths and always shortens the last one, so it reads as text rather than a
+uniform grey block.
+
+`variant` picks the animation: `pulse` (default) is a quiet opacity
+oscillation suited to most cases, `shimmer` is a sliding gradient better
+suited to large placeholder blocks, and `none` is static, useful inside an
+already-animated parent or for visual snapshot tests. `motion-reduce`
+disables both animated variants automatically.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Skeleton` | The base placeholder block. `variant` picks pulse, shimmer, or no animation. |
+| `SkeletonText` | A stack of `Skeleton` lines with naturally varied widths. The last line is always shorter, to read as a paragraph's end. |

package/knowledge/slider.md

@@ -0,0 +1,133 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: slider
+  sourceFile: packages/design-system/src/components/slider.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Slider
+      kind: component
+      typeText: "ForwardRefExoticComponent<SliderProps & RefAttributes<HTMLSpanElement>>"
+    - name: SliderProps
+      kind: type
+    - name: SliderSize
+      kind: type
+    - name: SliderValueLabel
+      kind: type
+  primaryExport: Slider
+  subcomponents: []
+  props:
+    Slider:
+      - name: formatValue
+        type: "((value: number) => ReactNode)"
+        required: false
+        declaredIn: self
+        doc: "Format the value rendered in the label (e.g. add a \"%\" suffix, currency). Default: the raw number."
+      - name: marks
+        type: "boolean | number[]"
+        required: false
+        declaredIn: self
+        doc: "Render tick marks along the track. - `true` - auto-generate at every `step` between `min` and `max` (auto-generation is skipped when it would produce more than 21 marks - for fine sliders, provide an explicit array instead) - `number[]` - render marks at exactly the provided positions"
+      - name: size
+        type: "\"lg\" | \"md\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: valueLabel
+        type: SliderValueLabel
+        required: false
+        declaredIn: self
+        doc: "Show the current value in a small pill above each thumb. - `\"always\"` - pill is always visible - `\"active\"` - pill appears on hover / focus / drag, hidden otherwise - `false` (default) - no pill"
+  extendsProps:
+    - "React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>"
+    - "VariantProps<typeof trackVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: Slider
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - LABEL_OFFSET
+    - THUMB_SIZE
+    - TRACK_HEIGHT
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-slider"
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-slider--default
+  storybookTitle: Components/Slider
+  docsId: components-slider--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: e376c3f50f6d
+  factsHash: "044041bba365"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A drag-to-select range control (single or multi-thumb) built on Radix Slider, with optional tick marks and a per-thumb value label."
+useWhen:
+  - "picking a numeric value, or a range between two values, by dragging rather than typing"
+useInstead:
+  - id: input
+    when: "the value needs to be typed precisely rather than dragged"
+related:
+  - input
+tokens:
+  - "--muted"
+  - "--primary"
+  - "--background"
+  - "--ring"
+  - "--foreground"
+a11y:
+  notes:
+    - "Each thumb is a real Radix slider thumb with native ARIA (role=\"slider\", aria-valuenow/min/max) - no additional labeling is required for the numeric value itself, though a visible field label is still needed to say what the slider controls."
+    - "valueLabel's pill is aria-hidden - it is a visual convenience, not the accessible value announcement, which Radix already provides through the native slider ARIA attributes."
+  keyboard:
+    - "Native Radix slider keyboard behavior: arrow keys nudge by step, Page Up/Down jump by a larger increment, Home/End jump to min/max."
+  radixHandles: true
+pitfalls:
+  - "The number of thumbs is driven entirely by the length of value/defaultValue - passing a two-element array renders a range slider with two thumbs automatically; there is no separate range prop to set."
+  - "marks={true} silently renders nothing once the auto-generated tick count would exceed 21 for fine-grained step/min/max combinations - pass an explicit number[] for a fine slider that still needs visible marks."
+  - "valueLabel=\"active\" reveals the pill via CSS group-hover/group-focus-visible/group-active on the thumb - overriding the thumb's className in a way that drops the group class silently stops the pill from appearing on interaction."
+canonicalSnippet: |
+  import { Slider } from "@adres/mgda-ui"
+
+  <Slider defaultValue={[50]} valueLabel="active" />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: e376c3f50f6d
+---
+
+## Usage
+
+`Slider` is for picking a numeric value, or a range between two values, by
+dragging - reach for `Input` instead when the value needs to be typed
+precisely rather than dragged.
+
+The number of thumbs is driven entirely by how many values `value`/
+`defaultValue` holds - pass a two-element array for a range slider with two
+thumbs; there is no separate prop to opt into range mode.
+
+Set `valueLabel="always"` or `"active"` to show the current value in a pill
+above each thumb (`"active"` reveals it only on hover, focus, or drag), and
+`marks` to render tick marks along the track - `true` auto-generates one per
+`step`, capped at 21 marks before it silently renders none, so pass an
+explicit array for finer-grained sliders that still need visible marks.