@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/input-button.md

@@ -0,0 +1,187 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: input-button
+  sourceFile: packages/design-system/src/components/input-button.tsx
+  client: true
+  category: web-app-form-controls
+  categoryFromBarrel: web-app-form-controls
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: InputButton
+      kind: component
+      typeText: "ForwardRefExoticComponent<InputButtonProps & RefAttributes<HTMLInputElement>>"
+    - name: InputButtonProps
+      kind: type
+    - name: InputButtonSize
+      kind: type
+    - name: InputButtonVariant
+      kind: type
+  primaryExport: InputButton
+  subcomponents: []
+  props:
+    InputButton:
+      - name: buttonClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra className appended to the inner Button."
+      - name: buttonDisabled
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: buttonLabel
+        type: ReactNode
+        required: true
+        declaredIn: self
+      - name: buttonType
+        type: "\"button\" | \"reset\" | \"submit\""
+        required: false
+        declaredIn: self
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+        doc: "className for the wrapping group (the input fills the remaining width)."
+      - name: inputClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra className appended to the inner Input."
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: input
+      - name: onButtonClick
+        type: "MouseEventHandler<HTMLButtonElement>"
+        required: false
+        declaredIn: self
+      - name: size
+        type: InputSize
+        required: false
+        declaredIn: self
+        doc: "Shared height/typography ladder - matches Button, Input, Select."
+      - name: variant
+        type: InputButtonVariant
+        required: false
+        declaredIn: self
+        doc: "Visual treatment of the right-hand action button."
+  extendsProps:
+    - "Omit<InputProps, \"size\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: InputButton
+    variant:
+      kind: enum
+      options:
+        - primary
+        - secondary
+        - outline
+      default: primary
+      on: InputButton
+    buttonType:
+      kind: enum
+      options:
+        - button
+        - submit
+        - reset
+      default: button
+      on: InputButton
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - input-button
+  dependsOn:
+    internal:
+      - button
+      - input
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-inputbutton--default
+  storybookTitle: Components/InputButton
+  docsId: components-inputbutton--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: f53f637fadd9
+  factsHash: "894c989301af"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A free-text Input and a commit-action Button joined into one inline composite control, sharing a single height."
+useWhen:
+  - "a text field needs an adjacent commit action - a search box with a Search button, or free-text entry plus Apply/Submit"
+useInstead:
+  - id: select-button
+    when: "the left half should be a fixed list of options rather than free text"
+  - id: search
+    when: "there is no separate commit button - Search already includes its own icon and clear affordance inline"
+related:
+  - select-button
+  - search
+a11y:
+  notes:
+    - "disabled disables both halves at once; use buttonDisabled to disable only the action button while the input stays editable."
+    - "All standard input attributes (value, onChange, placeholder, name, aria-*, and so on) forward straight to the inner Input, so the field keeps normal form semantics despite the composite wrapper."
+  keyboard:
+    - "Tab moves between the input and the button independently, since they are two separate focusable controls in the DOM despite the joined visual pill."
+  radixHandles: false
+pitfalls:
+  - "variant excludes ghost, accent, destructive, and link, mirroring SelectButton - only primary/secondary/outline fit the joined-pill visual."
+  - "disabled and buttonDisabled are independent - disabled turns off the whole control (input and button), while buttonDisabled leaves the input editable and only disables the button."
+  - "value, onChange, and placeholder are all real, forwarded Input props, but the extractor recorded this file's extends clause as Omit<InputProps, \"size\">, a local type alias rather than a raw HTML attributes type - it does not match the pattern the validator uses to recognize inherited DOM props. The machine-checked canonicalSnippet below omits them for that reason; see the fuller example in ## Usage."
+canonicalSnippet: |
+  import { InputButton } from "@adres/mgda-ui"
+
+  <InputButton
+    size="md"
+    buttonType="submit"
+    buttonLabel="Search"
+    onButtonClick={handleSearch}
+    onChange={(e) => setValue(e.target.value)}
+  />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: f53f637fadd9
+---
+
+## Usage
+
+`InputButton` joins a free-text `Input` and a commit-action `Button` into one
+visual pill - the sibling of `SelectButton`, but for text entry instead of a
+fixed list. Reach for `SelectButton` when the left half should be a list of
+options, and plain `Search` when there is no separate commit button (it
+already includes its own icon and clear affordance inline).
+
+`size` scales both halves together and matches `Button`/`Input`/`Select`'s
+own height ladder. `variant` only applies to the right-hand button and is
+restricted to `primary`/`secondary`/`outline`, the same restriction
+`SelectButton` uses.
+
+All standard input attributes forward straight to the inner `Input`,
+including `value`, `onChange`, and `placeholder` - they just cannot appear in
+this file's machine-checked `canonicalSnippet` above (see the pitfall on
+why). The real, recommended usage:
+
+```tsx
+<InputButton
+  size="md"
+  placeholder="e.g. AUH-100482"
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+  buttonType="submit"
+  buttonLabel="Search"
+/>
+```

