docs(site): join composition guides. remove layouts (#1727)

packages/docs/pages/guides/_meta.json

@@ -1,6 +1,5 @@
 {
   "getting-started": "Getting Started",
-  "layouts": "Layouts",
   "state-management": "State Management",
   "styling": "Styling",
   "composition": "Composition",

packages/docs/pages/guides/composition/extending-behavior.mdx → packages/docs/pages/guides/composition.mdx

@@ -1,3 +1,9 @@
+# Composition
+
+Sometimes it might be necessary to use the behaviour of a component on another one. For example you might need a button to behave as a link, or you might want a `div` with some component's functionality. Composable components are made to enable that.
+
+In Shoreline the concept of "composable" components are those that support a boolean property called `asChild`. When set to `true`, this property enables the component to extend its behavior to its child components. That allows the component to keep it's original features, but render as something different.
+
 ## Extending Component Behavior
 
 Composable components, by definition, possess a prop named `asChild`. When this property is set to `true`, it alters the behavior of the component. Instead of rendering in the usual manner, it renders its `children` and injects its internal props into them.
@@ -35,6 +41,31 @@ function ComposabilityExample() {
 }
 ```
 
+## Requirements for Child Components
+
+To be cloned and extended, custom components must be extensible. All components in Shoreline adhere to this requirement and can be used as children for composable components. The criteria for a component to be extensible include:
+
+1. Forward a Ref: Components need to forward a [ref](https://react.dev/reference/react/forwardRef).
+2. Forward Received Props: Components must forward the props they receive.
+
+### Extensible Component Example
+
+Here is an example of an extensible component:
+
+```
+const CustomComponent = forwardRef((props, ref) => {
+  const { name, ...otherProps } = props
+
+  return (
+    <div {...otherProps} ref={ref}>
+      {name}
+    </div>
+  )
+})
+```
+
+This component successfully forwards a ref and ensures that all received props are also forwarded. This adherence to extensibility makes it compatible as a child for composable components in the Shoreline library.
+
 ## Availability in Shoreline
 
 ### Not all components are composable