Technical review: Document anchored container queries (mdn#42710)

* Document anchored container queries

* Correct descriptor name error on the @container page

* Add list of descriptor links to @container link on module page

* Apply suggestions from code review - fix links and obvious typos.

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

* Fixes for Hamish review comments

* Add note, plus a couple of Claude fixes

---------

Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Author: chrisdavidmills

files/en-us/web/css/guides/anchor_positioning/anchored_container_queries/index.md

@@ -3,7 +3,9 @@ title: CSS anchor positioning
 short-title: Anchor positioning
 slug: Web/CSS/Guides/Anchor_positioning
 page-type: css-module
-spec-urls: https://drafts.csswg.org/css-anchor-position-1/
+spec-urls:
+  - https://drafts.csswg.org/css-anchor-position-1/
+  - https://drafts.csswg.org/css-anchor-position-2/
 sidebar: cssref
 ---
 
@@ -63,6 +65,9 @@ In addition, the specification provides CSS-only mechanisms to:
 - [Fallback options and conditional hiding for overflow](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Try_options_hiding)
   - : A guide to the mechanisms CSS anchor positioning provides to prevent anchor-positioned elements from overflowing their containing elements or the viewport, including position try fallback options and conditionally hiding elements.
 
+- [Using anchored container queries](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries)
+  - : Explains how to use anchored container queries to conditionally apply styles to anchor-positioned elements depending on what position try fallback options are active on them.
+
 ## Related concepts
 
 - [CSS logical properties and values](/en-US/docs/Web/CSS/Guides/Logical_properties_and_values) module:

files/en-us/web/css/guides/anchor_positioning/index.md

@@ -374,6 +374,39 @@ Scroll the page and check out the effect of these position-try fallback options
 
 {{ EmbedLiveSample("Custom fallback options", "100%", "250") }}
 
+## Styling anchor-positioned elements based on active fallback
+
+One problem the above functionality doesn't solve is updating the styling of an anchor-positioned element to suit its different fallback options. For example, it is common to include a small arrow on a tooltip that points to the anchor element it is associated with, improving UX by making the visual association clearer. When the tooltip moves to a different position, you'll need to change the position and orientation of the arrow, otherwise it will look wrong.
+
+To solve this problem, you can use anchored container queries. These extend the functionality of [CSS container queries](/en-US/docs/Web/CSS/Guides/Containment/Container_queries) to enable you to detect when a specific fallback option is applied to an anchor-positioned element, and apply CSS to its descendants as a result. Specifically, anchored container queries rely on two features:
+
+- The {{cssxref("container-type")}} property `anchored` value: Apply this to the anchor-positioned element to start detecting when different fallback options are applied to it.
+- The {{cssxref("@container")}} at-rule `anchored` keyword: This is followed by a set of parentheses inside which the `fallback` descriptor is included. The descriptor's value is a `position-try-fallbacks` value.
+
+For example, let's say we have an anchor-positioned tooltip element that is positioned above its anchor by default via a {{cssxref("position-area")}} value of `top`, but has a {{cssxref("position-try-fallbacks")}} value of `flip-block` specified. This will cause the tooltip to flip in the block direction to the bottom of its anchor when it starts to overflow the top of the viewport. If we want to detect when the fallback is applied to the tooltip, we first need to set `container-type: anchored` on it to turn it into an anchored query container.
+
+```css
+.tooltip {
+  position: absolute;
+  position-anchor: --myAnchor;
+  position-area: top;
+  position-try-fallbacks: flip-block;
+  container-type: anchored;
+}
+```
+
+With this in place, we can now write a container query like so:
+
+```css
+@container anchored(fallback: flip-block) {
+  /* Descendant styles here */
+}
+```
+
+The query test — `anchored(fallback: flip-block)` — will return true when the `flip-block` fallback option is applied to the tooltip, in which case the styles specified within the `@container` block will be applied. You might for example want to change the position and orientation of the arrow icon so that it continues to point towards the anchor, change the direction of a gradient, etc.
+
+For more information on anchored container queries and some examples, see [Using anchored container queries](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries).
+
 ## Using `position-try-order`
 
 The {{cssxref("position-try-order")}} property has a slightly different focus to the rest of the position try functionality, in that it makes use of position try fallback options when the positioned element is first displayed, rather than when it is in the process of overflowing.

files/en-us/web/css/guides/anchor_positioning/try_options_hiding/index.md

@@ -33,16 +33,28 @@ There are plans to further extend possible queries by adding the generalized con
 ### At-rules and descriptors
 
 - {{cssxref("@container")}}
+  - [`aspect-ratio`](/en-US/docs/Web/CSS/Reference/At-rules/@container#aspect-ratio)
+  - [`block-size`](/en-US/docs/Web/CSS/Reference/At-rules/@container#block-size)
+  - [`fallback`](/en-US/docs/Web/CSS/Reference/At-rules/@container#fallback)
+  - [`height`](/en-US/docs/Web/CSS/Reference/At-rules/@container#height)
+  - [`inline-size`](/en-US/docs/Web/CSS/Reference/At-rules/@container#inline-size)
+  - [`orientation`](/en-US/docs/Web/CSS/Reference/At-rules/@container#orientation)
+  - [`scrollable`](/en-US/docs/Web/CSS/Reference/At-rules/@container#scrollable)
+  - [`snapped`](/en-US/docs/Web/CSS/Reference/At-rules/@container#snapped)
+  - [`stuck`](/en-US/docs/Web/CSS/Reference/At-rules/@container#stuck)
+  - [`width`](/en-US/docs/Web/CSS/Reference/At-rules/@container#width)
 - {{cssxref("@media")}}
 - {{cssxref("@supports")}}
 
 The CSS conditional rules module also introduces the `@else` and `@when` at-rules. Currently, no browsers support these features.
 
 ### Functions
 
+- [`anchored()`](/en-US/docs/Web/CSS/Reference/At-rules/@container#anchored_container_descriptors)
 - [`style()`](/en-US/docs/Web/CSS/Reference/At-rules/@container#container_style_queries)
 - [`font-tech()`](/en-US/docs/Web/CSS/Reference/At-rules/@supports#font-tech)
 - [`font-format()`](/en-US/docs/Web/CSS/Reference/At-rules/@supports#font-format)
+- [`scroll-state()`](/en-US/docs/Web/CSS/Reference/At-rules/@container#scroll-state_container_descriptors)
 - [`selector()`](/en-US/docs/Web/CSS/Reference/At-rules/@supports#function_syntax)
 - [`supports()`](/en-US/docs/Web/CSS/Reference/At-rules/@import#supports-condition)
 
@@ -116,6 +128,9 @@ The CSS conditional rules module also introduces a `media()` CSS function. Curre
 - [CSS namespaces](/en-US/docs/Web/CSS/Guides/Namespaces) module
   - {{cssxref("@namespace")}} at-rule
 
+- [CSS anchor positioning](/en-US/docs/Web/CSS/Guides/Anchor_positioning) module
+  - [Using anchored container queries](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries)
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/css/guides/conditional_rules/index.md

@@ -11,10 +11,11 @@ Container queries enable you to apply styles to an element based on certain attr
 - The container's size.
 - Styles applied to the container.
 - The container's scroll-state or that of its scrolling ancestor.
+- Whether the container is [anchor-positioned](/en-US/docs/Web/CSS/Guides/Anchor_positioning) and has a [position-try fallback option](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Try_options_hiding) applied to it.
 
 Container queries are an alternative to [media queries](/en-US/docs/Web/CSS/Guides/Media_queries), which apply styles to elements based on viewport size or other device characteristics.
 
-This article provides an introduction to using container queries, specifically focusing on size container queries. Other guides discuss [style](/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries#container_style_queries) and [scroll-state](/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries) container queries in detail.
+This article provides an introduction to using container queries, specifically focusing on size container queries. Other guides discuss [style](/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries#container_style_queries), [scroll-state](/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries), and [anchored](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries) container queries in detail.
 
 ![Two different query types. First, a media query based on the viewport's width, which is the full width of the browser. Second, a container query based on the width of a container element.](container-query.svg)
 
@@ -174,6 +175,7 @@ If you want to use a single-column layout for devices with a smaller viewport, y
 - CSS {{cssxref("content-visibility")}} property
 - [Using container size and style queries](/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries)
 - [Using container scroll-state queries](/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries)
+- [Using anchored container queries](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries)
 - [Say Hello to CSS Container Queries](https://ishadeed.com/article/say-hello-to-css-container-queries/) by Ahmad Shadeed
 - [Container Queries: a Quick Start Guide](https://www.oddbird.net/2021/04/05/containerqueries/)
 - [Collection of Container Queries articles](https://github.com/sturobson/Awesome-Container-Queries)

files/en-us/web/css/guides/containment/container_queries/index.md

@@ -3,12 +3,15 @@ title: "@container"
 slug: Web/CSS/Reference/At-rules/@container
 page-type: css-at-rule
 browser-compat: css.at-rules.container
+spec-urls:
+  - https://drafts.csswg.org/css-conditional-5/#container-type
+  - https://drafts.csswg.org/css-anchor-position-2/#container-rule-anchored
 sidebar: cssref
 ---
 
 The **`@container`** [CSS](/en-US/docs/Web/CSS) [at-rule](/en-US/docs/Web/CSS/Guides/Syntax/At-rules) is a conditional group rule that applies styles to a [containment context](/en-US/docs/Web/CSS/Guides/Containment/Container_queries#naming_containment_contexts).
 Style declarations are filtered by a condition and applied to the container if the condition is true.
-The condition is evaluated when the queried container size, [`<style-feature>`](#container_style_queries), or scroll-state changes.
+The condition is evaluated when the queried container size, [`<style-feature>`](#container_style_queries), scroll-state, or state of the applied [position-try fallback](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Try_options_hiding) (in the case of [anchor-positioned](/en-US/docs/Web/CSS/Guides/Anchor_positioning) containers) changes.
 
 The condition must specify one or both of {{cssxref("container-name")}} and `<container-query>`.
 
@@ -48,6 +51,15 @@ If no `<container-query>` is specified, named containers are selected.
   }
 }
 
+/* With an anchored query */
+@container anchored(fallback: bottom) {
+  .infobox::before {
+    content: "▲";
+    bottom: 100%;
+    top: auto;
+  }
+}
+
 /* With a <container-name> and a <scroll-state> */
 @container sticky-heading scroll-state(stuck: top) {
   h2 {
@@ -79,7 +91,7 @@ If no `<container-query>` is specified, named containers are selected.
     - `<container-name>` {{optional_inline}}
       - : The name of the container that the styles will be applied to when the query evaluates to `true`, specified as an {{cssxref("ident")}}.
     - `<container-query>` {{optional_inline}}
-      - : A set of features that are evaluated against the query container when the size, [`<style-feature>`](#container_style_queries), or scroll-state of the container changes.
+      - : A set of features that are evaluated against the query container when the size, [`<style-feature>`](#container_style_queries), scroll-state, or applied position-try fallback of the container changes.
 
 ### Logical keywords in container queries
 
@@ -134,7 +146,7 @@ Details about usage and naming restrictions are described in the {{cssxref("cont
 
 ### Descriptors
 
-The `<container-condition>` queries include [size](#size_container_descriptors) and [scroll-state](#scroll-state_container_descriptors) container descriptors.
+The `<container-condition>` queries include [size](#size_container_descriptors), [scroll-state](#scroll-state_container_descriptors), and [anchored](#anchored_container_descriptors) container descriptors.
 
 #### Size container descriptors
 
@@ -172,7 +184,7 @@ The `<container-condition>` can include one or more boolean size queries, each w
 
 #### Scroll-state container descriptors
 
-Scroll-state container descriptors are specified inside the `<container-condition>` within a set of parentheses following the `scroll-state` keyword, for example:
+Scroll-state container descriptors are specified inside the `<container-condition>` as an argument for the `scroll-state()` function, for example:
 
 ```css
 @container scroll-state(scrollable: top) {
@@ -319,7 +331,7 @@ Supported keywords for scroll-state container descriptors include {{glossary("ph
 
     To evaluate a container with a non-`none` `stuck` scroll-state query, it must have `position: sticky` set on it, and be inside a scroll container. If the test passes, the rules inside the `@container` block are applied to descendants of the `position: sticky` container.
 
-    It is possible for two values from opposite axes to match at the same time:
+    It is possible for two values from adjacent axes to match at the same time:
 
     ```css
     @container scroll-state((stuck: top) and (stuck: left)) {
@@ -343,6 +355,27 @@ Supported keywords for scroll-state container descriptors include {{glossary("ph
     }
     ```
 
+#### Anchored container descriptors
+
+Anchored container descriptors are specified inside the `<container-condition>` as an argument for the `anchored()` function, for example:
+
+```css
+@container anchored(fallback: top) {
+  /* … */
+}
+@container anchored(fallback: flip-block flip-inline) {
+  /* … */
+}
+@container anchored(fallback: --custom-fallback) {
+  /* … */
+}
+```
+
+- `fallback`
+  - : Queries whether a specific position-try fallback is currently active on an anchor-positioned container, as specified via the {{cssxref("position-try-fallbacks")}} property. Valid `fallback` values include any component value that is valid for inclusion in a `position-try-fallbacks` property value.
+
+    If the `fallback` value named in the test is currently active on the anchor-positioned container, the test passes, and the rules inside the `@container` block are applied to descendants of the anchor-positioned container.
+
 ## Formal syntax
 
 {{csssyntax}}
@@ -511,7 +544,11 @@ The global `revert` and `revert-layer` are invalid as values in a `<style-featur
 
 ### Scroll-state queries
 
-See [Using container scroll-state queries](/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries) for full walkthroughs of scroll-state query examples.
+See [Using container scroll-state queries](/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries) for scroll-state query examples.
+
+### Anchored queries
+
+See [Using anchored container queries](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries) for anchored query examples.
 
 ## Specifications
 
@@ -526,6 +563,7 @@ See [Using container scroll-state queries](/en-US/docs/Web/CSS/Guides/Conditiona
 - [Using container queries](/en-US/docs/Web/CSS/Guides/Containment/Container_queries)
 - [Using container size and style queries](/en-US/docs/Web/CSS/Guides/Containment/Container_size_and_style_queries)
 - [Using container scroll-state queries](/en-US/docs/Web/CSS/Guides/Conditional_rules/Container_scroll-state_queries)
+- [Using anchored container queries](/en-US/docs/Web/CSS/Guides/Anchor_positioning/Anchored_container_queries)
 - {{Cssxref("container-name")}}
 - {{Cssxref("container-type")}}
 - {{Cssxref("contain")}}