package/knowledge/input-group.md

@@ -0,0 +1,185 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: input-group
+  sourceFile: packages/design-system/src/components/input-group.tsx
+  client: true
+  category: uncategorized
+  categoryFromBarrel: null
+  barrelExported: false
+  importPath: "@adres/mgda-ui/components/input-group"
+  exports:
+    - name: InputGroup
+      kind: component
+      typeText: "ForwardRefExoticComponent<InputGroupProps & RefAttributes<HTMLInputElement>>"
+    - name: InputGroupProps
+      kind: type
+    - name: InputGroupSize
+      kind: type
+  primaryExport: InputGroup
+  subcomponents: []
+  props:
+    InputGroup:
+      - name: children
+        type: ReactNode
+        required: true
+        declaredIn: self
+        doc: "SelectItem (and SelectLabel/SelectSeparator) children for the popover."
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+        doc: "className for the wrapping group (the input fills the remaining width)."
+      - name: inputClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra className appended to the inner Input."
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: input
+      - name: onSelectValueChange
+        type: "((value: string) => void)"
+        required: false
+        declaredIn: self
+      - name: selectClassName
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra className appended to the select trigger."
+      - name: selectDefaultValue
+        type: string
+        required: false
+        declaredIn: self
+      - name: selectDisabled
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Disables only the select half. `disabled` (inherited from InputProps) disables both."
+      - name: selectName
+        type: string
+        required: false
+        declaredIn: self
+      - name: selectPlaceholder
+        type: string
+        required: false
+        declaredIn: self
+      - name: selectValue
+        type: string
+        required: false
+        declaredIn: self
+      - name: size
+        type: InputGroupSize
+        required: false
+        declaredIn: self
+        doc: "Shared height/typography ladder - matches Button, Input, Select, InputButton, SelectButton."
+        variantKey: true
+  extendsProps:
+    - "Omit<InputProps, \"size\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: InputGroup
+  variantSource: tv
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - input-group
+  dependsOn:
+    internal:
+      - input
+      - select
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-select"
+      - lucide-react
+      - react
+      - tailwind-variants
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-inputgroup--default
+    - exportName: Sizes
+      id: components-inputgroup--sizes
+  storybookTitle: Components/InputGroup
+  docsId: components-inputgroup--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "4e29e3ec5a4b"
+  factsHash: "04c0e03ce79c"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A Select + Input joined into a single inline field, e.g. a title-select paired with a name field or a country-code paired with a phone number."
+useWhen:
+  - "two related fields (a short select and a free-text input) should read and submit as one visual control"
+  - "a title/prefix select (Mr./Ms./Dr.) needs to sit directly against a name or free-text field"
+  - "a country-code select needs to sit directly against a phone-number input"
+useInstead:
+  - id: input-button
+    when: "the joined control pairs an Input with an action Button, not a Select"
+  - id: select-button
+    when: "the joined control pairs a Select with an action Button, not an Input"
+  - id: select
+    when: "only the select half is needed, with no adjoining input"
+related:
+  - input-button
+  - select-button
+  - select
+composesWith:
+  - select
+a11y:
+  notes:
+    - "The select half has no visible label by itself - pair the whole group with a `<label>` describing the combined field (e.g. \"Name\"), and rely on selectPlaceholder for the select's own accessible hint."
+    - "disabled disables both halves; use selectDisabled to disable only the select while keeping the input editable."
+  radixHandles: true
+pitfalls:
+  - "disabled (inherited from InputProps) disables BOTH the select and the input - use selectDisabled if you only want to lock the select half."
+  - "size on InputGroup only accepts sm/md/lg and is separate from Input's own size prop - InputGroup already forwards the resolved size to the inner Input, so don't also pass size to children."
+  - "children must be SelectItem (and SelectLabel/SelectSeparator) elements for the popover, not arbitrary content - the input half has no children slot of its own."
+canonicalSnippet: |
+  import { InputGroup } from "@adres/mgda-ui/components/input-group"
+  import { SelectItem } from "@adres/mgda-ui"
+
+  <InputGroup
+    size="md"
+    selectPlaceholder="Title"
+    selectDefaultValue="mr"
+    onSelectValueChange={setTitle}
+    onChange={(e) => setName(e.target.value)}
+  >
+    <SelectItem value="mr">Mr.</SelectItem>
+    <SelectItem value="ms">Ms.</SelectItem>
+  </InputGroup>
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "4e29e3ec5a4b"
+---
+
+## Usage
+
+`InputGroup` joins a `Select` trigger and an `Input` into one visually
+continuous pill, the same joined-composite family as `InputButton` (Input +
+Button) and `SelectButton` (Select + Button). Reach for it when two related
+fields - most often a short prefix select and a free-text field, like a
+title/name pair or a country-code/phone-number pair - should read as a single
+control instead of two separate ones.
+
+Select-half props are prefixed (`selectValue`, `selectDefaultValue`,
+`onSelectValueChange`, `selectPlaceholder`, `selectName`, `selectDisabled`,
+`selectClassName`) so they don't collide with the native input attributes
+(`value`, `placeholder`, `onChange`, `disabled`, ...) inherited from
+`InputProps`. `disabled` disables both halves; use `selectDisabled` to disable
+only the select side.
+
+`size` (`sm` | `md` | `lg`) is shared across both halves and matches the
+height/typography ladder used by `Button`, `Input`, `Select`, `InputButton`
+and `SelectButton`, so an `InputGroup` lines up with any of those siblings at
+the same size.

