@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/button.md

@@ -0,0 +1,231 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: button
+  sourceFile: packages/design-system/src/components/button.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Button
+      kind: component
+      typeText: "ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLButtonElement>>"
+    - name: ButtonProps
+      kind: type
+    - name: buttonVariants
+      kind: variants
+      typeText: "TVReturnType<{ variant: { primary: string[]; secondary: string[]; outline: string[]; ghost: string[]; destructive: string[]; accent: string[]; }; size: { sm: \"ax:h-2xl ax:px-sm ax:rounded-(--button-radius) ax:text-sm\"; ....[truncated]"
+  primaryExport: Button
+  subcomponents: []
+  props:
+    Button:
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "When true, renders the child element instead of a button (e.g. for `<Link>`)."
+      - name: aurora
+        type: boolean
+        required: false
+        declaredIn: self
+        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: elevated
+        type: boolean
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: size
+        type: "\"icon\" | \"icon-lg\" | \"icon-sm\" | \"lg\" | \"md\" | \"sm\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: variant
+        type: "\"accent\" | \"destructive\" | \"ghost\" | \"outline\" | \"primary\" | \"secondary\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "React.ButtonHTMLAttributes<HTMLButtonElement>"
+    - "VariantProps<typeof buttonVariants>"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - primary
+        - secondary
+        - outline
+        - ghost
+        - destructive
+        - accent
+      default: primary
+      on: Button
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+        - icon-sm
+        - icon
+        - icon-lg
+      default: md
+      on: Button
+    elevated:
+      kind: boolean
+      default: false
+      on: Button
+  variantSource: tv
+  compoundVariants:
+    - variant: primary
+      elevated: true
+    - variant: destructive
+      elevated: true
+  sizeMaps: []
+  dataSlots:
+    - button
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-slot"
+      - react
+      - tailwind-variants
+  contexts: []
+  stories:
+    - exportName: Primary
+      id: components-button--primary
+    - exportName: Secondary
+      id: components-button--secondary
+    - exportName: Outline
+      id: components-button--outline
+    - exportName: Destructive
+      id: components-button--destructive
+    - exportName: Elevated
+      id: components-button--elevated
+    - exportName: Large
+      id: components-button--large
+    - exportName: IconSizes
+      id: components-button--icon-sizes
+  storybookTitle: Components/Button
+  docsId: components-button--documentation
+  argTypeOptions:
+    variant:
+      - primary
+      - secondary
+      - outline
+      - ghost
+      - destructive
+      - accent
+    size:
+      - sm
+      - md
+      - lg
+      - icon-sm
+      - icon
+      - icon-lg
+  resolvedCleanly: true
+  contractHash: "28e136dac512"
+  factsHash: "444fb0558a09"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The primary interactive control: fires an action or navigates."
+useWhen:
+  - "the user triggers an action - submit, save, delete, open a dialog"
+  - "you need a link that must read as a button (pair with asChild)"
+  - "an icon-only affordance sits in a dense toolbar or table row"
+useInstead:
+  - id: button-group
+    when: "several related actions sit together and read as one control"
+  - id: toggle
+    when: "the control carries persistent on/off state instead of firing an action"
+  - id: badge
+    when: "it only labels status and is not interactive"
+  - id: text-link
+    when: "it should read as a text link, inline or standalone; Button has no link variant"
+related:
+  - button-group
+  - input-button
+  - select-button
+  - toggle
+tokens:
+  - "--button-radius"
+  - "--primary-weaker"
+  - "--primary-weak"
+  - "--primary-strong"
+  - "--primary-foreground"
+  - "--secondary-weaker"
+  - "--secondary-strong"
+  - "--secondary-foreground"
+  - "--destructive-weaker"
+  - "--destructive-foreground"
+  - "--accent-weak"
+  - "--accent-foreground"
+  - "--border"
+  - "--muted"
+  - "--ring"
+a11y:
+  notes:
+    - "The focus-visible ring is built into the base classes. Overriding it through className removes the only visible keyboard affordance."
+    - "disabled applies pointer-events-none, so a tooltip or popover wrapping a disabled button never receives the hover or focus event that would open it. Wrap a disabled button in a container if it needs an explanation."
+  requiredProps:
+    - "aria-label is required when size is icon-sm, icon or icon-lg, because there is no text node to name the control"
+  keyboard:
+    - "Native button semantics: Enter and Space activate, and it takes part in tab order automatically."
+    - "asChild hands semantics to the child, so rendering an anchor makes it a link. Screen readers will announce a link, and Space will no longer activate it."
+  radixHandles: false
+pitfalls:
+  - "aurora is silently ignored when asChild is set, because Slot cannot accept the decorative children it injects."
+  - "elevated only changes anything on the primary and destructive variants. It is wired through compoundVariants, so on outline, ghost, secondary and accent it is accepted and does nothing."
+  - "The aurora orbs are positioned with physical offsets (left, right), so they do not mirror under RTL."
+  - "Pick the icon size that matches its neighbours' height (icon-sm beside sm controls, icon-lg beside lg) rather than shrinking icon with a size-* className."
+  - "There is no link variant. For anything that should read as a text link use TextLink, which also styles a <button> through asChild when the link-looking control is an action."
+rtl: "Base layout is safe (flex with gap), but the aurora orbs use physical left/right offsets and will not mirror. Prefer aurora off for RTL surfaces until those offsets move to logical properties."
+brandNotes: "Variants name a role, never a colour, so a brand re-skins all six by redefining --primary, --secondary, --accent and --destructive. Corner radius comes from --button-radius, which some brands set to a pill."
+canonicalSnippet: |
+  import { Button } from "@adres/mgda-ui"
+
+  <Button variant="primary" size="md" onClick={handleSave}>
+    Save changes
+  </Button>
+reviewedAt: 2026-10-05
+reviewedAgainstContractHash: "28e136dac512"
+---
+
+## Usage
+
+Button is the most leveraged primitive in the system, so it is also the one where a
+wrong default spreads fastest. Reach for `primary` once per view: it marks the single
+action you want taken. Everything else is `secondary`, `outline` or `ghost`.
+
+The six variants describe **role, not colour**. That is what lets a brand re-skin
+every button by redefining a handful of semantic variables, and it is why hardcoding
+a colour on a Button is always a mistake.
+
+Sizes follow a type-and-touch ladder rather than a visual whim: `sm` for dense rows,
+`md` (the default) for ordinary body buttons, `lg` for marketing calls to action.
+Icon-only controls get a matching square per height: `icon-sm` (32px) beside `sm`,
+`icon` (40px) beside `md`, and `icon-lg` (48px) beside `lg`.
+
+### Composing with links
+
+`asChild` renders the child element instead of a `button`, which is how a framework
+`Link` gets button styling without nesting interactive elements:
+
+```tsx
+<Button asChild variant="outline">
+  <Link href="/settings">Settings</Link>
+</Button>
+```
+
+Note what this changes: the accessible role becomes a link, so Space stops
+activating it. Use it for navigation, not for actions.
+
+### Decoration
+
+`aurora` adds blurred orbs behind the label. It is designed for `primary`, and it is
+deliberately inert under `asChild`. Treat it as a marketing flourish, not a state.

