{
  "name": "Stack",
  "source": "src/components/Stack.tsx",
  "propsType": "StackProps",
  "description": "Stack — children in a column or a row, a gap from the spacing scale\nbetween them.\n\nThe one layout primitive an agent should reach for before writing flex\nCSS: a screen built from raw `display: flex` and pixel gaps is where token\ndiscipline breaks. `gap` takes the scale's steps and nothing else.\n\nLAYOUT ONLY. It has no role and adds none; pass `as` for the element that\nmeans something. It renders on a server.",
  "import": "import { Stack } from 'ionbase-ui';",
  "status": "stable",
  "summary": "Children in a column or a row with a gap from the spacing scale between them. Reach for it before writing flex CSS; `gap` takes the scale's steps and nothing else.",
  "useWhen": [
    "laying out a group of things one after another — the sections of a page, the fields of a form, the controls of a filter row",
    "a row of controls that should wrap onto more lines on a narrow screen rather than overflow"
  ],
  "useInstead": [
    {
      "when": "the layout has columns that line up across rows — cards, stat tiles, a form in two columns",
      "use": "Grid",
      "why": "a wrapping row lines its items up per line, not across lines; a Grid keeps every row's columns the same width"
    },
    {
      "when": "a row of related controls a keyboard user should cross with the arrow keys",
      "use": "Toolbar",
      "why": "a Toolbar is one tab stop with arrow keys between its controls; a Stack is layout and leaves every control its own tab stop"
    },
    {
      "when": "two or three actions at the end of a dialog, drawer or form",
      "use": "ButtonGroup",
      "why": "it orders the primary action, and moves the rest into More actions when there is no room"
    }
  ],
  "composition": {
    "order": [
      "Stack"
    ],
    "note": "`direction` is `column` (the default) or `row`; `gap` is a step of the spacing scale — 16 by default. A row centres its children on the line and a column stretches them; `align` overrides either, `justify=\"between\"` pushes the first and last to the ends, and `wrap` lets a row break onto more lines. Pass `as` for the element that means something — `ul` for a list (its bullets and indent are removed; give each child an `li`), `nav` for links, `form`, `fieldset`. Nest Stacks for a row inside a column; each keeps its own gap. Gaps by what they separate: 4 for tight pairs (an icon and its label), 8 for controls in a row, 16 for fields and items (the default), 24 for sections of a card or panel, 32 for sections of a page.",
    "example": "<Stack gap={24}>\n  <PageHeader title=\"Agents\" />\n  <Stack direction=\"row\" wrap gap={8}>\n    <SearchField size=\"sm\" aria-label=\"Search agents\" />\n    <Select size=\"sm\" aria-label=\"Status\" options={statuses} />\n  </Stack>\n  <Table aria-label=\"Agents\">…</Table>\n</Stack>"
  },
  "variants": {
    "direction": {
      "column": {
        "use": "the default — things read top to bottom: page sections, fields, cards in a list"
      },
      "row": {
        "use": "things along a line: a filter row, a name beside its avatar, suggestions; add `wrap` when it may not fit"
      }
    }
  },
  "slots": {
    "children": {
      "accepts": "any",
      "note": "laid out in order; `li` children when `as` is `ul` or `ol`"
    }
  },
  "a11y": {
    "guarantees": [
      "layout only: it adds no role, so the element given by `as` — or the children — carry the meaning",
      "the visual order is the DOM order: no `order` or reversed direction that would make reading and tabbing disagree",
      "a row's children shrink to fit, so text wraps or is cut rather than pushing the row past the screen's edge",
      "`as=\"ul\"` stays a list to a screen reader while losing its bullets"
    ],
    "requires": [
      "`as` for a group that means something — a list, navigation, a form — rather than a div"
    ],
    "notes": [
      "It renders on a server. A gap off the spacing scale is a type error, not a style."
    ]
  },
  "antiPatterns": [
    {
      "dont": "a hand-written `display: flex` with a pixel gap",
      "do": "Stack with a `gap` step",
      "why": "a gap outside the scale is the first place a screen drifts off the tokens, and nothing catches it"
    },
    {
      "dont": "wrapping a single child in a Stack",
      "why": "a gap between one thing and nothing is no layout at all — the Stack is noise in the tree"
    },
    {
      "dont": "a Stack of cards that should line up in columns",
      "do": "Grid",
      "why": "a wrapping row sizes each line on its own, so the columns never line up"
    },
    {
      "dont": "reversing a row with CSS to put the primary action last",
      "why": "the visual order and the tab order then disagree — write the children in the order they are read"
    }
  ],
  "stylesheet": "src/styles/stack.css",
  "tokens": [
    "--ion-stack-gap",
    "--spacing-0",
    "--spacing-12",
    "--spacing-16",
    "--spacing-2",
    "--spacing-20",
    "--spacing-24",
    "--spacing-32",
    "--spacing-4",
    "--spacing-40",
    "--spacing-48",
    "--spacing-6",
    "--spacing-64",
    "--spacing-8"
  ],
  "props": {
    "direction": {
      "type": "StackDirection | undefined",
      "required": false,
      "origin": "own",
      "description": "`column` stacks top to bottom — the default; `row` runs along the line.",
      "values": [
        "row",
        "column"
      ]
    },
    "gap": {
      "type": "StackGap | undefined",
      "required": false,
      "origin": "own",
      "description": "Space between the children, from the spacing scale. Defaults to 16."
    },
    "align": {
      "type": "StackAlign | undefined",
      "required": false,
      "origin": "own",
      "description": "Cross-axis alignment. Defaults to `stretch` in a column, `center` in a row.",
      "values": [
        "start",
        "center",
        "end",
        "stretch",
        "baseline"
      ]
    },
    "justify": {
      "type": "StackJustify | undefined",
      "required": false,
      "origin": "own",
      "description": "Main-axis distribution. `between` pushes the first and last to the ends.",
      "values": [
        "start",
        "center",
        "end",
        "between"
      ]
    },
    "wrap": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Let a row wrap onto more lines instead of overflowing."
    },
    "as": {
      "type": "StackElement | undefined",
      "required": false,
      "origin": "own",
      "description": "The element: a list of things is a `ul`, a group of navigation links a\n`nav`. Stack is layout only — the element carries the meaning.",
      "values": [
        "form",
        "div",
        "span",
        "section",
        "nav",
        "ul",
        "ol",
        "li",
        "header",
        "footer",
        "fieldset"
      ]
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own"
    }
  },
  "propCounts": {
    "own": 7,
    "aria": 0,
    "dom": 277,
    "other": 0
  }
}