Debian Codegraph @

src/pydata_sphinx_theme/assets/styles/abstracts/_links.scss

raw
1 // Consistent styling for links
2 // ============================
3
4 @use "sass:string";
5
6 // Define some useful variables for links styling consistency
7
8 // The default thickness of the underline for links will be either:
9 // - 1px
10 // - 0.0625rem if it's thicker than 1px because the user has changed the text
11 // size in their browser
12 $link-underline-thickness: string.unquote("max(1px, .0625rem)") !default;
13
14 // Offset of link underlines from text baseline
15 // The default is 3px expressed as ems, as calculated against the default body
16 // font size (on desktop).
17 $link-underline-offset: 0.1578em !default;
18
19 // Thickness of link underlines in hover state
20 // The default for each link will be the thickest of the following:
21 // - 3px
22 // - 0.1875rem, if it's thicker than 3px because the user has changed the text
23 // size in their browser
24 // - 0.12em (relative to the link's text size)
25 $link-hover-decoration-thickness: string.unquote(
26 "max(3px, .1875rem, .12em)"
27 ) !default;
28
29 // Ensures links have an underline decoration by default - needed to meet
30 // WCAG SC 1.4.1
31 @mixin link-decoration {
32 text-decoration: underline;
33
34 @if $link-underline-thickness {
35 text-decoration-thickness: $link-underline-thickness;
36 }
37
38 @if $link-underline-offset {
39 text-underline-offset: $link-underline-offset;
40 }
41 }
42
43 // Ensures links have an underline decoration on hover - distinct from the
44 // default behaviour
45 @mixin link-decoration-hover {
46 @if $link-hover-decoration-thickness {
47 text-decoration-thickness: $link-hover-decoration-thickness;
48
49 // Disable ink skipping on underlines on hover.
50 text-decoration-skip-ink: none;
51 }
52 }
53
54 // Simple hover style - can be used alone or in conjunction with other mixins
55 // Add the text underline and change in thickness on hover.
56 // Intended for use with the `:hover` pseudo-class.
57 @mixin link-style-hover {
58 @include link-decoration;
59 @include link-decoration-hover;
60
61 color: var(--pst-color-link-hover);
62 }
63
64 // Default link styles
65 // -------------------
66 // Defines: default unvisited, visited, hover, and active.
67 // TODO: @trallard to improve focus styles in subsequent PR
68 @mixin link-style-default {
69 // So that really long links don't spill out of their container
70 overflow-wrap: break-word;
71 color: var(--pst-color-link);
72
73 @include link-decoration;
74
75 &:hover {
76 color: var(--pst-color-link-hover);
77
78 @include link-decoration-hover;
79 }
80
81 // TODO: @trallard to add active styles in subsequent PR
82 &:active {
83 color: var(--pst-color-link);
84 }
85
86 // Visited should still be hoverable
87 &:visited {
88 color: var(--pst-color-link);
89
90 &:hover {
91 color: var(--pst-color-link-hover);
92 }
93 }
94 }
95
96 // Text link styles
97 // ----------------
98 // Makes links use the muted text colour and removes the underline.
99 // Use this mixin for navigation bar links.
100 @mixin link-style-text {
101 color: var(--pst-color-text-muted);
102 text-decoration: none;
103
104 &:hover {
105 color: var(--pst-color-link-hover);
106
107 @include link-decoration;
108 @include link-decoration-hover;
109 }
110 }
111
112 // Sidebar and TOC links
113 // ---------------------
114 // Makes links use the muted text colour and removes the underline.
115 // Use this mixin for navigation the primary sidebar and table of contents.
116 // Active and hover should work together rather than one overriding the other.
117 @mixin link-sidebar {
118 color: var(--pst-color-text-muted);
119 text-decoration: none;
120
121 &:hover {
122 text-decoration: underline;
123 background-color: transparent;
124 color: var(--pst-color-link-hover);
125
126 @include link-decoration-hover;
127 }
128
129 // TODO: @trallard to update active styles in subsequent PR
130 &:active {
131 color: var(--pst-color-link-hover);
132 }
133
134 &:focus-visible {
135 box-shadow: $focus-ring-box-shadow;
136 outline: none;
137 z-index: 10; // keep focus ring on top (prevent the link-sidebar-current notch from lying on top of the ring)
138 }
139 }
140
141 // Sidebar current page link styles
142 // --------------------------------
143 // Adds a vertical line on the left hand side of the link to indicate that
144 // it's the current page. Note this is distinct from an active state.
145 // Used on the primary sidebar and the TOC.
146 // We want the side box shadow to have the same thickness as the hover underline
147 @mixin link-sidebar-current {
148 font-weight: 600;
149 color: var(--pst-color-primary);
150
151 @if $link-hover-decoration-thickness {
152 $notch-shadow: inset
153 $link-hover-decoration-thickness
154 0
155 0
156 var(--pst-color-primary);
157
158 box-shadow: $notch-shadow;
159
160 &:focus-visible {
161 box-shadow: $notch-shadow, $focus-ring-box-shadow;
162 outline: none;
163 }
164 }
165 }
166
167 // Header navbar text and icon links
168 // ---------------------------------
169 // (includes light/dark mode button)
170
171 // This mixin makes it possible to show hover/underline and focus/ring styles at
172 // the same time. The trick is to use:
173 // - a pseudo-element with bottom border for the hover underline
174 // - a CSS outline for the focus ring.
175
176 // Normally we use box-shadow for underline and outline for focus ring. But we
177 // cannot apply box-shadow and outline together on the same element because the
178 // border-radius value that we use to round the outline will also round the
179 // box-shadow used for the underline. We also cannot use text-underline because
180 // it does not work on non-text links, nor do we want to use it on text links
181 // that we want to treat as blocks, such as the header nav links because the
182 // underline will wrap across two lines if the link text also wraps across two
183 // lines.
184 @mixin link-style-block {
185 color: var(--pst-color-text-muted);
186
187 // Set position relative so that the child ::before pseudo-element's absolute
188 // position is relative to this element.
189 position: relative;
190
191 // Set up pseudo-element used for hover underline styles
192 &::before {
193 content: "";
194 display: block;
195 position: absolute;
196 inset: 0;
197 background-color: transparent;
198
199 @if $link-hover-decoration-thickness {
200 bottom: calc(-1 * $link-hover-decoration-thickness);
201 margin: $link-hover-decoration-thickness 0;
202 }
203 }
204
205 &:hover {
206 color: var(--pst-color-secondary);
207 text-decoration: none; // override the link-style-hover mixin
208 &::before {
209 @if $link-hover-decoration-thickness {
210 border-bottom: $link-hover-decoration-thickness
211 solid
212 var(--pst-color-secondary);
213 }
214 }
215 }
216
217 &:focus-visible {
218 box-shadow: none; // override Bootstrap
219 outline: 3px solid var(--pst-color-accent);
220 outline-offset: $focus-ring-width;
221 }
222 }