[css-contain-3] Begin sketching out container query work-in-progress

Author: mirisuzanne

css-contain-3/Overview.bs

@@ -87,11 +87,242 @@ Strong Containment: the 'contain' property</h2>
 
 	Issue: [[css-contain-2#contain-property]]
 
+	<pre class='propdef'>
+		Name: contain
+		Value: none | strict | content | [ size || inline-size || layout || style || paint ]
+		Initial: none
+		Inherited: no
+		Applies to: See <a href="#contain-applies">below</a>
+		Computed value: the keyword ''contain/none'' or one or more of ''size'', ''inline-size'', ''layout'', ''style'', ''paint''
+		Animation type: not animatable
+	</pre>
+
+	<dl dfn-type=value dfn-for=contain>
+		<dt><dfn>inline-size</dfn>
+		<dd>
+			The value turns on <a>inline-size containment</a> for the element.
+			This ensures that the inline [=size containment box|containment box=] can be laid out
+			without needing to examine its descendants.
+	</dl>
+
+	<span id="contain-applies">This property generally applies to all elements (including [[css-pseudo-4#generated-content]])</span>,
+	although some types of containment have no effect on some elements,
+	as detailed in [[#containment-types]].
+	In addition, in the case of [[SVG2]],
+	the 'contain' property only applies to <{svg}> elements that have an associated CSS layout box.
+
+
 <h2 id='containment-types'>
 Types of Containment</h2>
 
 	Issue: [[css-contain-2#containment-types]]
 
+<h3 id='containment-inline-size'>
+Inline-Size Containment</h3>
+
+	<dfn export>inline-size containment</dfn>
+
+	Issue: Define inline-size containment, maybe as a sub-section of size containment?
+	Need feedback from implementors on what edge-cases need to be more clearly outlined here.
+
+
+<h2 id="container-query">
+Container Queries</h2>
+
+	While [=media queries=] provide a method to test aspects of the external user agent or device
+	that a document is being displayed in (such as viewport dimensions or user preferences),
+	<dfn export>container queries</dfn> allow testing aspects of elements inside the document
+	(such as box dimensions or computed styles).
+
+<h3 id="container-type">
+Creating Containers: the ''container-type'' property</h2>
+
+	<pre class='propdef'>
+		Name: container-type
+		Value: none | [ size || inline-size || block-size || style || state ]
+		Initial: none
+		Inherited: no
+		Applies to: all elements
+		Computed value: the keyword ''container-type/none'' or one or more of ''container-type/size'', ''container-type/inline-size'', ''container-type/style'', ''container-type/state''
+		Animation type: not animatable
+	</pre>
+
+	Issue: TODO: Bikeshed terms (consider "query" or "context"?)
+
+	<dl dfn-type=value dfn-for=container-type>
+		<dt><dfn>size</dfn>
+		<dd>
+			Establishes a container for dimensional queries on both the inline and block axis.
+			The user agent must change the [=used value=] of the 'contain' property
+			so as to turn on [=layout containment=], [=style containment=], and [=size containment=].
+		<dt><dfn>inline-size</dfn>
+		<dd>
+			Establishes a container for dimensional queries on the inline axis.
+			The user agent must change the [=used value=] of the 'contain' property
+			so as to turn on [=layout containment=], [=style containment=], and [=inline-size containment=].
+		<dt><dfn>block-size</dfn>
+		<dd>
+			Establishes a container for dimensional queries on the block axis.
+			The user agent must change the [=used value=] of the 'contain' property
+			so as to turn on [=layout containment=], [=style containment=], and [=block-size containment=].
+		<dt><dfn>style</dfn>
+		<dd>
+			Establishes a container for style queries.
+		<dt><dfn>state</dfn>
+		<dd>
+			Establishes a container for state queries.
+	</dl>
+
+	<div class=example>
+		Many layouts rely on external sizing for the inline axis,
+		while allowing the block axis to auto-size based on content.
+		Establishing an ''container/inline-size'' container makes that behavior explicit,
+		so that the inline-dimension can be queried,
+		without impacting normal layout of the block dimensions:
+
+		<pre class=lang-css>
+		section {
+		  container: inline-size;
+		}
+
+		h2 { font-size: 1.2em; }
+
+		@container (width > 40em) {
+		  h2 { font-size: 1.5em; }
+		}
+		</pre>
+
+		The ''em'' value is relative to the <a>computed value</a> of 'font-size'
+		on the ''section'' container.
+	</div>
+
+	<div class=example>
+		Containers can also expose computed style values for querying.
+		This can be useful for toggling behavior across multiple properties:
+
+		<pre class=lang-css>
+		section {
+		  container: style;
+		}
+
+		@container (--cards == true) {
+		  article {
+		    border: thin solid silver;
+		    border-radius: 0.5em;
+		    padding: 1em;
+		  }
+		}
+		</pre>
+	</div>
+
+
+<h3 id="container-name">
+Naming Containers: the ''container-name'' property</h2>
+
+	<pre class='propdef'>
+		Name: container-name
+		Value: none | [ <<custom-ident>> | <<string>> ]+
+		Initial: none
+		Inherited: no
+		Applies to: all elements
+		Computed value: the keyword ''container/none'' or a list of custom identifiers
+		Animation type: not animatable
+	</pre>
+
+	Issue: TODO: Bikeshed terms (consider "query" or "context"?)
+
+	<div class=example>
+		In some cases, we want to query aspects of a specific container,
+		even if it's not the nearest ancestor container.
+		For example, we might want to query the height of a main content area,
+		and the width of a more nested inline-container.
+
+		<pre class=lang-css>
+		main {
+		  container-type: size;
+		  container-name: layout;
+		}
+
+		.grid-item {
+		  container-type: inline-size;
+		  container-name: component;
+		}
+
+		@container layout (block-size > 12em) {
+		  .card { margin-block: 2em; }
+		}
+
+		@container component (inline-size > 30em) {
+		  .card { margin-inline: 2em; }
+		}
+		</pre>
+	</div>
+
+	Issue: TODO: Implicit names based on container-type?
+	Or a new syntax to query a specific container-type?
+
+
+<h3 id="container-shorthand">
+Creating Named Containers: the ''container'' shorthand</h2>
+
+	Issue: TODO: Define the container shorthand
+
+	Issue: TODO: Bikeshed terms (consider "query" or "context"?)
+
+
+<h3 id="container-rule">
+Container Queries: the ''@container'' rule</h2>
+
+	The <dfn at-rule id="at-ruledef-container">@container</dfn> rule
+	is a [=conditional group rule=] whose condition is a container query.
+
+	To parse a <dfn>&lt;container-query-list></dfn> production,
+	<a>parse a comma-separated list of component values</a>,
+	then parse each entry in the returned list as a <<container-condition>>.
+
+	The syntax of a container condition in the ''@container'' rule
+	is similar to that defined for <<media-condition>> in [[MEDIAQUERIES-4]].
+
+	The syntax of the ''@container'' rule is:
+
+	<pre class="prod def" nohighlight>
+	@container <<container-name>>? <<container-query-list>> {
+		<<stylesheet>>
+	}
+	</pre>
+
+<h3 id="dimensional-container">
+Dimensional Container Features</h2>
+
+	Issue: TODO: Width queries
+
+	Issue: TODO: Height queries
+
+	Issue: TODO: Inline queries
+
+	Issue: TODO: Block queries
+
+	Issue: TODO: Aspect-ratio queries
+
+	Issue: TODO: Orientation queries
+
+
+<h3 id="style-container">
+Style Container Features</h2>
+
+	Issue: TODO: Custom property queries
+
+	Issue: TODO: Property queries (conflict with eg min/max-width dimensional queries?)
+
+
+<h3 id="state-container">
+State Container Features</h2>
+
+	Issue: TODO: Stuck?
+
+	Issue: TODO: Visible?
+
+
 Suppressing An Element's Contents Entirely: the 'content-visibility' property {#content-visibility}
 =================