CINXE.COM

<!doctype html><html lang="en"> <head> <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> <meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport"> <title>CSS Line Grid Module Level 1</title> <meta content="ED" name="w3c-status"> <link href="https://www.w3.org/StyleSheets/TR/2021/W3C-ED" rel="stylesheet"> <meta content="Bikeshed version 60c422380, updated Thu Feb 20 19:11:22 2025 -0800" name="generator"> <link href="https://www.w3.org/TR/css-line-grid-1/" rel="canonical"> <link href="https://drafts.csswg.org/csslogo.ico" rel="icon"> <meta content="3845f405525db5b389d1d2c673eb1bbe959e0bff" name="revision"> <meta content="dark light" name="color-scheme"> <link href="https://www.w3.org/StyleSheets/TR/2021/dark.css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css"> <style type="text/css"> .sidenote-block { border: 1px solid gray; margin: auto; text-align: left; padding: 4pt; position: relative; max-width: 400pt; } .sidenote-body { margin-left: 120pt; font-size: 12pt; line-height: 18pt; } .sidenote-note { font-size: 10pt; line-height: 18pt; position: absolute; left: 4pt; top: 4pt; width: 110pt; } </style> <style>/* Boilerplate: style-autolinks */ .css.css, .property.property, .descriptor.descriptor { color: var(--a-normal-text); font-size: inherit; font-family: inherit; } .css::before, .property::before, .descriptor::before { content: "‘"; } .css::after, .property::after, .descriptor::after { content: "’"; } .property, .descriptor { /* Don't wrap property and descriptor names */ white-space: nowrap; } .type { /* CSS value <type> */ font-style: italic; } pre .property::before, pre .property::after { content: ""; } [data-link-type="property"]::before, [data-link-type="propdesc"]::before, [data-link-type="descriptor"]::before, [data-link-type="value"]::before, [data-link-type="function"]::before, [data-link-type="at-rule"]::before, [data-link-type="selector"]::before, [data-link-type="maybe"]::before { content: "‘"; } [data-link-type="property"]::after, [data-link-type="propdesc"]::after, [data-link-type="descriptor"]::after, [data-link-type="value"]::after, [data-link-type="function"]::after, [data-link-type="at-rule"]::after, [data-link-type="selector"]::after, [data-link-type="maybe"]::after { content: "’"; } [data-link-type].production::before, [data-link-type].production::after, .prod [data-link-type]::before, .prod [data-link-type]::after { content: ""; } [data-link-type=element], [data-link-type=element-attr] { font-family: Menlo, Consolas, "DejaVu Sans Mono", monospace; font-size: .9em; } [data-link-type=element]::before { content: "<" } [data-link-type=element]::after { content: ">" } [data-link-type=biblio] { white-space: pre; } @media (prefers-color-scheme: dark) { :root { --selflink-text: black; --selflink-bg: silver; --selflink-hover-text: white; } } </style> <style>/* Boilerplate: style-colors */ /* Any --*-text not paired with a --*-bg is assumed to have a transparent bg */ :root { color-scheme: light dark; --text: black; --bg: white; --unofficial-watermark: url(https://www.w3.org/StyleSheets/TR/2016/logos/UD-watermark); --logo-bg: #1a5e9a; --logo-active-bg: #c00; --logo-text: white; --tocnav-normal-text: #707070; --tocnav-normal-bg: var(--bg); --tocnav-hover-text: var(--tocnav-normal-text); --tocnav-hover-bg: #f8f8f8; --tocnav-active-text: #c00; --tocnav-active-bg: var(--tocnav-normal-bg); --tocsidebar-text: var(--text); --tocsidebar-bg: #f7f8f9; --tocsidebar-shadow: rgba(0,0,0,.1); --tocsidebar-heading-text: hsla(203,20%,40%,.7); --toclink-text: var(--text); --toclink-underline: #3980b5; --toclink-visited-text: var(--toclink-text); --toclink-visited-underline: #054572; --heading-text: #005a9c; --hr-text: var(--text); --algo-border: #def; --del-text: red; --del-bg: transparent; --ins-text: #080; --ins-bg: transparent; --a-normal-text: #034575; --a-normal-underline: #bbb; --a-visited-text: var(--a-normal-text); --a-visited-underline: #707070; --a-hover-bg: rgba(75%, 75%, 75%, .25); --a-active-text: #c00; --a-active-underline: #c00; --blockquote-border: silver; --blockquote-bg: transparent; --blockquote-text: currentcolor; --issue-border: #e05252; --issue-bg: #fbe9e9; --issue-text: var(--text); --issueheading-text: #831616; --example-border: #e0cb52; --example-bg: #fcfaee; --example-text: var(--text); --exampleheading-text: #574b0f; --note-border: #52e052; --note-bg: #e9fbe9; --note-text: var(--text); --noteheading-text: hsl(120, 70%, 30%); --notesummary-underline: silver; --assertion-border: #aaa; --assertion-bg: #eee; --assertion-text: black; --advisement-border: orange; --advisement-bg: #fec; --advisement-text: var(--text); --advisementheading-text: #b35f00; --warning-border: red; --warning-bg: hsla(40,100%,50%,0.95); --warning-text: var(--text); --amendment-border: #330099; --amendment-bg: #F5F0FF; --amendment-text: var(--text); --amendmentheading-text: #220066; --def-border: #8ccbf2; --def-bg: #def; --def-text: var(--text); --defrow-border: #bbd7e9; --datacell-border: silver; --indexinfo-text: #707070; --indextable-hover-text: black; --indextable-hover-bg: #f7f8f9; --outdatedspec-bg: rgba(0, 0, 0, .5); --outdatedspec-text: black; --outdated-bg: maroon; --outdated-text: white; --outdated-shadow: red; --editedrec-bg: darkorange; } @media (prefers-color-scheme: dark) { :root { --text: #ddd; --bg: black; --unofficial-watermark: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='400' height='400'%3E%3Cg fill='%23100808' transform='translate(200 200) rotate(-45) translate(-200 -200)' stroke='%23100808' stroke-width='3'%3E%3Ctext x='50%25' y='220' style='font: bold 70px sans-serif; text-anchor: middle; letter-spacing: 6px;'%3EUNOFFICIAL%3C/text%3E%3Ctext x='50%25' y='305' style='font: bold 70px sans-serif; text-anchor: middle; letter-spacing: 6px;'%3EDRAFT%3C/text%3E%3C/g%3E%3C/svg%3E"); --logo-bg: #1a5e9a; --logo-active-bg: #c00; --logo-text: white; --tocnav-normal-text: #999; --tocnav-normal-bg: var(--bg); --tocnav-hover-text: var(--tocnav-normal-text); --tocnav-hover-bg: #080808; --tocnav-active-text: #f44; --tocnav-active-bg: var(--tocnav-normal-bg); --tocsidebar-text: var(--text); --tocsidebar-bg: #080808; --tocsidebar-shadow: rgba(255,255,255,.1); --tocsidebar-heading-text: hsla(203,20%,40%,.7); --toclink-text: var(--text); --toclink-underline: #6af; --toclink-visited-text: var(--toclink-text); --toclink-visited-underline: #054572; --heading-text: #8af; --hr-text: var(--text); --algo-border: #456; --del-text: #f44; --del-bg: transparent; --ins-text: #4a4; --ins-bg: transparent; --a-normal-text: #6af; --a-normal-underline: #555; --a-visited-text: var(--a-normal-text); --a-visited-underline: var(--a-normal-underline); --a-hover-bg: rgba(25%, 25%, 25%, .2); --a-active-text: #f44; --a-active-underline: var(--a-active-text); --borderedblock-bg: rgba(255, 255, 255, .05); --blockquote-border: silver; --blockquote-bg: var(--borderedblock-bg); --blockquote-text: currentcolor; --issue-border: #e05252; --issue-bg: var(--borderedblock-bg); --issue-text: var(--text); --issueheading-text: hsl(0deg, 70%, 70%); --example-border: hsl(50deg, 90%, 60%); --example-bg: var(--borderedblock-bg); --example-text: var(--text); --exampleheading-text: hsl(50deg, 70%, 70%); --note-border: hsl(120deg, 100%, 35%); --note-bg: var(--borderedblock-bg); --note-text: var(--text); --noteheading-text: hsl(120, 70%, 70%); --notesummary-underline: silver; --assertion-border: #444; --assertion-bg: var(--borderedblock-bg); --assertion-text: var(--text); --advisement-border: orange; --advisement-bg: #222218; --advisement-text: var(--text); --advisementheading-text: #f84; --warning-border: red; --warning-bg: hsla(40,100%,20%,0.95); --warning-text: var(--text); --amendment-border: #330099; --amendment-bg: #080010; --amendment-text: var(--text); --amendmentheading-text: #cc00ff; --def-border: #8ccbf2; --def-bg: #080818; --def-text: var(--text); --defrow-border: #136; --datacell-border: silver; --indexinfo-text: #aaa; --indextable-hover-text: var(--text); --indextable-hover-bg: #181818; --outdatedspec-bg: rgba(255, 255, 255, .5); --outdatedspec-text: black; --outdated-bg: maroon; --outdated-text: white; --outdated-shadow: red; --editedrec-bg: darkorange; } /* In case a transparent-bg image doesn't expect to be on a dark bg, which is quite common in practice... */ img { background: white; } } </style> <style>/* Boilerplate: style-counters */ body { counter-reset: example figure issue; } .issue { counter-increment: issue; } .issue:not(.no-marker)::before { content: "Issue " counter(issue); } .example { counter-increment: example; } .example:not(.no-marker)::before { content: "Example " counter(example); } .invalid.example:not(.no-marker)::before, .illegal.example:not(.no-marker)::before { content: "Invalid Example" counter(example); } figcaption { counter-increment: figure; } figcaption:not(.no-marker)::before { content: "Figure " counter(figure) " "; } </style> <style>/* Boilerplate: style-dfn-panel */ :root { --dfnpanel-bg: #ddd; --dfnpanel-text: var(--text); --dfnpanel-target-bg: #ffc; --dfnpanel-target-outline: orange; } @media (prefers-color-scheme: dark) { :root { --dfnpanel-bg: #222; --dfnpanel-text: var(--text); --dfnpanel-target-bg: #333; --dfnpanel-target-outline: silver; } } .dfn-panel { position: absolute; z-index: 35; width: 20em; width: 300px; height: auto; max-height: 500px; overflow: auto; padding: 0.5em 0.75em; font: small Helvetica Neue, sans-serif, Droid Sans Fallback; background: var(--dfnpanel-bg); color: var(--dfnpanel-text); border: outset 0.2em; white-space: normal; /* in case it's moved into a pre */ } .dfn-panel:not(.on) { display: none; } .dfn-panel * { margin: 0; padding: 0; text-indent: 0; } .dfn-panel > b { display: block; } .dfn-panel a { color: var(--dfnpanel-text); } .dfn-panel a:not(:hover) { text-decoration: none !important; border-bottom: none !important; } .dfn-panel a:focus { outline: 5px auto Highlight; outline: 5px auto -webkit-focus-ring-color; } .dfn-panel > b + b { margin-top: 0.25em; } .dfn-panel ul { padding: 0 0 0 1em; list-style: none; } .dfn-panel li a { max-width: calc(300px - 1.5em - 1em); overflow: hidden; text-overflow: ellipsis; } .dfn-panel.activated { display: inline-block; position: fixed; left: 8px; bottom: 2em; margin: 0 auto; max-width: calc(100vw - 1.5em - .4em - .5em); max-height: 30vh; transition: left 1s ease-out, bottom 1s ease-out; } .dfn-panel .link-item:hover { text-decoration: underline; } .dfn-panel .link-item .copy-icon { opacity: 0; } .dfn-panel .link-item:hover .copy-icon, .dfn-panel .link-item .copy-icon:focus { opacity: 1; } .dfn-panel .copy-icon { display: inline-block; margin-right: 0.5em; width: 0.85em; height: 1em; border-radius: 3px; background-color: #ccc; cursor: pointer; } .dfn-panel .copy-icon .icon { width: 100%; height: 100%; background-color: #fff; display: flex; justify-content: center; align-items: center; position: relative; } .dfn-panel .copy-icon .icon::before { content: ""; position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 1px solid black; background-color: #ccc; opacity: 0.25; transform: translate(3px, -3px); } .dfn-panel .copy-icon:active .icon::before { opacity: 1; } .dfn-paneled[role="button"] { cursor: help; } .highlighted { animation: target-fade 3s; } @keyframes target-fade { from { background-color: var(--dfnpanel-target-bg); outline: 5px solid var(--dfnpanel-target-outline); } to { color: var(--a-normal-text); background-color: transparent; outline: transparent; } } </style> <style>/* Boilerplate: style-issues */ a[href].issue-return { float: right; float: inline-end; color: var(--issueheading-text); font-weight: bold; text-decoration: none; } </style> <style>/* Boilerplate: style-md-lists */ /* This is a weird hack for me not yet following the commonmark spec regarding paragraph and lists. */ [data-md] > :first-child { margin-top: 0; } [data-md] > :last-child { margin-bottom: 0; } </style> <style>/* Boilerplate: style-ref-hints */ :root { --ref-hint-bg: #ddd; --ref-hint-text: var(--text); } @media (prefers-color-scheme: dark) { :root { --ref-hint-bg: #222; --ref-hint-text: var(--text); } } .ref-hint { display: inline-block; position: absolute; z-index: 35; width: 20em; width: 300px; height: auto; max-height: 500px; overflow: auto; padding: 0.5em 0.5em; font: small Helvetica Neue, sans-serif, Droid Sans Fallback; background: var(--ref-hint-bg); color: var(--ref-hint-text); border: outset 0.2em; white-space: normal; /* in case it's moved into a pre */ } .ref-hint * { margin: 0; padding: 0; text-indent: 0; } .ref-hint ul { padding: 0 0 0 1em; list-style: none; } </style> <style>/* Boilerplate: style-selflinks */ :root { --selflink-text: white; --selflink-bg: gray; --selflink-hover-text: black; } .heading, .issue, .note, .example, li, dt { position: relative; } a.self-link { position: absolute; top: 0; left: calc(-1 * (3.5rem - 26px)); width: calc(3.5rem - 26px); height: 2em; text-align: center; border: none; transition: opacity .2s; opacity: .5; } a.self-link:hover { opacity: 1; } .heading > a.self-link { font-size: 83%; } .example > a.self-link, .note > a.self-link, .issue > a.self-link { /* These blocks are overflow:auto, so positioning outside doesn't work. */ left: auto; right: 0; } li > a.self-link { left: calc(-1 * (3.5rem - 26px) - 2em); } dfn > a.self-link { top: auto; left: auto; opacity: 0; width: 1.5em; height: 1.5em; background: var(--selflink-bg); color: var(--selflink-text); font-style: normal; transition: opacity .2s, background-color .2s, color .2s; } dfn:hover > a.self-link { opacity: 1; } dfn > a.self-link:hover { color: var(--selflink-hover-text); } a.self-link::before { content: "¶"; } .heading > a.self-link::before { content: "§"; } dfn > a.self-link::before { content: "#"; } </style> <style>/* Boilerplate: style-wpt */ :root { --wpt-border: hsl(0, 0%, 60%); --wpt-bg: hsl(0, 0%, 95%); --wpt-text: var(--text); --wptheading-text: hsl(0, 0%, 30%); } @media (prefers-color-scheme: dark) { :root { --wpt-border: hsl(0, 0%, 30%); --wpt-bg: var(--borderedblock-bg); --wpt-text: var(--text); --wptheading-text: hsl(0, 0%, 60%); } } .wpt-tests-block { list-style: none; border-left: .5em solid var(--wpt-border); background: var(--wpt-bg); color: var(--wpt-text); margin: 1em auto; padding: .5em; } .wpt-tests-block summary { color: var(--wptheading-text); font-weight: normal; text-transform: uppercase; } .wpt-tests-block summary::marker{ color: var(--wpt-border); } .wpt-tests-block summary:hover::marker{ color: var(--wpt-text); } /* The only content of a wpt test block in its closed state is the <summary>, which contains the word TESTS, and that is absolutely positioned. In that closed state, wpt test blocks are styled to have a top margin whose height is exactly equal to the height of the absolutely positioned <summary>, and no other background/padding/margin/border. The wpt test block elements will therefore allow the maring of the previous/next block elements to collapse through them; if this combined margin would be larger than its own top margin, it stays as is, and therefore the pre-existing vertical rhythm of the document is undisturbed. If that combined margin would be smaller, it is grown to that size. This means that the wpt test block ensures that there's always enough vertical space to insert the summary, without adding more than is needed. */ .wpt-tests-block:not([open]){ padding: 0; border: none; background: none; font-size: 0.75em; line-height: 1; position: relative; margin: 1em 0 0; } .wpt-tests-block:not([open]) summary { position: absolute; right: 0; bottom: 0; } /* It is possible that both the last child of a block element and the block element itself would be annotated with a <wpt> block each. If the block element has a padding or a border, that's fine, but otherwise the bottom margin of the block and of its last child would collapse and both <wpt> elements would overlap, being both placed there. To avoid that, add 1px of padding to the <wpt> element annotating the last child to prevent the bottom margin of the block and of its last child from collapsing (and as much negative margin, as wel only want to prevent margin collapsing, but are not trying to actually take more space). */ .wpt-tests-block:not([open]):last-child { padding-bottom: 1px; margin-bottom: -1px; } /* Exception to the previous rule: don't do that in non-last list items, because it's not necessary, and would therefore consume more space than strictly needed. Lists must have list items as children, not <wpt> elements, so a <wpt> element cannot be a sibling of a list item, and the collision that the previous rule avoids cannot happen. */ li:not(:last-child) > .wpt-tests-block:not([open]):last-child, dd:not(:last-child) > .wpt-tests-block:not([open]):last-child { padding-bottom: 0; margin-bottom: 0; } .wpt-tests-block:not([open]):not(:hover){ opacity: 0.5; } .wpt-tests-list { list-style: none; display: grid; margin: 0; padding: 0; grid-template-columns: 1fr max-content auto auto; grid-column-gap: .5em; } .wpt-tests-block hr:last-child { display: none; } .wpt-test { display: contents; } .wpt-test > a { text-decoration: underline; border: none; } .wpt-test > .wpt-name { grid-column: 1; } .wpt-test > .wpt-results { grid-column: 2; } .wpt-test > .wpt-live { grid-column: 3; } .wpt-test > .wpt-source { grid-column: 4; } .wpt-test > .wpt-results { display: flex; gap: .1em; } .wpt-test .wpt-result { display: inline-block; height: 1em; width: 1em; border-radius: 50%; position: relative; } </style> <body class="h-entry"> <div class="head"> <p data-fill-with="logo"><a class="logo" href="https://www.w3.org/"> <img alt="W3C" height="48" src="https://www.w3.org/StyleSheets/TR/2021/logos/W3C" width="72"> </a> </p> <h1 class="p-name no-ref" id="title">CSS Line Grid Module Level 1</h1> <p id="w3c-state"><a href="https://www.w3.org/standards/types/#ED">Editor’s Draft</a>, <time class="dt-updated" datetime="2024-07-26">26 July 2024</time></p> <details open> <summary>More details about this document</summary> <div data-fill-with="spec-metadata"> <dl> <dt>This version: <dd><a class="u-url" href="https://drafts.csswg.org/css-line-grid/">https://drafts.csswg.org/css-line-grid/</a> <dt>Latest published version: <dd><a href="https://www.w3.org/TR/css-line-grid-1/">https://www.w3.org/TR/css-line-grid-1/</a> <dt>Previous Versions: <dd><a href="https://www.w3.org/TR/2014/WD-css-line-grid-1-20140916/" rel="prev">https://www.w3.org/TR/2014/WD-css-line-grid-1-20140916/</a> <dt>Feedback: <dd><a href="https://github.com/w3c/csswg-drafts/labels/css-line-grid-1">CSSWG Issues Repository</a> <dd><a href="#issues-index">Inline In Spec</a> <dt class="editor">Editors: <dd class="editor p-author h-card vcard" data-editor-id="35400"><a class="p-name fn u-url url" href="http://fantasai.inkedblade.net/contact">Elika Etemad</a> (<span class="p-org org">Invited Expert</span>) <dd class="editor p-author h-card vcard" data-editor-id="45369"><a class="p-name fn u-email email" href="mailto:kojiishi@gluesoft.co.jp">Koji Ishii</a> (<span class="p-org org">Invited Expert</span>) <dd class="editor p-author h-card vcard" data-editor-id="46659"><a class="p-name fn u-email email" href="mailto:stearns@adobe.com">Alan Stearns</a> (<span class="p-org org">Adobe Systems, Inc.</span>) <dt>Suggest an Edit for this Spec: <dd><a href="https://github.com/w3c/csswg-drafts/blob/main/css-line-grid-1/Overview.bs">GitHub Editor</a> </dl> </div> </details> <div data-fill-with="warning"></div> <p class="copyright" data-fill-with="copyright"><a href="https://www.w3.org/policies/#copyright">Copyright</a> © 2024 <a href="https://www.w3.org/">World Wide Web Consortium</a>. <abbr title="World Wide Web Consortium">W3C</abbr><sup>®</sup> <a href="https://www.w3.org/policies/#Legal_Disclaimer">liability</a>, <a href="https://www.w3.org/policies/#W3C_Trademarks">trademark</a> and <a href="https://www.w3.org/copyright/software-license/" rel="license" title="W3C Software and Document License">permissive document license</a> rules apply. </p> <hr title="Separator for header"> </div> <div class="p-summary" data-fill-with="abstract"> <h2 class="no-num no-toc no-ref heading settled" id="abstract"><span class="content">Abstract</span></h2> <p>This module contains CSS features for aligning content to a baseline grid.</p> <a href="https://www.w3.org/TR/CSS/">CSS</a> is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc. <script> const githubPrefix = "https://w3c.github.io/csswg-drafts/"; if(location.href.slice(0, githubPrefix.length) == githubPrefix) { const suffix = location.href.slice(githubPrefix.length); const draftUrl = "https://drafts.csswg.org/" + suffix; window.location.replace(draftUrl); } </script> </div> <h2 class="no-num no-toc no-ref heading settled" id="sotd"><span class="content">Status of this document</span></h2> <div data-fill-with="status"> <p> This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress. </p> <p>Please send feedback by <a href="https://github.com/w3c/csswg-drafts/issues">filing issues in GitHub</a> (preferred), including the spec code “css-line-grid” in the title, like this: “[css-line-grid] <i>…summary of comment…</i>”. All issues and comments are <a href="https://lists.w3.org/Archives/Public/public-css-archive/">archived</a>. Alternately, feedback can be sent to the (<a href="https://lists.w3.org/Archives/Public/www-style/">archived</a>) public mailing list <a href="mailto:www-style@w3.org?Subject=%5Bcss-line-grid%5D%20PUT%20SUBJECT%20HERE">www-style@w3.org</a>. </p> <p>This document is governed by the <a href="https://www.w3.org/policies/process/20231103/" id="w3c_process_revision">03 November 2023 W3C Process Document</a>. </p> </div> <div data-fill-with="at-risk"></div> <nav data-fill-with="table-of-contents" id="toc"> <h2 class="no-num no-toc no-ref" id="contents">Table of Contents</h2> <ol class="toc" role="directory"> <li> <a href="#intro"><span class="secno">1</span> <span class="content"> Introduction</span></a> <ol class="toc"> <li><a href="#context"><span class="secno">1.1</span> <span class="content"> Background</span></a> <li><a href="#placement"><span class="secno">1.2</span> <span class="content"> Module Interactions</span></a> <li><a href="#values"><span class="secno">1.3</span> <span class="content"> Value Definitions</span></a> </ol> <li><a href="#line-grid-property"><span class="secno">2</span> <span class="content"> Defining a <span>Line Grid</span>: the <span class="property">line-grid</span> property</span></a> <li> <a href="#grid-snapping"><span class="secno">3</span> <span class="content"> Snapping to a Grid</span></a> <ol class="toc"> <li><a href="#line-snap"><span class="secno">3.1</span> <span class="content"> Snapping Line Boxes: the <span class="property">line-snap</span> property</span></a> <li><a href="#box-snap"><span class="secno">3.2</span> <span class="content"> Snapping Block Boxes: the <span class="property">box-snap</span> property</span></a> </ol> <li> <a href="#snap-details"><span class="secno">4</span> <span class="content"> Snapping Details</span></a> <ol class="toc"> <li><a href="#alignment-interactions"><span class="secno">4.1</span> <span class="content"> Interacting with other alignments</span></a> <li><a href="#leading-adjustments"><span class="secno">4.2</span> <span class="content"> Leading adjustments</span></a> </ol> <li><a href="#acknowledgments"><span class="secno"></span> <span class="content">Acknowledgments</span></a> <li> <a href="#change-log"><span class="secno"></span> <span class="content"> Change Log</span></a> <ol class="toc"> <li><a href="#20140916"><span class="secno"></span> <span class="content"> Since <span>September 16th 2014</span></span></a> <li><a href="#20140403"><span class="secno"></span> <span class="content"> Since <span>April 3rd 2014</span></span></a> </ol> <li><a href="#privacy"><span class="secno"></span> <span class="content">Privacy Considerations</span></a> <li><a href="#security"><span class="secno"></span> <span class="content">Security Considerations</span></a> <li> <a href="#w3c-conformance"><span class="secno"></span> <span class="content"> Conformance</span></a> <ol class="toc"> <li><a href="#w3c-conventions"><span class="secno"></span> <span class="content"> Document conventions</span></a> <li><a href="#w3c-conformance-classes"><span class="secno"></span> <span class="content"> Conformance classes</span></a> <li> <a href="#w3c-partial"><span class="secno"></span> <span class="content"> Partial implementations</span></a> <ol class="toc"> <li><a href="#w3c-conform-future-proofing"><span class="secno"></span> <span class="content"> Implementations of Unstable and Proprietary Features</span></a> </ol> <li><a href="#w3c-testing"><span class="secno"></span> <span class="content"> Non-experimental implementations</span></a> </ol> <li> <a href="#index"><span class="secno"></span> <span class="content">Index</span></a> <ol class="toc"> <li><a href="#index-defined-here"><span class="secno"></span> <span class="content">Terms defined by this specification</span></a> <li><a href="#index-defined-elsewhere"><span class="secno"></span> <span class="content">Terms defined by reference</span></a> </ol> <li> <a href="#references"><span class="secno"></span> <span class="content">References</span></a> <ol class="toc"> <li><a href="#normative"><span class="secno"></span> <span class="content">Normative References</span></a> <li><a href="#informative"><span class="secno"></span> <span class="content">Informative References</span></a> </ol> <li><a href="#property-index"><span class="secno"></span> <span class="content">Property Index</span></a> <li><a href="#issues-index"><span class="secno"></span> <span class="content">Issues Index</span></a> </ol> </nav> <main> <h2 class="heading settled" data-level="1" id="intro"><span class="secno">1. </span><span class="content"> Introduction</span><a class="self-link" href="#intro"></a></h2> <h3 class="heading settled" data-level="1.1" id="context"><span class="secno">1.1. </span><span class="content"> Background</span><a class="self-link" href="#context"></a></h3> <p><em>This section is not normative.</em></p> <p>This specification provides features to align lines and blocks to invisible grids in the document.</p> <p>Aligning lines and blocks to grids provides the following benefits:</p> <ul> <li>Vertical rhythm is kept for better readability. <li>Lines are aligned between columns in multi-column documents. <li>The top and the bottom margins of pictures are made equal, while keeping the vertical rhythm of text before and after the pictures. <li>Layout lines are at the same position on every page in paged media. Keeping the position of the bottom line of a page has benefits for design and readability. This also improves the readability of duplex printing, two pages spreads, and displaying on slow display devices like e-ink. <li>East Asian layouts require vertical rhythm more often than other scripts do, even in single column, non-paged media documents, as defined in <a data-link-type="biblio" href="#biblio-jlreq" title="Requirements for Japanese Text Layout 日本語組版処理の要件(日本語版)">[JLREQ]</a>. </ul> <p>There are several types of objects in a document that can break the vertical rhythm. Examples include lines with different sizes of text, pictures, and tables.</p> <div class="figure"> <img alt="Vertical rhythm kept through pictures and different size of text in a multi-column document" src="images/line-grid-multicol.png" width="480"> <p class="caption">Vertical rhythm kept through pictures and different size of text in a multi-column document.</p> </div> <div class="example" id="example-1b67eeaa"> <a class="self-link" href="#example-1b67eeaa"></a> <div class="sidefigure"> <img alt="Large text wraps within line grids" src="images/line-grid-wrap.png" width="276"> <p class="caption">Large text wraps within line grids.</p> </div> <p>When a different size of text, such as a headings wraps, it is usually aligned to grids as a block and the lines within the block do not align.</p> <p><br style="clear:both;"></p> </div> <div class="figure" id="ex-sidenote"> <div class="sidenote-block"> <div class="sidenote-body"> <p>Sidenotes (and footnotes for that matter) are often set at a smaller size than the basic text. This smaller text should still line up with the basic text. Authors can try to achieve this effect by calculating appropriate font-size, line-height, and margins*, but lack the proper tools to get the baselines to align.</p> </div> <div class="sidenote-note"> <p>Even if the author controls all this, the baselines won’t align. And careful calculations can be thrown off by user stylesheets.</p> </div> </div> <p class="caption">Sidenotes are set at a smaller size, and baselines don’t align.</p> </div> <figure> <img alt="sidenote rendering with aligned baselines" height="194" src="images/sidenote-aligned.png" width="552"> <figcaption> Sidenote with baselines aligned to the body text. </figcaption> </figure> <div class="sidefigure" id="ex-width"> <img alt="East Asian layouts may require width be a multiple of em without fractions" height="142" src="images/width-multiple-of-em.png" width="180"> <p class="caption">East Asian layouts may require width be a multiple of <em>em</em> without fractions.</p> </div> <p>East Asian layouts may require grid-like features in inline progression direction as well.</p> <p>It is often desirable in East Asian layouts to make the line width a multiple of <em>em</em> without fractions. Because most East Asian characters have 1em advance and most East Asian documents are justified, this minimizes cases where justification needs to expand character spacing.</p> <p>This module provides the following capabilities:</p> <ul> <li>Defining grids in the line progression direction. <li>Controlling how lines and blocks align to the grids. </ul> <p>It is important to control these capabilities independently, so that, for example, aligning to grids can be turned off for tables, but can then be turned back on for aligning the following text to the grids.</p> <h3 class="heading settled" data-level="1.2" id="placement"><span class="secno">1.2. </span><span class="content"> Module Interactions</span><a class="self-link" href="#placement"></a></h3> <p>This module extends the line box model defined in <a data-link-type="biblio" href="#biblio-css2" title="Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification">[CSS2]</a> sections 9.4.2 and 10.8.</p> <h3 class="heading settled" data-level="1.3" id="values"><span class="secno">1.3. </span><span class="content"> Value Definitions</span><a class="self-link" href="#values"></a></h3> <p>This specification follows the <a href="https://www.w3.org/TR/CSS2/about.html#property-defs">CSS property definition conventions</a> from <a data-link-type="biblio" href="#biblio-css2" title="Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification">[CSS2]</a> using the <a href="https://www.w3.org/TR/css-values-3/#value-defs">value definition syntax</a> from <a data-link-type="biblio" href="#biblio-css-values-3" title="CSS Values and Units Module Level 3">[CSS-VALUES-3]</a>. Value types not defined in this specification are defined in CSS Values & Units <span title="CSS Values and Units Module Level 3">[CSS-VALUES-3]</span>. Combination with other CSS modules may expand the definitions of these value types.</p> <p>In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept the <a data-link-type="dfn" href="https://drafts.csswg.org/css-values-4/#css-wide-keywords" id="ref-for-css-wide-keywords">CSS-wide keywords</a> as their property value. For readability they have not been repeated explicitly.</p> <h2 class="heading settled" data-level="2" id="line-grid-property"><span class="secno">2. </span><span class="content"> Defining a <dfn class="dfn-paneled" data-dfn-type="dfn" data-noexport id="line-grid">Line Grid</dfn>: the <a class="property css" data-link-type="property" href="#propdef-line-grid" id="ref-for-propdef-line-grid">line-grid</a> property</span><a class="self-link" href="#line-grid-property"></a></h2> <table class="def propdef" data-link-for-hint="line-grid"> <tbody> <tr> <th>Name: <td><dfn class="dfn-paneled css" data-dfn-type="property" data-export id="propdef-line-grid">line-grid</dfn> <tr class="value"> <th><a href="https://www.w3.org/TR/css-values/#value-defs">Value:</a> <td class="prod">match-parent <a data-link-type="grammar" href="https://drafts.csswg.org/css-values-4/#comb-one" id="ref-for-comb-one">|</a> create <tr> <th><a href="https://www.w3.org/TR/css-cascade/#initial-values">Initial:</a> <td>match-parent <tr> <th><a href="https://www.w3.org/TR/css-cascade/#applies-to">Applies to:</a> <td>block, flex and grid containers <tr> <th><a href="https://www.w3.org/TR/css-cascade/#inherited-property">Inherited:</a> <td>no <tr> <th><a href="https://www.w3.org/TR/css-values/#percentages">Percentages:</a> <td>N/A <tr> <th><a href="https://www.w3.org/TR/css-cascade/#computed">Computed value:</a> <td>specified keyword <tr> <th><a href="https://www.w3.org/TR/cssom/#serializing-css-values">Canonical order:</a> <td>per grammar <tr> <th><a href="https://www.w3.org/TR/web-animations/#animation-type">Animation type:</a> <td>discrete </table> <p>Specifies whether this box creates a new baseline grid for its descendants or uses the same baseline grid as its parent. (Each box always has an associated <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid">line grid</a>. However, whether a box or its contents snap to a <span id="ref-for-line-grid①">line grid</span> is determined by <a class="property css" data-link-type="property" href="#propdef-line-snap" id="ref-for-propdef-line-snap">line-snap</a> and <a class="property css" data-link-type="property" href="#propdef-box-snap" id="ref-for-propdef-box-snap">box-snap</a>.)</p> <p>The values of this property have the following meanings:</p> <dl> <dt><dfn class="dfn-paneled css" data-dfn-for="line-grid" data-dfn-type="value" data-export id="valdef-line-grid-match-parent">match-parent</dfn> <dd>Box assumes the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②">line grid</a> of its parent if its <a data-link-type="dfn" href="https://drafts.csswg.org/css-writing-modes-4/#writing-mode" id="ref-for-writing-mode">writing mode</a> is the same as its parent. If the box has a <span id="ref-for-writing-mode①">writing mode</span> that is different than its parent, then the box creates a new <span id="ref-for-line-grid③">line grid</span> as <a class="css" data-link-type="maybe" href="#valdef-line-grid-create" id="ref-for-valdef-line-grid-create">create</a> below. <dt><dfn class="dfn-paneled css" data-dfn-for="line-grid" data-dfn-type="value" data-export id="valdef-line-grid-create">create</dfn> <dd>Box creates a new <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid④">line grid</a> using its own font and line layout settings, including any adjustment to the line height caused by the <a class="property css" data-link-type="property" href="https://drafts.csswg.org/css-rhythm-1/#propdef-line-height-step" id="ref-for-propdef-line-height-step">line-height-step</a> property. The <span id="ref-for-line-grid⑤">line grid</span> consists of a series of horizontal lines corresponding to all the baselines (alphabetic, text-top, text-bottom, mathematic, central, hanging, etc.) and to the line-over and line-under edges, positioned where they would fall if the contents of this element consisted entirely of line boxes filled with text (no sub-elements) using the first available font. If the box is paginated, the <span id="ref-for-line-grid⑥">line grid</span> is restarted on each page; since line boxes cannot be fragmented, no page begins with the bottom part of a line’s grid. </dl> <p>The initial containing block establishes a <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid⑦">line grid</a> using the font and line layout settings of the root element. If the root element (which has no parent) has a value of <a class="css" data-link-type="maybe" href="#valdef-line-grid-match-parent" id="ref-for-valdef-line-grid-match-parent">match-parent</a>, then it adopts the <span id="ref-for-line-grid⑧">line grid</span> of the initial containing block.</p> <p>In <a data-link-type="dfn" href="https://drafts.csswg.org/mediaqueries-5/#paged-media" id="ref-for-paged-media">paged media</a>, if the page context applying to a particular page specifies <a class="css" data-link-type="propdesc" href="#propdef-line-grid" id="ref-for-propdef-line-grid①">line-grid: create</a>, then a <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid⑨">line grid</a> for that page is established using the page context’s font and line layout settings applied to the page box (including its margins), and for layout within that page the initial containing block is assumed to have adopted this <span id="ref-for-line-grid①⓪">line grid</span>.</p> <div class="example" id="example-5340861c"> <a class="self-link" href="#example-5340861c"></a> Since the initial value of <a class="property css" data-link-type="property" href="#propdef-line-grid" id="ref-for-propdef-line-grid②">line-grid</a> is <a class="css" data-link-type="maybe" href="#valdef-line-grid-match-parent" id="ref-for-valdef-line-grid-match-parent①">match-parent</a>, by default a <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid①①">line grid</a> is automatically created using the root element’s font and line height settings to fill the initial containing block / page area. When all pages of a document are the same size, this will result in a consistent <span id="ref-for-line-grid①②">line grid</span> that exactly aligns to the top of each page area. <p>It is sometimes appropriate for the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid①③">line grid</a> to begin with the content, after the root element’s margins/padding/border and/or other header content. To do this, the root element (or some other element) can be told to establish the <span id="ref-for-line-grid①④">line grid</span>.</p> <pre>main { line-grid: create; } </pre> <p>If this <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid①⑤">line grid</a> is then paginated, the <span id="ref-for-line-grid①⑥">line grid</span> will start at the top of each page area after the first.</p> <p>In other cases, it’s desirable for all pages of a document share a common <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid①⑦">line grid</a>, even if page margins, border and/or padding change. The following rule will instead fill the page box area <em>including</em> the page margin/padding/borders with the <span id="ref-for-line-grid①⑧">line grid</span>:</p> <pre>@page { line-grid: create; } </pre> <p>As this <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid①⑨">line grid</a> is paginated, it will start at the top of each page box after the first; however it might not align to the top of the page area (where the content would normally begin).</p> </div> <p class="issue" id="issue-aa203f7b"><a class="self-link" href="#issue-aa203f7b"></a> The names of these values is currently up for debate. Current suggestions for match-parent include match-parent and normal; those for create include create and new.</p> <p class="note" role="note">The original proposal for line grids allowed an element to create a named grid. This property could still be extended to do this in the future. </p> <p class="note" role="note">There might need to be an offset for more complicated designs. How to set this offset is problematic: usually it’s not a fixed length, but the distance to clear some header content. This could be added to a later level of css-line-grid. </p> <h2 class="heading settled" data-level="3" id="grid-snapping"><span class="secno">3. </span><span class="content"> Snapping to a Grid</span><a class="self-link" href="#grid-snapping"></a></h2> <p>The <a class="property css" data-link-type="property" href="#propdef-line-snap" id="ref-for-propdef-line-snap①">line-snap</a> and <a class="property css" data-link-type="property" href="#propdef-box-snap" id="ref-for-propdef-box-snap①">box-snap</a> properties cause line boxes and block boxes to shift position in order to align to the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②⓪">line grid</a>. Shifting boxes in this way affects layout – it is not merely a display translation. If a line box is shifted, then subsequent line boxes will be laid out using the new shifted position as input to their line stacking rules. If a block box is shifted, then subsequent boxes will be laid out using the new shifted position as input.</p> <h3 class="heading settled" data-level="3.1" id="line-snap"><span class="secno">3.1. </span><span class="content"> Snapping Line Boxes: the <a class="property css" data-link-type="property" href="#propdef-line-snap" id="ref-for-propdef-line-snap②">line-snap</a> property</span><a class="self-link" href="#line-snap"></a></h3> <table class="def propdef" data-link-for-hint="line-snap"> <tbody> <tr> <th>Name: <td><dfn class="dfn-paneled css" data-dfn-type="property" data-export id="propdef-line-snap">line-snap</dfn> <tr class="value"> <th><a href="https://www.w3.org/TR/css-values/#value-defs">Value:</a> <td class="prod">none <a data-link-type="grammar" href="https://drafts.csswg.org/css-values-4/#comb-one" id="ref-for-comb-one①">|</a> baseline <span id="ref-for-comb-one②">|</span> contain <tr> <th><a href="https://www.w3.org/TR/css-cascade/#initial-values">Initial:</a> <td>none <tr> <th><a href="https://www.w3.org/TR/css-cascade/#applies-to">Applies to:</a> <td><a data-link-type="dfn" href="https://drafts.csswg.org/css-display-4/#block-container" id="ref-for-block-container">block container</a> elements <tr> <th><a href="https://www.w3.org/TR/css-cascade/#inherited-property">Inherited:</a> <td>yes <tr> <th><a href="https://www.w3.org/TR/css-values/#percentages">Percentages:</a> <td>N/A <tr> <th><a href="https://www.w3.org/TR/css-cascade/#computed">Computed value:</a> <td>specified keyword <tr> <th><a href="https://www.w3.org/TR/cssom/#serializing-css-values">Canonical order:</a> <td>per grammar <tr> <th><a href="https://www.w3.org/TR/web-animations/#animation-type">Animation type:</a> <td>discrete </table> <p>This property applies to all the line boxes directly contained by the element, and, when not none, causes each line box to shift (usually downward, possibly by zero) until it snaps to the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②①">line grid</a> specified by <a class="property css" data-link-type="property" href="#propdef-line-grid" id="ref-for-propdef-line-grid③">line-grid</a>. (The unshifted position is the position that would be determined by normal line stacking rules, with consideration of any new controls defined by other modules such as <a data-link-type="biblio" href="#biblio-css3line" title="CSS Inline Layout Module Level 3">[CSS3LINE]</a>.)</p> <p>Values have the following meanings:</p> <dl> <dt><dfn class="dfn-paneled css" data-dfn-for="line-snap" data-dfn-type="value" data-export id="valdef-line-snap-none">none</dfn> <dd>Line boxes do not snap to the grid; they stack normally. <dt><dfn class="dfn-paneled css" data-dfn-for="line-snap" data-dfn-type="value" data-export id="valdef-line-snap-baseline">baseline</dfn> <dd>The dominant baseline snaps with the matching baseline on the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②②">line grid</a> applying to the element. <dt><dfn class="dfn-paneled css" data-dfn-for="line-snap" data-dfn-type="value" data-export id="valdef-line-snap-contain">contain</dfn> <dd> Two baselines are used to align the line box: the line box is snapped so that its <a href="https://drafts.csswg.org/css-inline/#central">central</a> baseline is centered between one of the line grid’s <a href="https://drafts.csswg.org/css-inline/#text-over-edge">text-over-edge</a> baselines and a subsequent (but not necessarily consecutive) <a href="https://drafts.csswg.org/css-inline/#text-under-edge">text-under-edge</a> baseline. </dl> <div class="example" id="example-705d7900"> <a class="self-link" href="#example-705d7900"></a> <p>Line boxes almost always shift downward (towards the block-end direction) when snapping to a <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②③">line grid</a>. Here there are three lines with 20px line-height and line-snap:baseline that should snap to a 30px <span id="ref-for-line-grid②④">line grid</span>. Each line box shifts down so that the baselines align with the grid lines.</p> <figure style="float:left;"> <img alt="line positions before snapping" height="145" src="images/simple-no-snap.png" width="230"> <figcaption> Before line snapping </figcaption> </figure> <figure style="float:left;"> <img alt="line positions after snapping" height="146" src="images/simple-snapped.png" width="229"> <figcaption> After line snapping </figcaption> </figure> <p style="clear:left;"> In the figures below, there are two additional lines from h3 elements with line-snap:none. These lines do not shift to align to the grid, but their positions can change based on the shifting of lines around them. In this example, lines 1 2 and 3 shift down to snap their baselines to the grid lines, and line B has normal line box placement just below the line above. </p> <figure style="float:left;"> <img alt="line positions before snapping" height="269" src="images/top-no-snap.png" width="229"> <figcaption> Before line snapping </figcaption> </figure> <figure style="float:left;"> <img alt="line positions after snapping" height="269" src="images/top-snapped.png" width="229"> <figcaption> After line snapping </figcaption> </figure> </div> <h3 class="heading settled" data-level="3.2" id="box-snap"><span class="secno">3.2. </span><span class="content"> Snapping Block Boxes: the <a class="property css" data-link-type="property" href="#propdef-box-snap" id="ref-for-propdef-box-snap②">box-snap</a> property</span><a class="self-link" href="#box-snap"></a></h3> <p class="issue" id="issue-2aa6c022"><a class="self-link" href="#issue-2aa6c022"></a> This is a rough draft of trying to solve the box-snapping problem.</p> <p class="issue" id="issue-9431cf2e"><a class="self-link" href="#issue-9431cf2e"></a> Some optional box values (margin-box, border-box) could be added to the before and after values to allow snapping various box model edges to the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②⑤">line grid</a>.</p> <p class="issue" id="issue-7e5e0d99"><a class="self-link" href="#issue-7e5e0d99"></a> An auto value could be useful - one that defaults to center, but snaps to before if it’s the first block in a fragment container, and snaps to after if it’s the last block in a fragment container.</p> <table class="def propdef" data-link-for-hint="box-snap"> <tbody> <tr> <th>Name: <td><dfn class="dfn-paneled css" data-dfn-type="property" data-export id="propdef-box-snap">box-snap</dfn> <tr class="value"> <th><a href="https://www.w3.org/TR/css-values/#value-defs">Value:</a> <td class="prod">none <a data-link-type="grammar" href="https://drafts.csswg.org/css-values-4/#comb-one" id="ref-for-comb-one③">|</a> block-start <span id="ref-for-comb-one④">|</span> block-end <span id="ref-for-comb-one⑤">|</span> center <span id="ref-for-comb-one⑥">|</span> baseline <span id="ref-for-comb-one⑦">|</span> last-baseline <tr> <th><a href="https://www.w3.org/TR/css-cascade/#initial-values">Initial:</a> <td>none <tr> <th><a href="https://www.w3.org/TR/css-cascade/#applies-to">Applies to:</a> <td>block-level boxes and internal table elements except table cells <tr> <th><a href="https://www.w3.org/TR/css-cascade/#inherited-property">Inherited:</a> <td>yes <tr> <th><a href="https://www.w3.org/TR/css-values/#percentages">Percentages:</a> <td>N/A <tr> <th><a href="https://www.w3.org/TR/css-cascade/#computed">Computed value:</a> <td>as specified <tr> <th><a href="https://www.w3.org/TR/cssom/#serializing-css-values">Canonical order:</a> <td>per grammar <tr> <th><a href="https://www.w3.org/TR/web-animations/#animation-type">Animation type:</a> <td>discrete </table> <p>Specifies how the block is snapped to the baseline grid.</p> <p>Values have the following meanings:</p> <dl> <dt><dfn class="dfn-paneled css" data-dfn-for="box-snap" data-dfn-type="value" data-export id="valdef-box-snap-none">none</dfn> <dd>The block is not snapped to any grid. <dt><dfn class="dfn-paneled css" data-dfn-for="box-snap" data-dfn-type="value" data-export id="valdef-box-snap-block-start">block-start</dfn> <dd>The block-start edge is snapped to the nearest grid line. <dt><dfn class="dfn-paneled css" data-dfn-for="box-snap" data-dfn-type="value" data-export id="valdef-box-snap-block-end">block-end</dfn> <dd>The block-end edge is snapped to the nearest grid line. <dt><dfn class="dfn-paneled css" data-dfn-for="box-snap" data-dfn-type="value" data-export id="valdef-box-snap-center">center</dfn> <dd>The block is centered between one of the baseline grid’s text-over baselines and a subsequent (but not necessarily consecutive) text-under baseline. <dt><dfn class="dfn-paneled css" data-dfn-for="box-snap" data-dfn-type="value" data-export id="valdef-box-snap-baseline">baseline</dfn> <dd>The first line box’s dominant baseline is snapped to the nearest grid line. <dt><dfn class="dfn-paneled css" data-dfn-for="box-snap" data-dfn-type="value" data-export id="valdef-box-snap-last-baseline">last-baseline</dfn> <dd>The last line box’s dominant baseline is snapped to the nearest grid line. </dl> <p>Snapping block boxes always uses the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②⑥">line grid</a> of the box parent (a block’s own <span id="ref-for-line-grid②⑦">line grid</span> has no effect on box snapping). If the box is an empty block that could be <a href="https://www.w3.org/TR/CSS21/box.html">collapsed through</a>, then this property has no effect. <a data-link-type="biblio" href="#biblio-css2" title="Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification">[CSS2]</a></p> <p>To snap a block-level element to a grid line, take the unsnapped result of layout (including margin collapsing, clearance, etc.) as the block’s initial position, then shift the block downward (towards the block-end direction) until it snaps to the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②⑧">line grid</a>.</p> <p>For the <a class="css" data-link-type="maybe" href="#valdef-box-snap-block-start" id="ref-for-valdef-box-snap-block-start">block-start</a> and <a class="css" data-link-type="maybe" href="#valdef-box-snap-block-end" id="ref-for-valdef-box-snap-block-end">block-end</a> values, either the text-over-edge or text-under-edge baseline is chosen: whichever one is on the matching side of the central baseline. For example, when snapping the block-start edge in horizontal writing mode, the text-over-edge is chosen. In some cases the text-under-edge might be used instead for the block-start edge: for example, when the writing mode of the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid②⑨">line grid</a> doesn’t match that of the affected element, or when due to the <a class="property css" data-link-type="property" href="https://drafts.csswg.org/css-writing-modes-4/#propdef-text-orientation" id="ref-for-propdef-text-orientation">text-orientation</a> settings the text-under-edge corresponds to the block-start edge.</p> <p>When applied to table row group and table row boxes, <a class="property css" data-link-type="property" href="#propdef-box-snap" id="ref-for-propdef-box-snap③">box-snap</a> only affects the before and after edges, and only if those edges are not at the beginning or end of the table, respectively. To snap a before edge on a table row or row group, the preceding row’s height is increased. To snap an after edge on a table row or row group, the affected row’s height is increased.</p> <p>When applied to table column group and table column boxes, <a class="property css" data-link-type="property" href="#propdef-box-snap" id="ref-for-propdef-box-snap④">box-snap</a> only affects the start and end edges, and only if those edges are not at the start or end of the table, respectively. How the space is redistributed among columns to satisfy snapping constraints is not defined, however:</p> <ul> <li>In an auto-sized table no column may be smaller than its minimum content width. <li>The resulting table must not exceed its original measure if it had a non-auto measure. <li>The adjusted widths must not cause the table to overflow its containing block any more than it would with <a class="css" data-link-type="propdesc" href="#propdef-box-snap" id="ref-for-propdef-box-snap⑤">box-snap: none</a>. </ul> <p>To satisfy these constraints, some column edges may remain unsnapped.</p> <div class="issue" id="issue-829f143e"> <a class="self-link" href="#issue-829f143e"></a> Going forward, we could add a 2-d box-snap with more controls and to also extend it to handle snapping to an explicit layout grid (not just the baseline grid). Current thoughts are for box-snap to break out into longhands; the current block-snap property should thus be a subset of its expected future values. Below is an outline of the structure. (This may, of course, change.) <pre>box-snap +- block-snap | +- block-snap-edge | | +- block-start-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box" id="ref-for-typedef-shape-box"><shape-box></a> | | +- block-end-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box" id="ref-for-typedef-shape-box①"><shape-box></a> | +- block-snap-align: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-align-3/#typedef-content-position" id="ref-for-typedef-content-position"><content-position></a> | +- block-snap-grid: text-grid | <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-values-4/#identifier-value" id="ref-for-identifier-value"><custom-ident></a> /* name of grid/gridlines */ +- inline-snap +- inline-snap-edge | +- inline-start-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box" id="ref-for-typedef-shape-box②"><shape-box></a> | +- inline-end-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box" id="ref-for-typedef-shape-box③"><shape-box></a> +- inline-snap-align: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-align-3/#typedef-content-position" id="ref-for-typedef-content-position①"><content-position></a> +- inline-snap-grid: text-grid | <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-values-4/#identifier-value" id="ref-for-identifier-value①"><custom-ident></a> /* name of grid/gridlines */ where <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box" id="ref-for-typedef-shape-box④"><shape-box></a> includes margin-box | border-box | half-border-box | padding-box | content-box and <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-align-3/#typedef-content-position" id="ref-for-typedef-content-position②"><content-position></a> includes start | end | stretch | first-baseline | last-baseline | center </pre> </div> <h2 class="heading settled" data-level="4" id="snap-details"><span class="secno">4. </span><span class="content"> Snapping Details</span><a class="self-link" href="#snap-details"></a></h2> <h3 class="heading settled" data-level="4.1" id="alignment-interactions"><span class="secno">4.1. </span><span class="content"> Interacting with other alignments</span><a class="self-link" href="#alignment-interactions"></a></h3> <p>An element can have additional block layout constraints (such as centering or <a class="property css" data-link-type="property" href="#propdef-box-snap" id="ref-for-propdef-box-snap⑥">box-snap</a>) that can complicate line snapping. In these cases, implementations must produce the same result as the steps below:</p> <ul> <li> Line snap as if the layout constraint does not apply <li> Apply the layout constraint to the block <li> Adjust exactly one line box shift or space at the beginning or end of the block such that all of the snapping lines meet the <a data-link-type="dfn" href="#line-grid" id="ref-for-line-grid③⓪">line grid</a> while maintaining the block layout constraint. The single adjustment chosen must be the smallest shift needed to achieve the result without causing overflow. </ul> <div class="example" id="example-463a8867"> <a class="self-link" href="#example-463a8867"></a> <p>A block containing lines to snap might not be top-aligned within its container. In the figures below, the block containing the elements is centered. In a centered situation, you have to align baselines while maintaining centering. This can be done in two shift-and-center steps.</p> <p>First, shift the snapping lines as if the block was top-aligned (as in figure 9 above), then remove the shift for the very first snapping line. After removing the first shift, try centering the block. This is almost certain to throw the baseline alignment off. You can see one such result in the partial shifting figure below.</p> <p>Second, measure the distance from the first snapped line’s baseline to the grid lines above and below, looking for the closest grid line to that baseline.</p> <p>If the closest grid line is in the block-start direction, then add space below the last line in the block equal to twice that distance. Then the block is centered again, which will align all of the snapped lines to the grid.</p> <figure style="float:left;"> <img alt="line positions at step 1" height="270" src="images/first-center-part-snapped.png" width="229"> <figcaption> Partial shifting </figcaption> </figure> <figure style="float:left;"> <img alt="line positions after full snapping" height="269" src="images/first-center-snapped.png" width="229"> <figcaption> Full line snapping </figcaption> </figure> <p style="clear:left;"> If the closest grid line is in the block-end direction, then the first snapped line is shifted downward by twice that distance. Then the block is centered again, which will again align all of the snapped lines to the grid. </p> <figure style="float:left;"> <img alt="line positions at step 1" height="270" src="images/second-center-part-snapped.png" width="229"> <figcaption> Partial shifting </figcaption> </figure> <figure style="float:left;"> <img alt="line positions after full snapping" height="269" src="images/second-center-snapped.png" width="230"> <figcaption> Full line snapping </figcaption> </figure> </div> <div class="example" id="example-cd56247e"> <a class="self-link" href="#example-cd56247e"></a> <p>An end-aligned block also uses two steps, but is simpler than the centered case.</p> <p>First, shift the snapping lines as if there were no end-alignment (as in figure 9 above), then end-align the block.</p> <p>Second, shift the entire block contents upwards until the last snapped line aligns to a grid line. In this example, the shift is very minor.</p> <figure style="float:left;"> <img alt="line positions before snapping" height="269" src="images/bottom-no-snap.png" width="229"> <figcaption> Before snapping </figcaption> </figure> <figure style="float:left;"> <img alt="line positions after snapping" height="274" src="images/bottom-snapped.png" width="229"> <figcaption> After line snapping </figcaption> </figure> </div> <h3 class="heading settled" data-level="4.2" id="leading-adjustments"><span class="secno">4.2. </span><span class="content"> Leading adjustments</span><a class="self-link" href="#leading-adjustments"></a></h3> <p>In some cases lines of equal line height will not align perfectly to a baseline grid: this happens, for example, when fonts (of the same size) with different baseline tables are mixed on a line. In these cases, removing top half-leading can sometimes be the correct thing to do, but must be limited to the amount of baseline discrepancy so as not to trigger in other cases.</p> <p class="issue" id="issue-12524285"><a class="self-link" href="#issue-12524285"></a> Details to follow. It’s complicated when you have more than one font-size or line-height in a single line box.</p> <h2 class="no-num heading settled" id="acknowledgments"><span class="content">Acknowledgments</span><a class="self-link" href="#acknowledgments"></a></h2> <p>This module was made possible by the advice and contributions of Tab Atkins, Dave Cramer, Dave Hyatt, Bem Jones-Bey, Håkon Wium Lie, Shinyu Murakami, Liam Quin, and the CSS Working Group members.</p> <h2 class="no-num heading settled" id="change-log"><span class="content"> Change Log</span><a class="self-link" href="#change-log"></a></h2> <h3 class="no-num heading settled" id="20140916"><span class="content"> Since <a href="https://www.w3.org/TR/2014/WD-css-line-grid-1-20140916/">September 16th 2014</a></span><a class="self-link" href="#20140916"></a></h3> <ul> <li>Refined ICB/root/@page grid creation <li>Added flex and grid container applicability for line-grid <li>Added normative text for line-snap examples <li>Added @page and root element line grid handling <li>Made the dependency on line-height-step explicit <li><a class="css" data-link-type="maybe" href="#valdef-line-grid-match-parent" id="ref-for-valdef-line-grid-match-parent②">match-parent</a> creates new line grid for orthogonal flows </ul> <h3 class="no-num heading settled" id="20140403"><span class="content"> Since <a href="https://www.w3.org/TR/2014/WD-css-line-grid-1-20140403/">April 3rd 2014</a></span><a class="self-link" href="#20140403"></a></h3> <ul> <li>Added line-snapping examples <li>Modified box-snap values <li>Removed line-slack <li>Removed grid offset <li>Removed grid units <li>Removed 2d box snapping <li>Removed rounding functions </ul> <h2 class="no-num heading settled" id="privacy"><span class="content">Privacy Considerations</span><a class="self-link" href="#privacy"></a></h2> <p>No new privacy considerations have been reported on this specification.</p> <h2 class="no-num heading settled" id="security"><span class="content">Security Considerations</span><a class="self-link" href="#security"></a></h2> <p>No new security considerations have been reported on this specification.</p> </main> <h2 class="no-ref no-num heading settled" id="w3c-conformance"><span class="content"> Conformance</span><a class="self-link" href="#w3c-conformance"></a></h2> <h3 class="no-ref heading settled" id="w3c-conventions"><span class="content"> Document conventions</span><a class="self-link" href="#w3c-conventions"></a></h3> <p>Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification. </p> <p>All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. <a data-link-type="biblio" href="#biblio-rfc2119" title="Key words for use in RFCs to Indicate Requirement Levels">[RFC2119]</a></p> <p>Examples in this specification are introduced with the words “for example” or are set apart from the normative text with <code>class="example"</code>, like this: </p> <div class="example" id="w3c-example"> <a class="self-link" href="#w3c-example"></a> <p>This is an example of an informative example.</p> </div> <p>Informative notes begin with the word “Note” and are set apart from the normative text with <code>class="note"</code>, like this: </p> <p class="note" role="note">Note, this is an informative note.</p> <p>Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <code><strong class="advisement"></code>, like this: <strong class="advisement"> UAs MUST provide an accessible alternative. </strong></p> <details class="wpt-tests-block" dir="ltr" lang="en" open> <summary>Tests</summary> <p>Tests relating to the content of this specification may be documented in “Tests” blocks like this one. Any such block is non-normative.</p> <ul class="wpt-tests-list"></ul> <hr> </details> <h3 class="no-ref heading settled" id="w3c-conformance-classes"><span class="content"> Conformance classes</span><a class="self-link" href="#w3c-conformance-classes"></a></h3> <p>Conformance to this specification is defined for three conformance classes: </p> <dl> <dt>style sheet <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#style-sheet">CSS style sheet</a>. <dt>renderer <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> that interprets the semantics of a style sheet and renders documents that use them. <dt>authoring tool <dd>A <a href="http://www.w3.org/TR/CSS21/conform.html#user-agent">UA</a> that writes a style sheet. </dl> <p>A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module. </p> <p>A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.) </p> <p>An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module. </p> <h3 class="no-ref heading settled" id="w3c-partial"><span class="content"> Partial implementations</span><a class="self-link" href="#w3c-partial"></a></h3> <p>So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers <strong>must</strong> treat as invalid (and <a href="http://www.w3.org/TR/CSS21/conform.html#ignore">ignore as appropriate</a>) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents <strong>must not</strong> selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.</p> <h4 class="heading settled" id="w3c-conform-future-proofing"><span class="content"> Implementations of Unstable and Proprietary Features</span><a class="self-link" href="#w3c-conform-future-proofing"></a></h4> <p>To avoid clashes with future stable CSS features, the CSSWG recommends <a href="http://www.w3.org/TR/CSS/#future-proofing">following best practices</a> for the implementation of <a href="http://www.w3.org/TR/CSS/#unstable">unstable</a> features and <a href="http://www.w3.org/TR/CSS/#proprietary-extension">proprietary extensions</a> to CSS. </p> <h3 class="no-ref heading settled" id="w3c-testing"><span class="content"> Non-experimental implementations</span><a class="self-link" href="#w3c-testing"></a></h3> <p>Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec. </p> <p>To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group. </p> <p>Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at <a href="http://www.w3.org/Style/CSS/Test/">http://www.w3.org/Style/CSS/Test/</a>. Questions should be directed to the <a href="http://lists.w3.org/Archives/Public/public-css-testsuite">public-css-testsuite@w3.org</a> mailing list.</p> <script src="https://www.w3.org/scripts/TR/2021/fixup.js"></script> <h2 class="no-num no-ref heading settled" id="index"><span class="content">Index</span><a class="self-link" href="#index"></a></h2> <h3 class="no-num no-ref heading settled" id="index-defined-here"><span class="content">Terms defined by this specification</span><a class="self-link" href="#index-defined-here"></a></h3> <ul class="index"> <li> baseline <ul> <li><a href="#valdef-box-snap-baseline">value for box-snap</a><span>, in § 3.2</span> <li><a href="#valdef-line-snap-baseline">value for line-snap</a><span>, in § 3.1</span> </ul> <li><a href="#valdef-box-snap-block-end">block-end</a><span>, in § 3.2</span> <li><a href="#valdef-box-snap-block-start">block-start</a><span>, in § 3.2</span> <li><a href="#propdef-box-snap">box-snap</a><span>, in § 3.2</span> <li><a href="#valdef-box-snap-center">center</a><span>, in § 3.2</span> <li><a href="#valdef-line-snap-contain">contain</a><span>, in § 3.1</span> <li><a href="#valdef-line-grid-create">create</a><span>, in § 2</span> <li><a href="#valdef-box-snap-last-baseline">last-baseline</a><span>, in § 3.2</span> <li><a href="#line-grid">Line Grid</a><span>, in § 2</span> <li><a href="#propdef-line-grid">line-grid</a><span>, in § 2</span> <li><a href="#propdef-line-snap">line-snap</a><span>, in § 3.1</span> <li><a href="#valdef-line-grid-match-parent">match-parent</a><span>, in § 2</span> <li> none <ul> <li><a href="#valdef-box-snap-none">value for box-snap</a><span>, in § 3.2</span> <li><a href="#valdef-line-snap-none">value for line-snap</a><span>, in § 3.1</span> </ul> </ul> <h3 class="no-num no-ref heading settled" id="index-defined-elsewhere"><span class="content">Terms defined by reference</span><a class="self-link" href="#index-defined-elsewhere"></a></h3> <ul class="index"> <li> <a data-link-type="biblio">[CSS-ALIGN-3]</a> defines the following terms: <ul> <li><span class="dfn-paneled" id="aadd356f"><content-position></span> </ul> <li> <a data-link-type="biblio">[CSS-DISPLAY-4]</a> defines the following terms: <ul> <li><span class="dfn-paneled" id="9f3d4f17">block container</span> </ul> <li> <a data-link-type="biblio">[CSS-RHYTHM-1]</a> defines the following terms: <ul> <li><span class="dfn-paneled" id="2d625495">line-height-step</span> </ul> <li> <a data-link-type="biblio">[CSS-SHAPES-1]</a> defines the following terms: <ul> <li><span class="dfn-paneled" id="f2024dbb"><shape-box></span> </ul> <li> <a data-link-type="biblio">[CSS-VALUES-4]</a> defines the following terms: <ul> <li><span class="dfn-paneled" id="e274345c"><custom-ident></span> <li><span class="dfn-paneled" id="358fd6ff">CSS-wide keywords</span> <li><span class="dfn-paneled" id="6ec67710">|</span> </ul> <li> <a data-link-type="biblio">[CSS-WRITING-MODES-4]</a> defines the following terms: <ul> <li><span class="dfn-paneled" id="3bd4bbe9">text-orientation</span> <li><span class="dfn-paneled" id="a73617e0">writing mode</span> </ul> <li> <a data-link-type="biblio">[MEDIAQUERIES-5]</a> defines the following terms: <ul> <li><span class="dfn-paneled" id="758665a5">paged media</span> </ul> </ul> <h2 class="no-num no-ref heading settled" id="references"><span class="content">References</span><a class="self-link" href="#references"></a></h2> <h3 class="no-num no-ref heading settled" id="normative"><span class="content">Normative References</span><a class="self-link" href="#normative"></a></h3> <dl> <dt id="biblio-css-align-3">[CSS-ALIGN-3] <dd>Elika Etemad; Tab Atkins Jr.. <a href="https://drafts.csswg.org/css-align/"><cite>CSS Box Alignment Module Level 3</cite></a>. URL: <a href="https://drafts.csswg.org/css-align/">https://drafts.csswg.org/css-align/</a> <dt id="biblio-css-display-4">[CSS-DISPLAY-4] <dd>Elika Etemad; Tab Atkins Jr.. <a href="https://drafts.csswg.org/css-display/"><cite>CSS Display Module Level 4</cite></a>. URL: <a href="https://drafts.csswg.org/css-display/">https://drafts.csswg.org/css-display/</a> <dt id="biblio-css-rhythm-1">[CSS-RHYTHM-1] <dd>Koji Ishii; Elika Etemad. <a href="https://drafts.csswg.org/css-rhythm/"><cite>CSS Rhythmic Sizing</cite></a>. URL: <a href="https://drafts.csswg.org/css-rhythm/">https://drafts.csswg.org/css-rhythm/</a> <dt id="biblio-css-shapes-1">[CSS-SHAPES-1] <dd>Rossen Atanassov; Alan Stearns. <a href="https://drafts.csswg.org/css-shapes/"><cite>CSS Shapes Module Level 1</cite></a>. URL: <a href="https://drafts.csswg.org/css-shapes/">https://drafts.csswg.org/css-shapes/</a> <dt id="biblio-css-values-3">[CSS-VALUES-3] <dd>Tab Atkins Jr.; Elika Etemad. <a href="https://drafts.csswg.org/css-values-3/"><cite>CSS Values and Units Module Level 3</cite></a>. URL: <a href="https://drafts.csswg.org/css-values-3/">https://drafts.csswg.org/css-values-3/</a> <dt id="biblio-css-values-4">[CSS-VALUES-4] <dd>Tab Atkins Jr.; Elika Etemad. <a href="https://drafts.csswg.org/css-values-4/"><cite>CSS Values and Units Module Level 4</cite></a>. URL: <a href="https://drafts.csswg.org/css-values-4/">https://drafts.csswg.org/css-values-4/</a> <dt id="biblio-css-writing-modes-4">[CSS-WRITING-MODES-4] <dd>Elika Etemad; Koji Ishii. <a href="https://drafts.csswg.org/css-writing-modes-4/"><cite>CSS Writing Modes Level 4</cite></a>. URL: <a href="https://drafts.csswg.org/css-writing-modes-4/">https://drafts.csswg.org/css-writing-modes-4/</a> <dt id="biblio-css2">[CSS2] <dd>Bert Bos; et al. <a href="https://drafts.csswg.org/css2/"><cite>Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification</cite></a>. URL: <a href="https://drafts.csswg.org/css2/">https://drafts.csswg.org/css2/</a> <dt id="biblio-mediaqueries-5">[MEDIAQUERIES-5] <dd>Dean Jackson; et al. <a href="https://drafts.csswg.org/mediaqueries-5/"><cite>Media Queries Level 5</cite></a>. URL: <a href="https://drafts.csswg.org/mediaqueries-5/">https://drafts.csswg.org/mediaqueries-5/</a> <dt id="biblio-rfc2119">[RFC2119] <dd>S. Bradner. <a href="https://datatracker.ietf.org/doc/html/rfc2119"><cite>Key words for use in RFCs to Indicate Requirement Levels</cite></a>. March 1997. Best Current Practice. URL: <a href="https://datatracker.ietf.org/doc/html/rfc2119">https://datatracker.ietf.org/doc/html/rfc2119</a> </dl> <h3 class="no-num no-ref heading settled" id="informative"><span class="content">Informative References</span><a class="self-link" href="#informative"></a></h3> <dl> <dt id="biblio-css3line">[CSS3LINE] <dd>Elika Etemad. <a href="https://drafts.csswg.org/css-inline-3/"><cite>CSS Inline Layout Module Level 3</cite></a>. URL: <a href="https://drafts.csswg.org/css-inline-3/">https://drafts.csswg.org/css-inline-3/</a> <dt id="biblio-jlreq">[JLREQ] <dd>Hiroyuki Chiba; et al. <a href="https://w3c.github.io/jlreq/"><cite>Requirements for Japanese Text Layout 日本語組版処理の要件(日本語版)</cite></a>. URL: <a href="https://w3c.github.io/jlreq/">https://w3c.github.io/jlreq/</a> </dl> <h2 class="no-num no-ref heading settled" id="property-index"><span class="content">Property Index</span><a class="self-link" href="#property-index"></a></h2> <div class="big-element-wrapper"> <table class="index"> <thead> <tr> <th scope="col">Name <th scope="col">Value <th scope="col">Initial <th scope="col">Applies to <th scope="col">Inh. <th scope="col">%ages <th scope="col">Animation type <th scope="col">Canonical order <th scope="col">Computed value <tbody> <tr> <th scope="row"><a class="css" data-link-type="property" href="#propdef-box-snap" id="ref-for-propdef-box-snap⑦">box-snap</a> <td>none | block-start | block-end | center | baseline | last-baseline <td>none <td>block-level boxes and internal table elements except table cells <td>yes <td>N/A <td>discrete <td>per grammar <td>as specified <tr> <th scope="row"><a class="css" data-link-type="property" href="#propdef-line-grid" id="ref-for-propdef-line-grid④">line-grid</a> <td>match-parent | create <td>match-parent <td>block, flex and grid containers <td>no <td>N/A <td>discrete <td>per grammar <td>specified keyword <tr> <th scope="row"><a class="css" data-link-type="property" href="#propdef-line-snap" id="ref-for-propdef-line-snap③">line-snap</a> <td>none | baseline | contain <td>none <td>block container elements <td>yes <td>N/A <td>discrete <td>per grammar <td>specified keyword </table> </div> <h2 class="no-num no-ref heading settled" id="issues-index"><span class="content">Issues Index</span><a class="self-link" href="#issues-index"></a></h2> <div style="counter-reset:issue"> <div class="issue"> The names of these values is currently up for debate. Current suggestions for match-parent include match-parent and normal; those for create include create and new. <a class="issue-return" href="#issue-aa203f7b" title="Jump to section">↵</a></div> <div class="issue"> This is a rough draft of trying to solve the box-snapping problem. <a class="issue-return" href="#issue-2aa6c022" title="Jump to section">↵</a></div> <div class="issue"> Some optional box values (margin-box, border-box) could be added to the before and after values to allow snapping various box model edges to the <a data-link-type="dfn" href="#line-grid">line grid</a>. <a class="issue-return" href="#issue-9431cf2e" title="Jump to section">↵</a></div> <div class="issue"> An auto value could be useful - one that defaults to center, but snaps to before if it’s the first block in a fragment container, and snaps to after if it’s the last block in a fragment container. <a class="issue-return" href="#issue-7e5e0d99" title="Jump to section">↵</a></div> <div class="issue"> Going forward, we could add a 2-d box-snap with more controls and to also extend it to handle snapping to an explicit layout grid (not just the baseline grid). Current thoughts are for box-snap to break out into longhands; the current block-snap property should thus be a subset of its expected future values. Below is an outline of the structure. (This may, of course, change.) <pre>box-snap +- block-snap | +- block-snap-edge | | +- block-start-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box"><shape-box></a> | | +- block-end-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box"><shape-box></a> | +- block-snap-align: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-align-3/#typedef-content-position"><content-position></a> | +- block-snap-grid: text-grid | <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-values-4/#identifier-value"><custom-ident></a> /* name of grid/gridlines */ +- inline-snap +- inline-snap-edge | +- inline-start-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box"><shape-box></a> | +- inline-end-snap-edge: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box"><shape-box></a> +- inline-snap-align: <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-align-3/#typedef-content-position"><content-position></a> +- inline-snap-grid: text-grid | <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-values-4/#identifier-value"><custom-ident></a> /* name of grid/gridlines */ where <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-shapes-1/#typedef-shape-box"><shape-box></a> includes margin-box | border-box | half-border-box | padding-box | content-box and <a class="production" data-link-type="type" href="https://drafts.csswg.org/css-align-3/#typedef-content-position"><content-position></a> includes start | end | stretch | first-baseline | last-baseline | center </pre> <a class="issue-return" href="#issue-829f143e" title="Jump to section">↵</a> </div> <div class="issue"> Details to follow. It’s complicated when you have more than one font-size or line-height in a single line box. <a class="issue-return" href="#issue-12524285" title="Jump to section">↵</a></div> </div> <script>/* Boilerplate: script-dom-helper */ "use strict"; function query(sel) { return document.querySelector(sel); } function queryAll(sel) { return [...document.querySelectorAll(sel)]; } function iter(obj) { if(!obj) return []; var it = obj[Symbol.iterator]; if(it) return it; return Object.entries(obj); } function mk(tagname, attrs, ...children) { const el = document.createElement(tagname); for(const [k,v] of iter(attrs)) { if(k.slice(0,3) == "_on") { const eventName = k.slice(3); el.addEventListener(eventName, v); } else if(k[0] == "_") { // property, not attribute el[k.slice(1)] = v; } else { if(v === false || v == null) { continue; } else if(v === true) { el.setAttribute(k, ""); continue; } else { el.setAttribute(k, v); } } } append(el, children); return el; } /* Create shortcuts for every known HTML element */ [ "a", "abbr", "acronym", "address", "applet", "area", "article", "aside", "audio", "b", "base", "basefont", "bdo", "big", "blockquote", "body", "br", "button", "canvas", "caption", "center", "cite", "code", "col", "colgroup", "datalist", "dd", "del", "details", "dfn", "dialog", "div", "dl", "dt", "em", "embed", "fieldset", "figcaption", "figure", "font", "footer", "form", "frame", "frameset", "head", "header", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "html", "i", "iframe", "img", "input", "ins", "kbd", "label", "legend", "li", "link", "main", "map", "mark", "meta", "meter", "nav", "nobr", "noscript", "object", "ol", "optgroup", "option", "output", "p", "param", "pre", "progress", "q", "s", "samp", "script", "section", "select", "small", "source", "span", "strike", "strong", "style", "sub", "summary", "sup", "table", "tbody", "td", "template", "textarea", "tfoot", "th", "thead", "time", "title", "tr", "u", "ul", "var", "video", "wbr", "xmp", ].forEach(tagname=>{ mk[tagname] = (...args) => mk(tagname, ...args); }); function* nodesFromChildList(children) { for(const child of children.flat(Infinity)) { if(child instanceof Node) { yield child; } else { yield new Text(child); } } } function append(el, ...children) { for(const child of nodesFromChildList(children)) { if(el instanceof Node) el.appendChild(child); else el.push(child); } return el; } function insertAfter(el, ...children) { for(const child of nodesFromChildList(children)) { el.parentNode.insertBefore(child, el.nextSibling); } return el; } function clearContents(el) { el.innerHTML = ""; return el; } function parseHTML(markup) { if(markup.toLowerCase().trim().indexOf('<!doctype') === 0) { const doc = document.implementation.createHTMLDocument(""); doc.documentElement.innerHTML = markup; return doc; } else { const el = mk.template({}); el.innerHTML = markup; return el.content; } }</script> <script>/* Boilerplate: script-dfn-panel */ "use strict"; { let dfnPanelData = { "2d625495": {"dfnID":"2d625495","dfnText":"line-height-step","external":true,"refSections":[{"refs":[{"id":"ref-for-propdef-line-height-step"}],"title":"2. \nDefining a Line Grid: the line-grid property"}],"url":"https://drafts.csswg.org/css-rhythm-1/#propdef-line-height-step"}, "358fd6ff": {"dfnID":"358fd6ff","dfnText":"CSS-wide keywords","external":true,"refSections":[{"refs":[{"id":"ref-for-css-wide-keywords"}],"title":"1.3. \nValue Definitions"}],"url":"https://drafts.csswg.org/css-values-4/#css-wide-keywords"}, "3bd4bbe9": {"dfnID":"3bd4bbe9","dfnText":"text-orientation","external":true,"refSections":[{"refs":[{"id":"ref-for-propdef-text-orientation"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"}],"url":"https://drafts.csswg.org/css-writing-modes-4/#propdef-text-orientation"}, "6ec67710": {"dfnID":"6ec67710","dfnText":"|","external":true,"refSections":[{"refs":[{"id":"ref-for-comb-one"}],"title":"2. \nDefining a Line Grid: the line-grid property"},{"refs":[{"id":"ref-for-comb-one\u2460"},{"id":"ref-for-comb-one\u2461"}],"title":"3.1. \nSnapping Line Boxes: the line-snap property"},{"refs":[{"id":"ref-for-comb-one\u2462"},{"id":"ref-for-comb-one\u2463"},{"id":"ref-for-comb-one\u2464"},{"id":"ref-for-comb-one\u2465"},{"id":"ref-for-comb-one\u2466"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"}],"url":"https://drafts.csswg.org/css-values-4/#comb-one"}, "758665a5": {"dfnID":"758665a5","dfnText":"paged media","external":true,"refSections":[{"refs":[{"id":"ref-for-paged-media"}],"title":"2. \nDefining a Line Grid: the line-grid property"}],"url":"https://drafts.csswg.org/mediaqueries-5/#paged-media"}, "9f3d4f17": {"dfnID":"9f3d4f17","dfnText":"block container","external":true,"refSections":[{"refs":[{"id":"ref-for-block-container"}],"title":"3.1. \nSnapping Line Boxes: the line-snap property"}],"url":"https://drafts.csswg.org/css-display-4/#block-container"}, "a73617e0": {"dfnID":"a73617e0","dfnText":"writing mode","external":true,"refSections":[{"refs":[{"id":"ref-for-writing-mode"},{"id":"ref-for-writing-mode\u2460"}],"title":"2. \nDefining a Line Grid: the line-grid property"}],"url":"https://drafts.csswg.org/css-writing-modes-4/#writing-mode"}, "aadd356f": {"dfnID":"aadd356f","dfnText":"<content-position>","external":true,"refSections":[{"refs":[{"id":"ref-for-typedef-content-position"},{"id":"ref-for-typedef-content-position\u2460"},{"id":"ref-for-typedef-content-position\u2461"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"}],"url":"https://drafts.csswg.org/css-align-3/#typedef-content-position"}, "e274345c": {"dfnID":"e274345c","dfnText":"<custom-ident>","external":true,"refSections":[{"refs":[{"id":"ref-for-identifier-value"},{"id":"ref-for-identifier-value\u2460"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"}],"url":"https://drafts.csswg.org/css-values-4/#identifier-value"}, "f2024dbb": {"dfnID":"f2024dbb","dfnText":"<shape-box>","external":true,"refSections":[{"refs":[{"id":"ref-for-typedef-shape-box"},{"id":"ref-for-typedef-shape-box\u2460"},{"id":"ref-for-typedef-shape-box\u2461"},{"id":"ref-for-typedef-shape-box\u2462"},{"id":"ref-for-typedef-shape-box\u2463"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"}],"url":"https://drafts.csswg.org/css-shapes-1/#typedef-shape-box"}, "line-grid": {"dfnID":"line-grid","dfnText":"Line Grid","external":false,"refSections":[{"refs":[{"id":"ref-for-line-grid"},{"id":"ref-for-line-grid\u2460"},{"id":"ref-for-line-grid\u2461"},{"id":"ref-for-line-grid\u2462"},{"id":"ref-for-line-grid\u2463"},{"id":"ref-for-line-grid\u2464"},{"id":"ref-for-line-grid\u2465"},{"id":"ref-for-line-grid\u2466"},{"id":"ref-for-line-grid\u2467"},{"id":"ref-for-line-grid\u2468"},{"id":"ref-for-line-grid\u2460\u24ea"},{"id":"ref-for-line-grid\u2460\u2460"},{"id":"ref-for-line-grid\u2460\u2461"},{"id":"ref-for-line-grid\u2460\u2462"},{"id":"ref-for-line-grid\u2460\u2463"},{"id":"ref-for-line-grid\u2460\u2464"},{"id":"ref-for-line-grid\u2460\u2465"},{"id":"ref-for-line-grid\u2460\u2466"},{"id":"ref-for-line-grid\u2460\u2467"},{"id":"ref-for-line-grid\u2460\u2468"}],"title":"2. \nDefining a Line Grid: the line-grid property"},{"refs":[{"id":"ref-for-line-grid\u2461\u24ea"}],"title":"3. \nSnapping to a Grid"},{"refs":[{"id":"ref-for-line-grid\u2461\u2460"},{"id":"ref-for-line-grid\u2461\u2461"},{"id":"ref-for-line-grid\u2461\u2462"},{"id":"ref-for-line-grid\u2461\u2463"}],"title":"3.1. \nSnapping Line Boxes: the line-snap property"},{"refs":[{"id":"ref-for-line-grid\u2461\u2464"},{"id":"ref-for-line-grid\u2461\u2465"},{"id":"ref-for-line-grid\u2461\u2466"},{"id":"ref-for-line-grid\u2461\u2467"},{"id":"ref-for-line-grid\u2461\u2468"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"},{"refs":[{"id":"ref-for-line-grid\u2462\u24ea"}],"title":"4.1. \nInteracting with other alignments"}],"url":"#line-grid"}, "propdef-box-snap": {"dfnID":"propdef-box-snap","dfnText":"box-snap","external":false,"refSections":[{"refs":[{"id":"ref-for-propdef-box-snap"}],"title":"2. \nDefining a Line Grid: the line-grid property"},{"refs":[{"id":"ref-for-propdef-box-snap\u2460"}],"title":"3. \nSnapping to a Grid"},{"refs":[{"id":"ref-for-propdef-box-snap\u2461"},{"id":"ref-for-propdef-box-snap\u2462"},{"id":"ref-for-propdef-box-snap\u2463"},{"id":"ref-for-propdef-box-snap\u2464"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"},{"refs":[{"id":"ref-for-propdef-box-snap\u2465"}],"title":"4.1. \nInteracting with other alignments"}],"url":"#propdef-box-snap"}, "propdef-line-grid": {"dfnID":"propdef-line-grid","dfnText":"line-grid","external":false,"refSections":[{"refs":[{"id":"ref-for-propdef-line-grid"},{"id":"ref-for-propdef-line-grid\u2460"},{"id":"ref-for-propdef-line-grid\u2461"}],"title":"2. \nDefining a Line Grid: the line-grid property"},{"refs":[{"id":"ref-for-propdef-line-grid\u2462"}],"title":"3.1. \nSnapping Line Boxes: the line-snap property"}],"url":"#propdef-line-grid"}, "propdef-line-snap": {"dfnID":"propdef-line-snap","dfnText":"line-snap","external":false,"refSections":[{"refs":[{"id":"ref-for-propdef-line-snap"}],"title":"2. \nDefining a Line Grid: the line-grid property"},{"refs":[{"id":"ref-for-propdef-line-snap\u2460"}],"title":"3. \nSnapping to a Grid"},{"refs":[{"id":"ref-for-propdef-line-snap\u2461"}],"title":"3.1. \nSnapping Line Boxes: the line-snap property"}],"url":"#propdef-line-snap"}, "valdef-box-snap-baseline": {"dfnID":"valdef-box-snap-baseline","dfnText":"baseline","external":false,"refSections":[],"url":"#valdef-box-snap-baseline"}, "valdef-box-snap-block-end": {"dfnID":"valdef-box-snap-block-end","dfnText":"block-end","external":false,"refSections":[{"refs":[{"id":"ref-for-valdef-box-snap-block-end"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"}],"url":"#valdef-box-snap-block-end"}, "valdef-box-snap-block-start": {"dfnID":"valdef-box-snap-block-start","dfnText":"block-start","external":false,"refSections":[{"refs":[{"id":"ref-for-valdef-box-snap-block-start"}],"title":"3.2. \nSnapping Block Boxes: the box-snap property"}],"url":"#valdef-box-snap-block-start"}, "valdef-box-snap-center": {"dfnID":"valdef-box-snap-center","dfnText":"center","external":false,"refSections":[],"url":"#valdef-box-snap-center"}, "valdef-box-snap-last-baseline": {"dfnID":"valdef-box-snap-last-baseline","dfnText":"last-baseline","external":false,"refSections":[],"url":"#valdef-box-snap-last-baseline"}, "valdef-box-snap-none": {"dfnID":"valdef-box-snap-none","dfnText":"none","external":false,"refSections":[],"url":"#valdef-box-snap-none"}, "valdef-line-grid-create": {"dfnID":"valdef-line-grid-create","dfnText":"create","external":false,"refSections":[{"refs":[{"id":"ref-for-valdef-line-grid-create"}],"title":"2. \nDefining a Line Grid: the line-grid property"}],"url":"#valdef-line-grid-create"}, "valdef-line-grid-match-parent": {"dfnID":"valdef-line-grid-match-parent","dfnText":"match-parent","external":false,"refSections":[{"refs":[{"id":"ref-for-valdef-line-grid-match-parent"},{"id":"ref-for-valdef-line-grid-match-parent\u2460"}],"title":"2. \nDefining a Line Grid: the line-grid property"},{"refs":[{"id":"ref-for-valdef-line-grid-match-parent\u2461"}],"title":"\nSince September 16th 2014"}],"url":"#valdef-line-grid-match-parent"}, "valdef-line-snap-baseline": {"dfnID":"valdef-line-snap-baseline","dfnText":"baseline","external":false,"refSections":[],"url":"#valdef-line-snap-baseline"}, "valdef-line-snap-contain": {"dfnID":"valdef-line-snap-contain","dfnText":"contain","external":false,"refSections":[],"url":"#valdef-line-snap-contain"}, "valdef-line-snap-none": {"dfnID":"valdef-line-snap-none","dfnText":"none","external":false,"refSections":[],"url":"#valdef-line-snap-none"}, }; document.addEventListener("DOMContentLoaded", ()=>{ genAllDfnPanels(); document.body.addEventListener("click", (e) => { // If not handled already, just hide all dfn panels. hideAllDfnPanels(); }); }); window.addEventListener("resize", () => { // Pin any visible dfn panel queryAll(".dfn-panel.on, .dfn-panel.activated").forEach(el=>positionDfnPanel(el)); }); function genAllDfnPanels() { for(const panelData of Object.values(dfnPanelData)) { const dfnID = panelData.dfnID; const dfn = document.getElementById(dfnID); if(!dfn) { console.log(`Can't find dfn#${dfnID}.`, panelData); continue; } dfn.panelData = panelData; insertDfnPopupAction(dfn); } } function genDfnPanel(dfn, { dfnID, url, dfnText, refSections, external }) { const dfnPanel = mk.aside({ class: "dfn-panel on", id: `infopanel-for-${dfnID}`, "data-for": dfnID, "aria-labelled-by":`infopaneltitle-for-${dfnID}`, }, mk.span({id:`infopaneltitle-for-${dfnID}`, style:"display:none"}, `Info about the '${dfnText}' ${external?"external":""} reference.`), mk.a({href:url, class:"dfn-link"}, url), refSections.length == 0 ? [] : mk.b({}, "Referenced in:"), mk.ul({}, ...refSections.map(section=> mk.li({}, ...section.refs.map((ref, refI)=> [ mk.a({ href: `#${ref.id}` }, (refI == 0) ? section.title : `(${refI + 1})` ), " ", ] ), ), ), ), genLinkingSyntaxes(dfn), ); dfnPanel.addEventListener('click', (event) => { if (event.target.nodeName == 'A') { scrollToTargetAndHighlight(event); pinDfnPanel(dfnPanel); } event.stopPropagation(); refocusOnTarget(event); }); dfnPanel.addEventListener('keydown', (event) => { if(event.keyCode == 27) { // Escape key hideDfnPanel({dfnPanel}); event.stopPropagation(); event.preventDefault(); } }); dfnPanel.dfn = dfn; dfn.dfnPanel = dfnPanel; return dfnPanel; } function hideAllDfnPanels() { // Delete the currently-active dfn panel. queryAll(".dfn-panel").forEach(dfnPanel=>hideDfnPanel({dfnPanel})); } function showDfnPanel(dfn) { hideAllDfnPanels(); // Only display one at a time. dfn.setAttribute("aria-expanded", "true"); const dfnPanel = genDfnPanel(dfn, dfn.panelData); // Give the dfn a unique tabindex, and then // give all the tabbable panel bits successive indexes. let tabIndex = 100; dfn.tabIndex = tabIndex++; const tabbable = dfnPanel.querySelectorAll(":is(a, button)"); for (const el of tabbable) { el.tabIndex = tabIndex++; } append(document.body, dfnPanel); positionDfnPanel(dfnPanel); } function positionDfnPanel(dfnPanel) { const dfn = dfnPanel.dfn; const dfnPos = getBounds(dfn); dfnPanel.style.top = dfnPos.bottom + "px"; dfnPanel.style.left = dfnPos.left + "px"; const panelPos = dfnPanel.getBoundingClientRect(); const panelMargin = 8; const maxRight = document.body.parentNode.clientWidth - panelMargin; if (panelPos.right > maxRight) { const overflowAmount = panelPos.right - maxRight; const newLeft = Math.max(panelMargin, dfnPos.left - overflowAmount); dfnPanel.style.left = newLeft + "px"; } } function pinDfnPanel(dfnPanel) { // Switch it to "activated" state, which pins it. dfnPanel.classList.add("activated"); dfnPanel.style.position = "fixed"; dfnPanel.style.left = null; dfnPanel.style.top = null; } function hideDfnPanel({dfn, dfnPanel}) { if(!dfnPanel) dfnPanel = dfn.dfnPanel; if(!dfn) dfn = dfnPanel.dfn; dfn.dfnPanel = undefined; dfnPanel.dfn = undefined; dfn.setAttribute("aria-expanded", "false"); dfn.tabIndex = undefined; dfnPanel.remove() } function toggleDfnPanel(dfn) { if(dfn.dfnPanel) { hideDfnPanel(dfn); } else { showDfnPanel(dfn); } } function insertDfnPopupAction(dfn) { dfn.setAttribute('role', 'button'); dfn.setAttribute('aria-expanded', 'false') dfn.tabIndex = 0; dfn.classList.add('has-dfn-panel'); dfn.addEventListener('click', (event) => { toggleDfnPanel(dfn); event.stopPropagation(); }); dfn.addEventListener('keypress', (event) => { const kc = event.keyCode; // 32->Space, 13->Enter if(kc == 32 || kc == 13) { toggleDfnPanel(dfn); event.stopPropagation(); event.preventDefault(); } }); } function refocusOnTarget(event) { const target = event.target; setTimeout(() => { // Refocus on the event.target element. // This is needed after browser scrolls to the destination. target.focus(); }); } // TODO: shared util // Returns the root-level absolute position {left and top} of element. function getBounds(el, relativeTo=document.body) { const relativeRect = relativeTo.getBoundingClientRect(); const elRect = el.getBoundingClientRect(); const top = elRect.top - relativeRect.top; const left = elRect.left - relativeRect.left; return { top, left, bottom: top + elRect.height, right: left + elRect.width, } } function scrollToTargetAndHighlight(event) { let hash = event.target.hash; if (hash) { hash = decodeURIComponent(hash.substring(1)); const dest = document.getElementById(hash); if (dest) { dest.classList.add('highlighted'); setTimeout(() => dest.classList.remove('highlighted'), 1000); } } } // Functions, divided by link type, that wrap an autolink's // contents with the appropriate outer syntax. // Alternately, a string naming another type they format // the same as. function needsFor(type) { switch(type) { case "descriptor": case "value": case "element-attr": case "attr-value": case "element-state": case "method": case "constructor": case "argument": case "attribute": case "const": case "dict-member": case "event": case "enum-value": case "stringifier": case "serializer": case "iterator": case "maplike": case "setlike": case "state": case "mode": case "context": case "facet": return true; default: return false; } } function refusesFor(type) { switch(type) { case "property": case "element": case "interface": case "namespace": case "callback": case "dictionary": case "enum": case "exception": case "typedef": case "http-header": case "permission": return true; default: return false; } } function linkFormatterFromType(type) { switch(type) { case 'scheme': case 'permission': case 'dfn': return (text) => `[=${text}=]`; case 'abstract-op': return (text) => `[\$${text}\$]`; case 'function': case 'at-rule': case 'selector': case 'value': return (text) => `''${text}''`; case 'http-header': return (text) => `[:${text}:]`; case 'interface': case 'constructor': case 'method': case 'argument': case 'attribute': case 'callback': case 'dictionary': case 'dict-member': case 'enum': case 'enum-value': case 'exception': case 'const': case 'typedef': case 'stringifier': case 'serializer': case 'iterator': case 'maplike': case 'setlike': case 'extended-attribute': case 'event': case 'idl': return (text) => `{{${text}}}`; case 'element-state': case 'element-attr': case 'attr-value': case 'element': return (element) => `<{${element}}>`; case 'grammar': return (text) => `${text} (within a <pre class=prod>)`; case 'type': return (text)=> `<<${text}>>`; case 'descriptor': case 'property': return (text) => `'${text}'`; default: return; }; }; function genLinkingSyntaxes(dfn) { if(dfn.tagName != "DFN") return; const type = dfn.getAttribute('data-dfn-type'); if(!type) { console.log(`<dfn> doesn't have a data-dfn-type:`, dfn); return []; } // Return a function that wraps link text based on the type const linkFormatter = linkFormatterFromType(type); if(!linkFormatter) { console.log(`<dfn> has an unknown data-dfn-type:`, dfn); return []; } let ltAlts; if(dfn.hasAttribute('data-lt')) { ltAlts = dfn.getAttribute('data-lt') .split("|") .map(x=>x.trim()); } else { ltAlts = [dfn.textContent.trim()]; } if(type == "type") { // lt of "<foo>", but "foo" is the interior; // <<foo/bar>> is how you write it with a for, // not <foo/<bar>> or whatever. for(var i = 0; i < ltAlts.length; i++) { const lt = ltAlts[i]; const match = /<(.*)>/.exec(lt); if(match) { ltAlts[i] = match[1]; } } } let forAlts; if(dfn.hasAttribute('data-dfn-for')) { forAlts = dfn.getAttribute('data-dfn-for') .split(",") .map(x=>x.trim()); } else { forAlts = ['']; } let linkingSyntaxes = []; if(!needsFor(type)) { for(const lt of ltAlts) { linkingSyntaxes.push(linkFormatter(lt)); } } if(!refusesFor(type)) { for(const f of forAlts) { linkingSyntaxes.push(linkFormatter(`${f}/${ltAlts[0]}`)) } } return [ mk.b({}, 'Possible linking syntaxes:'), mk.ul({}, ...linkingSyntaxes.map(link => { const copyLink = async () => await navigator.clipboard.writeText(link); return mk.li({}, mk.div({ class: 'link-item' }, mk.button({ class: 'copy-icon', title: 'Copy', type: 'button', _onclick: copyLink, tabindex: 0, }, mk.span({ class: 'icon' }) ), mk.span({}, link) ) ); }) ) ]; } } </script> <script>/* Boilerplate: script-link-titles */ "use strict"; { let linkTitleData = { "https://drafts.csswg.org/css-align-3/#typedef-content-position": "Expands to: center | end | flex-end | flex-start | start", "https://drafts.csswg.org/css-shapes-1/#typedef-shape-box": "Expands to: border-box | content-box | margin-box | padding-box", }; function setTypeTitles() { for(let el of document.querySelectorAll("a[href]")) { if(el.href in linkTitleData && !el.hasAttribute("title")) { el.setAttribute("title", linkTitleData[el.href]); } } } document.addEventListener("DOMContentLoaded", setTypeTitles); } </script> <script>/* Boilerplate: script-ref-hints */ "use strict"; { let refsData = { "#line-grid": {"displayText":"line grid","export":true,"for_":[],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"line grid","type":"dfn","url":"#line-grid"}, "#propdef-box-snap": {"displayText":"box-snap","export":true,"for_":[],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"box-snap","type":"property","url":"#propdef-box-snap"}, "#propdef-line-grid": {"displayText":"line-grid","export":true,"for_":[],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"line-grid","type":"property","url":"#propdef-line-grid"}, "#propdef-line-snap": {"displayText":"line-snap","export":true,"for_":[],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"line-snap","type":"property","url":"#propdef-line-snap"}, "#valdef-box-snap-block-end": {"displayText":"block-end","export":true,"for_":["box-snap"],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"block-end","type":"value","url":"#valdef-box-snap-block-end"}, "#valdef-box-snap-block-start": {"displayText":"block-start","export":true,"for_":["box-snap"],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"block-start","type":"value","url":"#valdef-box-snap-block-start"}, "#valdef-line-grid-create": {"displayText":"create","export":true,"for_":["line-grid"],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"create","type":"value","url":"#valdef-line-grid-create"}, "#valdef-line-grid-match-parent": {"displayText":"match-parent","export":true,"for_":["line-grid"],"level":"1","normative":true,"shortname":"css-line-grid","spec":"css-line-grid-1","status":"local","text":"match-parent","type":"value","url":"#valdef-line-grid-match-parent"}, "https://drafts.csswg.org/css-align-3/#typedef-content-position": {"displayText":"<content-position>","export":true,"for_":[],"level":"3","normative":true,"shortname":"css-align","spec":"css-align-3","status":"current","text":"<content-position>","type":"type","url":"https://drafts.csswg.org/css-align-3/#typedef-content-position"}, "https://drafts.csswg.org/css-display-4/#block-container": {"displayText":"block container","export":true,"for_":[],"level":"4","normative":true,"shortname":"css-display","spec":"css-display-4","status":"current","text":"block container","type":"dfn","url":"https://drafts.csswg.org/css-display-4/#block-container"}, "https://drafts.csswg.org/css-rhythm-1/#propdef-line-height-step": {"displayText":"line-height-step","export":true,"for_":[],"level":"1","normative":true,"shortname":"css-rhythm","spec":"css-rhythm-1","status":"current","text":"line-height-step","type":"property","url":"https://drafts.csswg.org/css-rhythm-1/#propdef-line-height-step"}, "https://drafts.csswg.org/css-shapes-1/#typedef-shape-box": {"displayText":"<shape-box>","export":true,"for_":[],"level":"1","normative":true,"shortname":"css-shapes","spec":"css-shapes-1","status":"current","text":"<shape-box>","type":"type","url":"https://drafts.csswg.org/css-shapes-1/#typedef-shape-box"}, "https://drafts.csswg.org/css-values-4/#comb-one": {"displayText":"|","export":true,"for_":[],"level":"4","normative":true,"shortname":"css-values","spec":"css-values-4","status":"current","text":"|","type":"grammar","url":"https://drafts.csswg.org/css-values-4/#comb-one"}, "https://drafts.csswg.org/css-values-4/#css-wide-keywords": {"displayText":"CSS-wide keywords","export":true,"for_":[],"level":"4","normative":true,"shortname":"css-values","spec":"css-values-4","status":"current","text":"css-wide keywords","type":"dfn","url":"https://drafts.csswg.org/css-values-4/#css-wide-keywords"}, "https://drafts.csswg.org/css-values-4/#identifier-value": {"displayText":"<custom-ident>","export":true,"for_":[],"level":"4","normative":true,"shortname":"css-values","spec":"css-values-4","status":"current","text":"<custom-ident>","type":"type","url":"https://drafts.csswg.org/css-values-4/#identifier-value"}, "https://drafts.csswg.org/css-writing-modes-4/#propdef-text-orientation": {"displayText":"text-orientation","export":true,"for_":[],"level":"4","normative":true,"shortname":"css-writing-modes","spec":"css-writing-modes-4","status":"current","text":"text-orientation","type":"property","url":"https://drafts.csswg.org/css-writing-modes-4/#propdef-text-orientation"}, "https://drafts.csswg.org/css-writing-modes-4/#writing-mode": {"displayText":"writing mode","export":true,"for_":[],"level":"4","normative":true,"shortname":"css-writing-modes","spec":"css-writing-modes-4","status":"current","text":"writing mode","type":"dfn","url":"https://drafts.csswg.org/css-writing-modes-4/#writing-mode"}, "https://drafts.csswg.org/mediaqueries-5/#paged-media": {"displayText":"paged media","export":true,"for_":[],"level":"5","normative":true,"shortname":"mediaqueries","spec":"mediaqueries-5","status":"current","text":"paged media","type":"dfn","url":"https://drafts.csswg.org/mediaqueries-5/#paged-media"}, }; function mkRefHint(link, ref) { const linkText = link.textContent; let dfnTextElements = ''; if (ref.displayText.toLowerCase() != linkText.toLowerCase()) { // Give the original term if it's being displayed in a different way. // But allow casing differences, they're insignificant. dfnTextElements = mk.li({}, mk.b({}, "Term: "), mk.span({}, ref.displayText) ); } const forList = ref.for_; let forListElements; if(forList.length == 0) { forListElements = []; } else if(forList.length == 1) { forListElements = mk.li({}, mk.b({}, "For: "), mk.span({}, forList[0]), ); } else { forListElements = mk.li({}, mk.b({}, "For: "), mk.ul({}, ...forList.map(forItem => mk.li({}, mk.span({}, forItem) ), ), ), ); } const url = ref.url; const safeUrl = encodeURIComponent(url); const hintPanel = mk.aside({ class: "ref-hint", id: `ref-hint-for-${safeUrl}`, "data-for": url, "aria-labelled-by": `ref-hint-for-${safeUrl}`, }, mk.ul({}, dfnTextElements, mk.li({}, mk.b({}, "URL: "), mk.a({ href: url, class: "ref" }, url), ), mk.li({}, mk.b({}, "Type: "), mk.span({}, `${ref.type}`), ), mk.li({}, mk.b({}, "Spec: "), mk.span({}, `${ref.spec ? ref.spec : ''}`), ), forListElements ), ); hintPanel.forLink = link; setupRefHintEventListeners(link, hintPanel); return hintPanel; } function hideAllRefHints() { queryAll(".ref-hint").forEach(el=>hideRefHint(el)); } function hideRefHint(refHint) { const link = refHint.forLink; link.setAttribute("aria-expanded", "false"); if(refHint.teardownEventListeners) { refHint.teardownEventListeners(); } refHint.remove(); } function showRefHint(link) { if(link.classList.contains("dfn-link")) return; const url = link.getAttribute("href"); const refHintKey = link.getAttribute("data-refhint-key"); let key = url; if(refHintKey) { key = refHintKey + "_" + url; } const ref = refsData[key]; if(!ref) return; hideAllRefHints(); // Only display one at this time. const refHint = mkRefHint(link, ref); append(document.body, refHint); link.setAttribute("aria-expanded", "true"); positionRefHint(refHint); } function setupRefHintEventListeners(link, refHint) { if (refHint.teardownEventListeners) return; // Add event handlers to hide the refHint after the user moves away // from both the link and refHint, if not hovering either within one second. let timeout = null; const startHidingRefHint = (event) => { if (timeout) { clearTimeout(timeout); } timeout = setTimeout(() => { hideRefHint(refHint); }, 1000); } const resetHidingRefHint = (event) => { if (timeout) clearTimeout(timeout); timeout = null; }; link.addEventListener("mouseleave", startHidingRefHint); link.addEventListener("mouseenter", resetHidingRefHint); link.addEventListener("blur", startHidingRefHint); link.addEventListener("focus", resetHidingRefHint); refHint.addEventListener("mouseleave", startHidingRefHint); refHint.addEventListener("mouseenter", resetHidingRefHint); refHint.addEventListener("blur", startHidingRefHint); refHint.addEventListener("focus", resetHidingRefHint); refHint.teardownEventListeners = () => { // remove event listeners resetHidingRefHint(); link.removeEventListener("mouseleave", startHidingRefHint); link.removeEventListener("mouseenter", resetHidingRefHint); link.removeEventListener("blur", startHidingRefHint); link.removeEventListener("focus", resetHidingRefHint); refHint.removeEventListener("mouseleave", startHidingRefHint); refHint.removeEventListener("mouseenter", resetHidingRefHint); refHint.removeEventListener("blur", startHidingRefHint); refHint.removeEventListener("focus", resetHidingRefHint); }; } function positionRefHint(refHint) { const link = refHint.forLink; const linkPos = getBounds(link); refHint.style.top = linkPos.bottom + "px"; refHint.style.left = linkPos.left + "px"; const panelPos = refHint.getBoundingClientRect(); const panelMargin = 8; const maxRight = document.body.parentNode.clientWidth - panelMargin; if (panelPos.right > maxRight) { const overflowAmount = panelPos.right - maxRight; const newLeft = Math.max(panelMargin, linkPos.left - overflowAmount); refHint.style.left = newLeft + "px"; } } // TODO: shared util // Returns the root-level absolute position {left and top} of element. function getBounds(el, relativeTo=document.body) { const relativeRect = relativeTo.getBoundingClientRect(); const elRect = el.getBoundingClientRect(); const top = elRect.top - relativeRect.top; const left = elRect.left - relativeRect.left; return { top, left, bottom: top + elRect.height, right: left + elRect.width, } } function showRefHintListener(e) { // If the target isn't in a link (or is a link), // just ignore it. let link = e.target.closest("a"); if(!link) return; // If the target is in a ref-hint panel // (aka a link in the already-open one), // also just ignore it. if(link.closest(".ref-hint")) return; // Otherwise, show the panel for the link. showRefHint(link); } function hideAllHintsListener(e) { // If the click is inside a ref-hint panel, ignore it. if(e.target.closest(".ref-hint")) return; // Otherwise, close all the current panels. hideAllRefHints(); } document.addEventListener("DOMContentLoaded", () => { document.body.addEventListener("mousedown", showRefHintListener); document.body.addEventListener("focus", showRefHintListener); document.body.addEventListener("click", hideAllHintsListener); }); window.addEventListener("resize", () => { // Hide any open ref hint. hideAllRefHints(); }); } </script>