Slot Children Access API for Astro Components

[RATIU5]

Body

Summary

Enable programmatic access to slotted content structure in Astro components through a new children() API method, allowing people to analyze and manipulate child components and their slot hierarchy before rendering.

Background & Motivation

Currently, Astro slots provide an elegant way to pass content between components, but it lack programmatic introspection capabilities. While Astro.slots.render() allows rendering slot content to a string HTML of the slot contents, we'll use Astro.slots.render('default'), developers cannot analyze the structure of slotted content before rendering. This limitation makes it difficult to implement complex component patterns that require knowledge of child components and their attributes.

Many UI framework patterns, particularly in form controls and compound components, need to understand their children's structure. For example, custom select components often need to traverse their child options to build both a visible UI and a corresponding native <select> element for form submission. Current workarounds involve either using props (which may not meet design requirements) or parsing rendered HTML (which is inefficient and error-prone).

I've had difficulties with:

• Building compound components that need to understand their child structure
• Implementing progressive enhancement patterns that require multiple renderings of the same data
• Creating component libraries with complex parent-child relationships
• Accessing metadata about nested slots for dynamic behavior

Goals

• Provide a programmatic API to access slot content structure without rendering to HTML
• Enable inspection of child components, their types, props, and nested slots
• Support both named and default slot access
• Allow for analysis of deeply nested slot hierarchies
• Facilitate progressive enhancement patterns by allowing multiple interpretations of slot content
• Support both static site generation and server-side rendering modes
• Ensure compatibility with existing slot features like fallback content

Example

The proposed API introduces a children() method that accepts Astro.slots as an argument and returns a structured representation of the slotted content:

---
const slotChildren = children(Astro.slots);
// or 
const slotChildren = Astro.children();

// Result structure:
// {
//   children: [
//     {
//       isAstroComponentFactory: true,
//       moduleId: "path/to/component.astro",
//       propagation: undefined,
//       slotName: "slot1",
//       props: {},
//       children: [
//         {
//           isAstroComponentFactory: true,
//           moduleId: "path/to/other/component.astro",
//           propagation: undefined,
//           slotName: "slot2",
//           props: {},
//           children: undefined
//         }
//       ]
//     }
//   ]
// }
---

Consider a custom combobox component that requires both a visible dropdown and a hidden <select> element for form submission:

---
const slotChildren = children(Astro.slots);

const options = [];
const groups = [];

slotChildren.children.forEach(child => {
  if (child.moduleId.endsWith('Combobox.Option.astro')) {
    options.push({
      value: child.props.value,
      label: child.props.label
    });
  } else if (child.moduleId.endsWith('Combobox.Group.astro')) {
    const groupOptions = child.children.filter(
      subChild => subChild.moduleId.endsWith('Combobox.Option.astro')
    );
    groups.push({
      label: child.props.label,
      options: groupOptions.map(opt => ({
        value: opt.props.value,
        label: opt.props.label
      }))
    });
  }
});
---

<div class="combobox">
  <!-- Render the visible UI structure -->
  <slot />
  
  <!-- Create a hidden select for form submission -->
  <select hidden>
    {options.map(opt => (
      <option value={opt.value}>{opt.label}</option>
    ))}
    {groups.map(group => (
      <optgroup label={group.label}>
        {group.options.map(opt => (
          <option value={opt.value}>{opt.label}</option>
        ))}
      </optgroup>
    ))}
  </select>
</div>

Usage with nested slots:

---
// Page.astro
---
<MyComponent>
  <Fragment slot="slot1">
    <Fragment slot="slot2">
      <p>Hello, World</p>
    </Fragment>
  </Fragment>
</MyComponent>

Optional auto-generated slot names:

---
// With auto-generated names, the system would assign internal IDs
// e.g., _slot_0, _slot_1, etc.
---
<MyComponent>
  <Fragment>
    <Fragment>
      <p>Hello, World</p>
    </Fragment>
  </Fragment>
</MyComponent>

The API would work with existing Astro features:

• Respecting slot fallback content behavior Fallback content will only be displayed when there are no matching elements with the slot="name" attribute being passed in to a named slot
• Supporting component factories and framework components
• Maintaining the server-side rendering nature of Astro components

If there's already a solution to do this without explicit use of props, I'm all ears.