docs(css): Fx116 - syntax updates for offset-path and ray() #28348
Conversation
Preview URLs (7 pages)External URLs (4)URL:
(comment last updated: 2023-08-17 02:45:59) |
|
|
||
| In this example, various `offset-anchor` and `offset-path: ray()` values are applied to a box and results are displayed side-by-side for comparison. One box border is highlighted to demonstrate different ray starting points and box orientations. After a box is positioned at the ray's starting point, it is oriented in the direction of the specified ray angle. | ||
| In this example, various `offset-anchor` and `offset-path: ray()` values are applied to a box. Results are displayed side-by-side for comparison. The element's containing block is depicted with a dashed border. One border of the box is highlighted to demonstrate different ray starting points and box orientations. After a box is positioned at the ray's starting point, it is oriented in the direction of the specified ray angle. If `offset-position` is not specified, the default offset starting position of a ray is the top-left corner of the element's containing block. |
There was a problem hiding this comment.
Note: the spec got updated recently for the initial value of offset-position. (w3c/fxtf-drafts#522)
The initial value of offset-position is normal now (https://bugzilla.mozilla.org/show_bug.cgi?id=1846817), so if we don't specify offset-position, and ray() doesn't specify at <position>, the default starting position will be at center of the containing block.
https://drafts.fxtf.org/motion-1/#valdef-ray-at-position
I am working on this new change now, so perhaps you have to create a new PR for it.
There was a problem hiding this comment.
Thanks for flagging this, @BorisChiou. I've added the doc keyword to that bug so that it is on our radar when the fix comes in for us to update the docs. From the way it is currently working, ray() is using offset-position: auto when no at <position> and offset-position are specified. I'll update this later after your fix is in.
On a related note, the docs are updated for the new keyword for offset-position: https://developer.mozilla.org/en-US/docs/Web/CSS/offset-position#values. But I should add there that normal is (50% 50%) of the containing block.
Appreciate you taking a look at the changes in this PR.
| - `<coord-box>` | ||
| - : Refers to the coordinate box used for positioning and sizing an element within its parent container. It is used to control how content flows around the edges of the box. It excludes the margin area. | ||
|
|
There was a problem hiding this comment.
| - `<coord-box>` | |
| - : Refers to the coordinate box used for positioning and sizing an element within its parent container. It is used to control how content flows around the edges of the box. It excludes the margin area. | |
| - `<coord-box>` | |
| - : Refers to the coordinate box used for positioning and sizing an element within its parent container. It is used to control how content flows around the edges of the box. It excludes the margin area. This value type is used for the {{cssxref("mask-origin")}} property | |
| - `<geometry-box>` | |
| - : Defines the reference box for the basic shape or, if specified by itself, it causes the edges of the specified box, including any corner shaping (such as a {{cssxref("border-radius")}}), to be the clipping path. This value type is used for the {{cssxref("mask-clip")}} property and the SVG {{SVGAttr("clip-path")}} attribute. |
There was a problem hiding this comment.
Thanks for adding <geometry-box>! I somehow completely missed adding an entry for it.
Btw, shouldn't mask-origin be listed with <geometry-box>?
I've changed the property listed with <coord-box> to offset-path (as per the new syntax, also updated as part of this PR).
|
This pull request has merge conflicts that must be resolved before it can be merged. |
dipikabh
force-pushed
the
fx116-offset-path-shapes
branch
from
842f3ed
to
d261b5d
Compare
| <visual-box> = content-box | padding-box | border-box /* also referred to as <box> */ | ||
| <layout-box> = <box> | margin-box /* also referred to as <shape-box> */ | ||
| <paint-box> = <box> | fill-box | stroke-box | ||
| <coord-box> = <box> | fill-box | stroke-box | view-box | ||
| <geometry-box> = <layout-box> | fill-box | stroke-box | view-box |
There was a problem hiding this comment.
not wanting to hold anything up with this question, but...
we use <box> on 17, 18, and 19. It is introduced in line 16 as a comment.
we use <layout-box> on 21, which is the name on 18, with the comment of 18 introducing <shape-box>, but we're not using <shape-box>
thinking this may be a way of updating this:
| <visual-box> = content-box | padding-box | border-box /* also referred to as <box> */ | |
| <layout-box> = <box> | margin-box /* also referred to as <shape-box> */ | |
| <paint-box> = <box> | fill-box | stroke-box | |
| <coord-box> = <box> | fill-box | stroke-box | view-box | |
| <geometry-box> = <layout-box> | fill-box | stroke-box | view-box | |
| <visual-box> = content-box | padding-box | border-box /* the three <box> values */ | |
| <layout-box> = <box> | margin-box | |
| <paint-box> = <box> | fill-box | stroke-box | |
| <coord-box> = <box> | fill-box | stroke-box | view-box | |
| <geometry-box> = <layout-box> | fill-box | stroke-box | view-box |
and then adding the "also referred to as " under layout box in the values section.
There was a problem hiding this comment.
That's an excellent observation!
- The reason I've mentioned
<shape-box>in the syntax is because it occurs in the shape-outside property.
It is defined in the Shapes module spec as:
<shape-box> = <box> | margin-box(https://drafts.csswg.org/css-shapes/#typedef-shape-box)
(but the Box module spec defines the data type as<layout-box>, so keeping that as is here...) - The clip-path formal syntax refers to
<geometry-box>,<shape-box>, and<box>. Another reason why I wanted to define what's<shape-box>and<box>. - I believe I've seen occurrences of
<box>in a few other "Formal syntax" sections. - If we define these alternate terms here, we can point from those property pages to the
<box-edge>page in the future and update their value descriptions as well.
How about for <geometry-box>, we use <shape-box> instead of <layout-box>? (Because <shape-box> is more commonly used, but there are no occurrences of <layout-box> in content..yet!)
Updated text:
<visual-box> = content-box | padding-box | border-box /* the three <box> values */ <layout-box> = <box> | margin-box /* the <shape-box> values */ <paint-box> = <box> | fill-box | stroke-box <coord-box> = <box> | fill-box | stroke-box | view-box <geometry-box> = <shape-box> | fill-box | stroke-box | view-box
|
|
||
| - `<paint-box>` | ||
|
|
||
| - : Refers to the area within the layout box that is used to render the content visually. This includes the area where the element's background and borders are painted. It excludes the margin area. |
There was a problem hiding this comment.
still looking for a property that uses this... no luck. Do you have know how we can look at a web ref dump?
I am thinking that since in SVG, border-box is treated as stroke-box and padding-box is treated as fill-box, is paint-box just a synonym for visual box?
Maybe @fantasai can give us insight?
There was a problem hiding this comment.
Do you have know how we can look at a web ref dump?
No idea but it would be good to learn how to.
I guess we keep this description as is for now and update when we have more info
|
Thanks for the review, @estelle! I've incorporated most of your suggested changes. A few outstanding comments:
|
|
Thank you! Let me take up the |
1. offset-path
Previous syntax
offset-path: none | ray( [ <angle> && <size> && contain? ] ) | <path()> | <url> | [ <basic-shape> || <geometry-box> ]New syntax
offset-path: none | <offset-path> || <coord-box>where:
<offset-path> = <ray()> | <url> | <basic-shape>ray( <angle> && <size>? && contain? && [at <position>]? )layout.css.motion-path-coord-box.enabledlayout.css.motion-path-basic-shapes.enabled<coord-box>is defined in the Box Model spec (https://drafts.csswg.org/css-box-4/#keywords).New page: I've created a
<box>data type page to document the box-edge keywords and how they are then used in different<box>types like<visual-box>,<layout-box>,<paint-box>,<coord-box>, and<geometry-box>.I can do a follow up PR to add examples to
<box>data type page and also cleanup other related pages (covered in "Additional info"). I anyway need to do a separate PR to add spec link and BCD info.Additional info (click arrow)
* clip-path syntax expands
<box>toborder-box | padding-box | content-box. So I've used<box>as the building block. (as also used in the Shapes spec)* Making a note of this here for future reference and cleanup - a lot of pages on MDN refer to the box-edge keywords
- Box model
- Box model in Learn
- Shapes from box values
- box-sizing
- transform-box
- background-clip
- overflow-clip-margin mentions the
<visual-box>value* Only a glossary page exists for Bounding box - https://developer.mozilla.org/en-US/docs/Glossary/Bounding_box
- Types not covered on MDN: object bounding box, stroke bounding box, decorated bounding box (svg spec: https://svgwg.org/svg2-draft/coords.html#TermObjectBoundingBox)
2. ray()
Previous syntax
ray( <angle> && <ray-size>? && contain? )New syntax
ray( <angle> && <size>? && contain? && [at <position>]? )layout.css.motion-path-ray.enabledlayout.css.motion-path-offset-position.enabledRelated issues and pull requests
Doc trackers:
<basic-shape> || <coord-box>foroffset-path#27747Bugs:
To Dos