package/knowledge/input.md

@@ -0,0 +1,256 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: input
+  sourceFile: packages/design-system/src/components/input.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Field
+      kind: component
+      typeText: "ForwardRefExoticComponent<FieldProps & RefAttributes<HTMLDivElement>>"
+    - name: FieldProps
+      kind: type
+    - name: Input
+      kind: component
+      typeText: "ForwardRefExoticComponent<InputProps & RefAttributes<HTMLInputElement>>"
+    - name: InputProps
+      kind: type
+    - name: InputSize
+      kind: type
+    - name: Label
+      kind: component
+      typeText: "ForwardRefExoticComponent<LabelProps & RefAttributes<HTMLLabelElement>>"
+    - name: LabelProps
+      kind: type
+    - name: LabelSize
+      kind: type
+    - name: Textarea
+      kind: component
+      typeText: "ForwardRefExoticComponent<TextareaProps & RefAttributes<HTMLTextAreaElement>>"
+    - name: TextareaProps
+      kind: type
+    - name: TextareaResize
+      kind: type
+    - name: TextareaSize
+      kind: type
+    - name: TextFieldRoot
+      kind: component
+      typeText: "ForwardRefExoticComponent<TextFieldRootProps & RefAttributes<HTMLDivElement>>"
+    - name: TextFieldRootProps
+      kind: type
+    - name: TextFieldSlot
+      kind: component
+      typeText: "ForwardRefExoticComponent<TextFieldSlotProps & RefAttributes<HTMLDivElement>>"
+    - name: TextFieldSlotProps
+      kind: type
+  primaryExport: Input
+  subcomponents:
+    - Field
+    - Label
+    - Textarea
+    - TextFieldRoot
+    - TextFieldSlot
+  props:
+    Field:
+      - name: error
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: help
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: size
+        type: InputSize
+        required: false
+        declaredIn: self
+        doc: "Sizes the Label and any Input/Textarea/TextFieldRoot inside, unless one overrides it directly."
+    Input:
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: size
+        type: InputSize
+        required: false
+        declaredIn: self
+    Label:
+      - name: size
+        type: LabelSize
+        required: false
+        declaredIn: self
+    Textarea:
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: resize
+        type: TextareaResize
+        required: false
+        declaredIn: self
+      - name: size
+        type: TextareaSize
+        required: false
+        declaredIn: self
+    TextFieldRoot:
+      - name: invalid
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: size
+        type: InputSize
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.InputHTMLAttributes<HTMLInputElement>, \"size\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: Input
+    resize:
+      kind: enum
+      options:
+        - none
+        - horizontal
+        - vertical
+        - both
+      default: vertical
+      on: Textarea
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - HEIGHT
+    - LABEL_TEXT_SIZE
+    - PADDING_X
+    - RESIZE_CLASS
+    - TEXTAREA_SIZE
+    - TEXT_SIZE
+  dataSlots:
+    - input
+    - textarea
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts:
+    - name: TextFieldContext
+      type: TextFieldContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-input--default
+    - exportName: TextareaStory
+      id: components-input--textarea-story
+  storybookTitle: Components/Input
+  docsId: components-input--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "351b79aa1dfa"
+  factsHash: "97acd1cb8a1c"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A text field, standalone or slotted with icons/buttons via TextFieldRoot, plus its Label/Field/Textarea companions."
+useWhen:
+  - "collecting a single line of free text - name, email, any plain form field"
+  - "collecting multi-line text (reach for Textarea)"
+  - "an icon, unit, or button needs to sit inside the field's border (TextFieldRoot + TextFieldSlot)"
+useInstead:
+  - id: search
+    when: "the field is specifically a search box - Search already assembles TextFieldRoot + icon + clear button, don't reassemble it"
+related:
+  - search
+tokens:
+  - "--input-radius"
+  - "--input"
+  - "--card"
+  - "--foreground"
+  - "--muted-foreground"
+  - "--destructive"
+  - "--destructive-foreground"
+  - "--ring"
+  - "--muted"
+a11y:
+  notes:
+    - "Field auto-wires aria-describedby to its help/error text, but only across its direct children - don't wrap the control in another element or the cloning that links them never reaches it."
+    - "invalid maps straight to aria-invalid on Input/Textarea, but TextFieldRoot's own invalid prop only changes the container's border/ring - set invalid on the inner Input too, or a screen reader won't hear the invalid state."
+  requiredProps:
+    - "Label needs an explicit htmlFor (or let Field assign matching ids by giving the control no id of its own) - association isn't inferred from DOM nesting."
+  keyboard:
+    - "Native input/textarea semantics only - no custom key handling."
+  radixHandles: false
+pitfalls:
+  - "Field clones every direct child, not just the control - a Label sitting next to the input also receives the generated id/aria-describedby/aria-invalid attributes. Harmless on the DOM, but means Field only really suits a Label+control pair, not a larger group."
+  - "TextFieldRoot's invalid prop only styles the container; it doesn't set aria-invalid on the nested Input, so pair it with invalid (or aria-invalid) on the Input itself for the state to be announced."
+  - "Input defers to TextFieldRoot's context size only when its own size prop is unset - passing a different size to each produces mismatched height/padding between the root and the field."
+  - "Set size once on Field rather than on each child - Field's size reaches Label, Input, Textarea and TextFieldRoot through context, and a size on any child overrides it for that child only."
+  - "Label's default type is t-label-xs for sm and md; only size lg steps up to t-label-sm. A Label outside any Field or TextFieldRoot uses md."
+canonicalSnippet: |
+  import { Field, Input, Label } from "@adres/mgda-ui"
+
+  const emailHelp = "We do not share your email."
+
+  <Field className="ax:max-w-sm" help={emailHelp}>
+    <Label htmlFor="email">Email</Label>
+    <Input id="email" type="email" placeholder="you@example.com" />
+  </Field>
+reviewedAt: 2026-10-26
+reviewedAgainstContractHash: "351b79aa1dfa"
+---
+
+## Usage
+
+`Input` covers both a standalone text field and a slotted one. Use it standalone
+for a plain label+field pair, the common case. Use `TextFieldRoot` +
+`TextFieldSlot` + `Input` together when an icon, unit, or button needs to sit
+inside the field's border - `Search` is the shipped example of this pattern and
+should be reached for directly when the field is specifically a search box,
+rather than reassembling the three primitives.
+
+Reach for `Textarea` for multi-line input; it shares `Input`'s size ramp and
+type scale so the two read consistently side by side in the same form.
+
+`Field` is the wrapper that wires a `Label` to its control: it generates an id,
+links `aria-describedby` to the help/error text, and sets `aria-invalid` when
+`error` is passed. Wrap exactly one control (plus its `Label`) per `Field` - the
+wiring assumes a single field, not a fieldset of several.
+
+### Sizes
+
+`sm`/`md` (default)/`lg` follow the same type-and-touch ladder as `Button`, so a
+`Button` and an `Input` at the same size share height and horizontal padding -
+useful when they sit in the same row, like a `Search` next to a filter button.
+
+Pass `size` to `Field` to size the whole field at once: its `Label`, and any
+`Input`, `Textarea` or `TextFieldRoot` inside, read it from context unless they
+set their own `size`.
+
+## Anatomy
+
+`Input` is a family of primitives that compose, not one compound component with
+a fixed structure.
+
+| Part | Role |
+| --- | --- |
+| `Input` | The text field. Renders borderless and full-bleed when read inside `TextFieldRoot`'s context, bordered and self-sized standalone otherwise. |
+| `TextFieldRoot` | Optional wrapper that owns the border, ring, height and horizontal padding when an `Input` needs to share space with icons or buttons. |
+| `TextFieldSlot` | A leading or trailing icon/button holder inside `TextFieldRoot`. Pointer events are disabled by default, re-enabled automatically for a nested `button` or `a`. |
+| `Textarea` | Multi-line sibling. Independent of `TextFieldRoot` - always standalone. |
+| `Label` | Paired via `Field`, or manually via `htmlFor`. |
+| `Field` | Groups one `Label` and one control, wiring `id`/`aria-describedby`/`aria-invalid` between them. |
+
+`TextFieldContext` is what tells an `Input` whether it is inside a
+`TextFieldRoot` - that context switch is why `Input`'s className branches
+entirely on `inRoot` rather than on a prop.