package/knowledge/calendar.md

@@ -0,0 +1,168 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: calendar
+  sourceFile: packages/design-system/src/components/calendar.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Calendar
+      kind: component
+      typeText: "ForwardRefExoticComponent<CalendarProps & RefAttributes<HTMLDivElement>>"
+    - name: CalendarMode
+      kind: type
+    - name: CalendarProps
+      kind: type
+    - name: CalendarValue
+      kind: type
+    - name: DateRange
+      kind: type
+  primaryExport: Calendar
+  subcomponents: []
+  props:
+    Calendar:
+      - name: defaultMonth
+        type: Date
+        required: false
+        declaredIn: self
+      - name: defaultValue
+        type: CalendarValue
+        required: false
+        declaredIn: self
+        doc: "Uncontrolled initial selection."
+      - name: isDateDisabled
+        type: "((date: Date) => boolean)"
+        required: false
+        declaredIn: self
+        doc: "Return true to disable a specific day (evaluated after min/max)."
+      - name: locale
+        type: string
+        required: false
+        declaredIn: self
+        doc: "BCP-47 locale for month/weekday names + first weekday. Defaults to the runtime locale."
+      - name: max
+        type: Date
+        required: false
+        declaredIn: self
+      - name: min
+        type: Date
+        required: false
+        declaredIn: self
+        doc: "Selectable bounds (inclusive)."
+      - name: mode
+        type: CalendarMode
+        required: false
+        declaredIn: self
+        doc: "Selection mode. `single` picks one date; `range` picks a start→end span."
+      - name: month
+        type: Date
+        required: false
+        declaredIn: self
+        doc: "Controlled displayed month (any day within it)."
+      - name: onMonthChange
+        type: "((month: Date) => void)"
+        required: false
+        declaredIn: self
+      - name: onValueChange
+        type: "((value: CalendarValue) => void)"
+        required: false
+        declaredIn: self
+      - name: showOutsideDays
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render leading/trailing days from adjacent months (muted). Default true."
+      - name: value
+        type: CalendarValue
+        required: false
+        declaredIn: self
+        doc: "Controlled selection. `Date | undefined` in single mode, `DateRange` in range mode."
+      - name: weekStartsOn
+        type: "0 | 1 | 2 | 3 | 4 | 5 | 6"
+        required: false
+        declaredIn: self
+        doc: "0 = Sunday ... 6 = Saturday. Defaults to the locale's first weekday (Mon fallback)."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"defaultValue\" | \"onChange\">"
+  variants:
+    mode:
+      kind: enum
+      options:
+        - single
+        - range
+      default: single
+      on: Calendar
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-calendar--default
+    - exportName: Range
+      id: components-calendar--range
+  storybookTitle: Components/Calendar
+  docsId: components-calendar--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "90dc8c204fb0"
+  factsHash: "399bec69481a"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A single-day or date-range picker grid with full keyboard navigation, locale-aware names, and RTL-aware arrow keys."
+useWhen:
+  - "picking one date, or a start-to-end range, directly in the UI rather than typing it into a text field"
+a11y:
+  notes:
+    - "The grid uses role=\"grid\"/\"row\"/\"columnheader\"/\"gridcell\" with a single roving tabIndex - only the focused day is tabbable, so Tab moves in and out of the whole grid once and arrow keys move within it, the standard grid-navigation pattern."
+    - "aria-live=\"polite\" on the month caption announces month changes from the nav buttons or PageUp/PageDown, so a screen reader user hears which month they landed on without re-reading the grid."
+    - "Arrow-key direction is read from the resolved CSS direction, not just a locale or dir prop passed to Calendar - it stays correct even when RTL comes from a wrapping dir=\"rtl\" ancestor."
+  keyboard:
+    - "Arrow keys move by day or week; Home/End jump to the start/end of the visible row; PageUp/PageDown move by month, and with Shift by year; Enter/Space selects the focused day."
+  radixHandles: false
+pitfalls:
+  - "value's shape depends on mode: a bare Date in \"single\" mode, a { from, to } DateRange in \"range\" mode - mismatching the two does not throw, it just makes the selection state behave unpredictably at runtime."
+  - "The very first render always uses a fixed \"en\" locale, even without an explicit locale prop - the real navigator.language locale only applies after mount, to avoid an SSR/client hydration mismatch. Expect a brief flash of English month/weekday names on load when locale is unset."
+  - "min/max only disable day selection and grey out the prev/next month buttons - they do not clamp an already-set value or defaultValue that falls outside those bounds."
+  - "In range mode, clicking a day once the range is already complete (both from and to set) starts a brand-new range from that day rather than moving either end - there is no API-level way to just adjust one end of an existing range."
+canonicalSnippet: |
+  import { Calendar } from "@adres/mgda-ui"
+
+  <Calendar
+    mode="range"
+    value={range}
+    onValueChange={setRange}
+    min={new Date()}
+  />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "90dc8c204fb0"
+---
+
+## Usage
+
+`Calendar` is a self-contained day-grid picker - reach for it when the
+interaction is picking a date (or a range) directly in the UI, not typing one
+into a text field. It has no Radix dependency; keyboard navigation, roving
+focus, and range logic are all hand-rolled inside the component.
+
+`mode="single"` (default) picks one `Date`; `mode="range"` picks a
+`{ from, to }` span, with `to` staying `undefined` mid-selection. Keep the
+`value` shape in sync with `mode` - the two are not interchangeable.
+
+Locale drives both the weekday and month names and the default first weekday
+(`weekStartsOn` overrides it). `min`/`max` disable out-of-range days and grey
+out the prev/next month buttons once every day in that direction is disabled,
+but they do not clamp an already-set `value` that falls outside the bounds.