
package com.smartgwt.client.docs;

/**
 * <h3>Embedded Components in Contents</h3>
 * Smart GWT's {@link com.smartgwt.client.widgets.layout.Layout} and its subclasses provide a
 * powerful
 *  layout engine, but some designs are more naturally expressed with CSS
 *  &mdash; for example, CSS flexbox with <code>gap</code> and
 *  <code>flex-wrap</code>, CSS grid with named
 *  <code>grid-template-areas</code>, or a page where Smart GWT widgets are
 *  interspersed with static HTML such as headings, paragraphs, and images.
 *  <p>
 *  <b>Embedded components in contents</b> bridge this gap: you provide an
 * HTML template as {@link com.smartgwt.client.widgets.Canvas#getContents Canvas.contents} (a
 * plain string, as it has always
 *  been), and mark slots for Smart GWT widgets using the <code>scID</code>
 *  attribute on placeholder elements.  The CSS in the template controls all
 *  layout and sizing; the framework takes care of connecting widgets to the
 *  placeholders at draw time.
 *  <p>
 *  <h4>Basic Usage</h4>
 *  <p>
 *  Place one or more elements with an <code>scID</code> attribute in the
 * {@link com.smartgwt.client.widgets.Canvas#getContents Canvas.contents} string.  Each
 * <code>scID</code> value identifies a
 *  child component by <i>name</i> &mdash; either a child already present in
 * the {@link com.smartgwt.client.widgets.Canvas#getChildren Canvas.children} array (matched by
 * {@link com.smartgwt.client.widgets.Canvas#getName Canvas.name}), or an
 *  {@link autoChildren AutoChild} that will be created automatically if
 *  the corresponding <code>*Defaults</code> / <code>*Constructor</code>
 *  properties exist on the Canvas.
 *  <p>
 *  After the contents HTML is inserted into the DOM at draw time, the
 *  framework scans for <code>scID</code> placeholders, resolves each one to a
 *  child or AutoChild, and connects the widget to the placeholder element via
 * {@link com.smartgwt.client.widgets.Canvas#getHtmlElement Canvas.htmlElement} and {@link
 * com.smartgwt.client.widgets.Canvas#getMatchElement Canvas.matchElement}.  The widget
 *  renders inside the placeholder and sizes itself to match it, so the HTML's
 *  CSS rules control all layout and sizing.
 *  <p>
 *  <h4>Example: Mixing HTML and Smart GWT Widgets</h4>
 *  <p>
 *  The most common use case is a page section that mixes static HTML content
 *  (headings, text, images) with Smart GWT widgets:
 *  <pre>
 *  isc.Canvas.create({
 *      width: "100%", height: "100%",
 *      overflow: "auto",
 *      contents:
 *          '&lt;h2&gt;Employee Directory&lt;/h2&gt;' +
 *          '&lt;p&gt;Select a row to see details.&lt;/p&gt;' +
 *          '&lt;div scID="mainGrid"' +
 *          '     style="height:400px"&gt;&lt;/div&gt;' +
 *          '&lt;footer style="margin-top:10px;' +
 *          '     color:#888"&gt;&amp;copy; 2026 Acme&lt;/footer&gt;',
 *      mainGridDefaults: {
 *          _constructor: "ListGrid",
 *          autoFetchData: true,
 *          dataSource: "employees"
 *      }
 *  });
 *  </pre>
 *  The <code>&lt;h2&gt;</code>, <code>&lt;p&gt;</code>, and
 *  <code>&lt;footer&gt;</code> are ordinary HTML rendered by the browser.
 *  The <code>mainGrid</code> AutoChild fills the 400px-tall placeholder.
 *  Because the child is <code>position:relative</code> inside the content
 *  flow, the entire Canvas scrolls naturally when
 *  {@link com.smartgwt.client.widgets.Canvas#getOverflow overflow} is <code>"auto"</code>.
 *  <p>
 *  As with all AutoChildren, the created component is accessible as an
 *  instance property on the parent &mdash; in this case,
 *  <code>this.mainGrid</code>.  See {@link autoChildren AutoChildren}
 *  for details.
 *  <p>
 *  <h4>Example: CSS Flexbox</h4>
 *  <p>
 *  <pre>
 *  isc.Canvas.create({
 *      width: "100%", height: "100%",
 *      contents:
 *          '&lt;div style="display:flex; gap:10px;' +
 *          '     height:100%"&gt;' +
 *              '&lt;div scID="mainGrid"' +
 *              '     style="flex:1"&gt;&lt;/div&gt;' +
 *              '&lt;div scID="detail"' +
 *              '     style="width:300px"&gt;&lt;/div&gt;' +
 *          '&lt;/div&gt;',
 *      mainGridDefaults: {
 *          _constructor: "ListGrid",
 *          autoFetchData: true,
 *          dataSource: "employees"
 *      },
 *      detailDefaults: {
 *          _constructor: "DetailViewer",
 *          dataSource: "employees"
 *      }
 *  });
 *  </pre>
 *  The CSS <code>flex</code> rules control the split between the grid and
 *  the detail viewer.
 *  <p>
 *  <h4>Example: CSS Grid with Named Areas</h4>
 *  <p>
 *  CSS Grid's <code>grid-template-areas</code> is a particularly natural
 *  fit for <code>scID</code>, since both use names to identify regions:
 *  <pre>
 *  isc.Canvas.create({
 *      width: "100%", height: "100%",
 *      contents:
 *          '&lt;div style="display:grid; height:100%;' +
 *          '     grid-template-columns: 1fr 300px;' +
 *          '     grid-template-rows: auto 1fr auto;' +
 *          '     grid-template-areas:' +
 *          "     'header header'" +
 *          "     'grid   detail'" +
 *          "     'footer footer';" +
 *          '     gap: 8px"&gt;' +
 *          '&lt;h2 style="grid-area:header;' +
 *          '     margin:0"&gt;Dashboard&lt;/h2&gt;' +
 *          '&lt;div scID="mainGrid"' +
 *          '     style="grid-area:grid"&gt;&lt;/div&gt;' +
 *          '&lt;div scID="detail"' +
 *          '     style="grid-area:detail"&gt;&lt;/div&gt;' +
 *          '&lt;div style="grid-area:footer;' +
 *          '     text-align:center;' +
 *          '     color:#888"&gt;Status bar&lt;/div&gt;' +
 *          '&lt;/div&gt;',
 *      mainGridDefaults: {
 *          _constructor: "ListGrid",
 *          autoFetchData: true,
 *          dataSource: "employees"
 *      },
 *      detailDefaults: {
 *          _constructor: "DetailViewer",
 *          dataSource: "employees"
 *      }
 *  });
 *  </pre>
 *  The header and footer are plain HTML; the grid and detail areas are
 *  Smart GWT widgets sized by the CSS grid engine.
 *  <p>
 *  <h4>Example: Explicit Children</h4>
 *  <p>
 *  Instead of AutoChildren, pre-created children can be supplied in the
 * {@link com.smartgwt.client.widgets.Canvas#getChildren Canvas.children} array.  Each child's
 * {@link com.smartgwt.client.widgets.Canvas#getName Canvas.name} must match
 *  the corresponding <code>scID</code>:
 *  <pre>
 *  isc.Canvas.create({
 *      width: "100%", height: "100%",
 *      contents:
 *          '&lt;div style="display:flex; gap:10px;' +
 *          '     height:100%"&gt;' +
 *              '&lt;div scID="gridArea"' +
 *              '     style="flex:1"&gt;&lt;/div&gt;' +
 *              '&lt;div scID="chartArea"' +
 *              '     style="flex:1"&gt;&lt;/div&gt;' +
 *          '&lt;/div&gt;',
 *      children: [
 *          isc.ListGrid.create({
 *              name: "gridArea",
 *              autoDraw: false,
 *              dataSource: "employees",
 *              autoFetchData: true
 *          }),
 *          isc.FacetChart.create({
 *              name: "chartArea",
 *              autoDraw: false,
 *              facets: [{ id: "region" }],
 *              dataSource: "employees",
 *              autoFetchData: true
 *          })
 *      ]
 *  });
 *  </pre>
 *  <p>
 *  <h4>How It Works</h4>
 *  <p>
 *  The framework processes <code>scID</code> placeholders during
 *  {@link com.smartgwt.client.widgets.Canvas#draw Canvas.draw()}, between HTML insertion and
 * {@link com.smartgwt.client.widgets.Canvas#getDrawChildren drawChildren()}.  For each
 * <code>scID</code>
 *  found in the DOM:
 *  <ol>
 * <li>The name is resolved to an existing child (by {@link
 * com.smartgwt.client.widgets.Canvas#getName Canvas.name}) or
 *      an AutoChild (via  Canvas.addAutoChild()).  If neither resolves,
 *      a warning is logged and the placeholder is left empty.
 *  <li>The child is connected to the placeholder element with
 * {@link com.smartgwt.client.widgets.Canvas#getHtmlElement Canvas.htmlElement} set to the
 * placeholder,
 * {@link com.smartgwt.client.widgets.Canvas#getHtmlPosition Canvas.htmlPosition} set to
 * <code>"afterBegin"</code>, and
 * {@link com.smartgwt.client.widgets.Canvas#getMatchElement Canvas.matchElement} set to
 * <code>true</code>.  This causes the
 *      widget to render inside the placeholder and size itself to match.
 *  <li>The child draws in the normal
 *      {@link com.smartgwt.client.widgets.Canvas#getDrawChildren drawChildren()} pass.
 *  </ol>
 *  Because the child is rendered <code>position:relative</code> inside the
 *  placeholder, it participates in normal document flow.  The placeholder's
 *  CSS (width, height, flex, grid-area, etc.) controls the widget's size and
 * position, and {@link com.smartgwt.client.widgets.Canvas#getPersistentMatchElement
 * Canvas.persistentMatchElement} ensures the widget
 *  tracks the placeholder through subsequent page reflows.
 *  <p>
 *  <h4>Scrolling and Responsive Behavior</h4>
 *  <p>
 *  Because embedded children are <code>position:relative</code> within the
 *  contents, they scroll naturally with the rest of the content when
 * {@link com.smartgwt.client.widgets.Canvas#getOverflow overflow} is set to <code>"auto"</code>
 * or
 *  <code>"scroll"</code>.  This is a key difference from Smart GWT's
 *  Layout system, which uses absolute positioning internally.
 *  <p>
 *  CSS media queries, <code>flex-wrap</code>, and other responsive techniques
 *  work as expected &mdash; when the browser reflows the template (for
 * example, due to a viewport resize), {@link
 * com.smartgwt.client.widgets.Canvas#getPersistentMatchElement Canvas.persistentMatchElement}
 *  detects the placeholder's new size and automatically resizes the embedded
 *  widget to match.
 *  <p>
 *  <h4>Dynamic Contents</h4>
 *  <p>
 * {@link com.smartgwt.client.widgets.Canvas#getDynamicContents Dynamic contents}
 * (<code>${}</code>
 *  expressions) can be combined with <code>scID</code> placeholders.  The
 *  <code>${}</code> expressions are evaluated first, producing the final HTML
 *  string, and then the framework scans the resulting DOM for <code>scID</code>
 *  attributes.  This allows the template itself to be data-driven while still
 *  embedding Smart GWT components.
 *  <p>
 *  <h4>Visibility</h4>
 *  <p>
 * When an embedded child is hidden (via {@link com.smartgwt.client.widgets.Canvas#hide
 * Canvas.hide()},
 * {@link com.smartgwt.client.widgets.Canvas#getVisibleWhen Canvas.visibleWhen}, etc.), the
 * child's DOM handle becomes invisible
 *  but the <code>scID</code> placeholder element is unaffected &mdash; it
 *  retains whatever size and position the CSS template gives it.  This follows
 * the existing {@link com.smartgwt.client.widgets.Canvas#getMatchElement Canvas.matchElement}
 * contract: the framework controls
 *  the widget; the CSS template controls the placeholder.
 *  <p>
 *  If a design requires the placeholder to collapse when the child is hidden
 *  (for example, so that flex siblings expand to fill the vacated space), this
 *  can be achieved by toggling the placeholder's own CSS from application code
 *  &mdash; for instance, setting <code>display:none</code> on the placeholder
 * in a {@link com.smartgwt.client.widgets.Canvas#addVisibilityChangedHandler
 * Canvas.visibilityChanged()} override.
 *  <p>
 *  <h4>Redraw Behavior</h4>
 *  <p>
 *  When a Canvas with <code>scID</code> placeholders is redrawn (e.g., via
 * {@link com.smartgwt.client.widgets.Canvas#setContents Canvas.setContents()} or {@link
 * com.smartgwt.client.widgets.Canvas#markForRedraw Canvas.markForRedraw()}), the
 *  framework preserves embedded children using a detach-and-reattach
 *  strategy:
 *  <ol>
 *  <li>Each embedded child's DOM handle is detached from its placeholder
 *      (without destroying the widget).
 *  <li>The contents HTML is replaced in the DOM.
 *  <li>The DOM is re-scanned for <code>scID</code> placeholders.
 *  <li>Children already connected to an <code>scID</code> are reattached to
 *      the corresponding new placeholder element without re-resolving.
 *  </ol>
 *  If a placeholder that previously existed is absent after redraw, the
 * corresponding child is {@link com.smartgwt.client.widgets.Canvas#clear cleared} but not
 * destroyed,
 *  allowing it to be reconnected if the placeholder reappears in a subsequent
 *  redraw.  Conversely, if a new <code>scID</code> appears that was not in
 * the previous contents, {@link com.smartgwt.client.widgets.Canvas#resolveContentsComponent
 * Canvas.resolveContentsComponent()} is called
 *  to resolve it, including AutoChild creation if applicable.
 *  <p>
 * For {@link com.smartgwt.client.widgets.Canvas#getHtmlPosition Canvas.htmlPosition} variants
 * where the child is absolutely
 *  positioned over (rather than inside) the placeholder, a
 * {@link com.smartgwt.client.widgets.Canvas#clear clear()} / {@link
 * com.smartgwt.client.widgets.Canvas#draw draw()} cycle is used
 *  instead of detach/reattach, because the child's position depends on
 *  coordinates that must be recalculated.
 *  <p>
 *  <h4>Layout Interaction</h4>
 *  <p>
 * When <code>scID</code> placeholders are used in a {@link
 * com.smartgwt.client.widgets.layout.Layout} or
 *  its subclasses (VLayout, HLayout, etc.), embedded children are positioned
 *  by the CSS template, <i>not</i> by the Layout engine.  These children are
 * part of the {@link com.smartgwt.client.widgets.Canvas#getChildren Canvas.children} array but
 * are not added as
 * {@link com.smartgwt.client.widgets.layout.Layout#getMembers Layout.members}, so {@link
 * com.smartgwt.client.widgets.layout.Layout#layoutChildren Layout.layoutChildren()} does not
 * attempt
 *  to size or position them.
 *  <p>
 *  <h4>Restrictions</h4>
 *  <ul>
 *  <li><code>scID</code> resolution is local to the owning Canvas.  A
 *      placeholder cannot reference a widget that is not a child or
 *      AutoChild of the Canvas whose contents contains the placeholder.
 *  <li>A given <code>scID</code> value must be unique within a single
 *      Canvas's contents.
 *  <li>The placeholder element should be a block-level element (typically a
 *      <code>&lt;div&gt;</code>).  Using inline elements may produce
 *      unexpected sizing behavior.
 * <li>Embedded children should not also be added as {@link
 * com.smartgwt.client.widgets.layout.Layout#getMembers Layout.members}
 *      of the same Canvas.
 * <li>Embedded children are normal {@link com.smartgwt.client.widgets.Canvas#getChildren
 * Canvas.children} and follow
 *      standard child lifecycle &mdash; they are destroyed when the parent
 *      is {@link com.smartgwt.client.widgets.Canvas#destroy destroyed}.
 *  </ul>
     * @see com.smartgwt.client.widgets.Canvas#getContents
     * @see com.smartgwt.client.widgets.Canvas#getHtmlElement
     * @see com.smartgwt.client.widgets.Canvas#getMatchElement
     * @see com.smartgwt.client.docs.AutoChildren
 * @see com.smartgwt.client.widgets.Canvas#resolveContentsComponent
 * @see com.smartgwt.client.widgets.Canvas#contentsComponentConnected
 * @see com.smartgwt.client.widgets.Canvas#getContentsComponentDefaults
 */
public interface ContentsEmbeddedComponents {
}
