title: Layout components
shell: standard

components:
  - type: breadcrumb
    items:
      - label: Home
        href: ../index.html
      - label: Components
        href: index.html
      - label: Layout

  - type: header
    title: Layout components
    eyebrow: Reference
    subtitle: section, columns, divider, timeline, steps, progress_bar, empty_state

  # ── section ───────────────────────────────
  - type: section
    eyebrow: section
    heading: Grouping with a heading
    components:
      - type: markdown
        body: |
          A titled block of nested components. Use it to organize long pages into
          scannable chunks. `eyebrow` + `heading` optional. Nested `components:` can
          hold any components. Add `align: center | right` to align the eyebrow,
          heading, and text content within the section.

          **Anchors.** When `heading` is set, the rendered `<section>` gets an
          auto-slugged `id` (lowercase, hyphens, punctuation and emoji stripped),
          so deep-links like `/guide.html#platform-health` just work. Set
          `id: stable-name` to lock the anchor even if the heading wording
          changes. Same behavior applies to `header`.

      - type: section
        eyebrow: Example section
        heading: Platform health
        components:
          - type: stat_grid
            columns: 3
            stats:
              - label: Uptime
                value: 99.9%
                color: green
              - label: Errors
                value: "0.02%"
                color: green
              - label: Latency p95
                value: 140ms
                color: default
          - type: markdown
            body: "Everything above lives inside this section."

      - type: code
        language: yaml
        code: |
          - type: section
            eyebrow: Example section
            heading: Platform health
            components:
              - type: stat_grid
                stats: [...]
              - type: markdown
                body: "Everything above lives inside this section."

  # ── columns ───────────────────────────────
  - type: section
    eyebrow: columns
    heading: Multi-column row
    components:
      - type: markdown
        body: "Distribute components into equal-width columns. Each column is itself a list of components."

      - type: markdown
        body: "**Default** — columns stretch at the grid level, contents sit at natural height:"

      - type: columns
        columns:
          - - type: callout
              variant: info
              title: Left
              body: "Arbitrary components live inside each column."
          - - type: callout
              variant: success
              title: Center
              body: "Even widths, responsive collapse on narrow screens. One more line here so heights diverge."
          - - type: callout
              variant: warn
              title: Right
              body: "Great for comparison layouts. Extra line here. And another."

      - type: markdown
        body: "**`equal_heights: true`** — children grow to fill their column so all three look balanced:"

      - type: columns
        equal_heights: true
        columns:
          - - type: callout
              variant: info
              title: Left
              body: "Arbitrary components live inside each column."
          - - type: callout
              variant: success
              title: Center
              body: "Even widths, responsive collapse on narrow screens. One more line here so heights diverge."
          - - type: callout
              variant: warn
              title: Right
              body: "Great for comparison layouts. Extra line here. And another."

      - type: code
        language: yaml
        code: |
          - type: columns
            equal_heights: true    # default false
            columns:
              - - type: callout
                  variant: info
                  title: Left
                  body: Left content
              - - type: callout
                  variant: success
                  title: Center
                  body: Center content

  # ── timeline ──────────────────────────────
  - type: section
    eyebrow: timeline
    heading: Horizontal phase tracker
    components:
      - type: markdown
        body: "A horizontal row of phases with status indicators. Each item is `completed`, `active`, or `upcoming`. No interaction — purely visual progress."

      - type: timeline
        items:
          - name: Planning
            status: completed
          - name: Configuration
            status: completed
          - name: Optimization
            status: active
          - name: Ongoing
            status: upcoming

      - type: code
        language: yaml
        code: |
          - type: timeline
            items:
              - name: Planning
                status: completed    # completed | active | upcoming
              - name: Configuration
                status: completed
              - name: Optimization
                status: active
              - name: Ongoing
                status: upcoming

  # ── steps ─────────────────────────────────
  - type: section
    eyebrow: steps
    heading: Numbered or bulleted steps
    components:
      - type: markdown
        body: "Ordered list of cards with title + optional detail. Numbered by default; set `numbered: false` for bullets."

      - type: steps
        items:
          - title: Install the binary
            detail: Build from source with cargo build --release.
          - title: Create a site directory
            detail: Any directory of .yaml files — kazam walks it recursively.
          - title: Run dev mode
            detail: kazam dev ./my-site watches and live-reloads at localhost:3000.

      - type: code
        language: yaml
        code: |
          - type: steps
            numbered: true   # default; false for bullets
            items:
              - title: Install the binary
                detail: Build from source with cargo build --release.
              - title: Create a site directory
                detail: Any directory of .yaml files.
              - title: Run dev mode
                detail: kazam dev ./my-site

  # ── empty_state ────────────────────────────
  - type: section
    eyebrow: empty_state
    heading: Zero-data placeholder
    components:
      - type: markdown
        body: "For pages or sections that have nothing to show yet. Icon, title, description, optional CTA. Any bundled lucide icon name works in the `icon:` field."

      - type: empty_state
        title: No customers yet
        body: Add your first customer to see them here with health badges, deployment guides, and meeting agendas.
        action:
          label: Add customer
          href: "#"

      - type: empty_state
        title: All caught up
        icon: check-circle
        body: Zero open issues in this portfolio.

      - type: code
        language: yaml
        code: |
          - type: empty_state
            title: No customers yet
            body: Add your first customer to see them here.
            icon: inbox                 # any bundled lucide icon
            action:
              label: Add customer
              href: /customers/new

  - type: callout
    variant: info
    title: Next up
    body: Navigation components thread pages together — breadcrumbs on deep pages, button groups for primary CTAs.
    links:
      - label: Navigation
        href: navigation.html
        variant: primary
      - label: All components
        href: index.html
        variant: secondary
