mirror of https://git.lenooby09.tech/LeNooby09/social-app.git
lenooby09.tech
1# Layout
2
3This directory contains our core layout components. Use these when creating new
4screens, or when supplementing other components with functionality like
5centering.
6
7## Usage
8
9If we aren't talking about the `shell` components, layouts on individual screens
10look like more or less like this:
11
12```tsx
13<Outer>
14 <Header>...</Header>
15 <Content>...</Content>
16</Outer>
17```
18
19I'll map these words to real components.
20
21### `Layout.Screen`
22
23Provides the "Outer" functionality for a screen, like taking up the full height
24of the screen. **All screens should be wrapped with this component,** probably
25as the outermost component.
26
27> [!NOTE]
28> On web, `Layout.Screen` also provides the side borders on our central content
29> column. These borders are fixed position, 1px outside our center column width
30> of 600px.
31>
32> What this effectively means is that _nothing inside the center content column
33> needs (or should) define left/right borders._ That is now handled in one
34> place: within `Layout.Screen`.
35
36### `Layout.Header.*`
37
38The `Layout.Header` component actually contains multiple sub-components. Use
39this to compose different versions of the header. The most basic version looks
40like this:
41
42```tsx
43<Layout.Header.Outer>
44 <Layout.Header.BackButton /> {/* or <Layout.Header.MenuButton /> */}
45
46 <Layout.Header.Content>
47 <Layout.Header.TitleText>Account</Layout.Header.TitleText>
48
49 {/* Optional subtitle */}
50 <Layout.Header.SubtitleText>Settings for @esb.lol</Layout.Header.SubtitleText>
51 </Layout.Header.Content>
52
53 <Layout.Header.Slot />
54</Layout.Header.Outer>
55```
56
57Note the additional `Slot` component. This is here to keep the header balanced
58and provide correct spacing on all platforms. The `Slot` is 34px wide, which
59matches the `BackButton` and `MenuButton`.
60
61> If anyone has better ideas, I'm all ears, but this was simple and the small
62> amount of boilerplate is only incurred when creating a new screen, which is
63> infrequent.
64
65It can also function as a "slot" for a button positioned on the right side. See
66the `Hashtag` screen for an example, abbreviated below:
67
68```tsx
69<Layout.Header.Slot>
70 <Button size='small' shape='round'>...</Button>
71</Layout.Header.Slot>
72```
73
74If you need additional customization, simply use the components that are helpful
75and create new ones as needed. A good example is the `SavedFeeds` screen, which
76looks roughly like this:
77
78```tsx
79<Layout.Header.Outer>
80 <Layout.Header.BackButton />
81
82 {/* Override to align content to the left, making room for the button */}
83 <Layout.Header.Content align='left'>
84 <Layout.Header.TitleText>Edit My Feeds</Layout.Header.TitleText>
85 </Layout.Header.Content>
86
87 {/* Custom button, wider than 34px */}
88 <Button size='small'>...</Button>
89</Layout.Header.Outer>
90```
91
92> [!TIP]
93> The `Header` should be _outside_ the `Content` component in order to be
94> fixed on scroll on native. Placing it inside will make it scroll with the rest
95> of the page.
96
97### `Layout.Content`
98
99This provides the "Content" functionality for a screen. This component is
100actually an `Animated.ScrollView`, and accepts props for that component. It
101provides a little default styling as well. On web, it also _centers the content
102inside our center content column of 600px_.
103
104> [!NOTE]
105> What about flatlists or pagers? Those components are not colocated here (yet).
106> But those components serve the same purpose of "Content".
107
108## Examples
109
110The most basic layout available to us looks like this:
111
112```tsx
113<Layout.Screen>
114 <Layout.Header.Outer>
115 <Layout.Header.BackButton /> {/* or <Layout.Header.MenuButton /> */}
116
117 <Layout.Header.Content>
118 <Layout.Header.TitleText>Account</Layout.Header.TitleText>
119
120 {/* Optional subtitle */}
121 <Layout.Header.SubtitleText>Settings for @esb.lol</Layout.Header.SubtitleText>
122 </Layout.Header.Content>
123
124 <Layout.Header.Slot />
125 </Layout.Header.Outer>
126
127 <Layout.Content>
128 ...
129 </Layout.Content>
130</Layout.Screen>
131```
132
133**For `List` views,** you'd sub in `List` for `Layout.Content` and it will
134function the same. See `Feeds` screen for an example.
135
136**For `Pager` views,** including `PagerWithHeader`, do the same. See `Hashtag`
137screen for an example.
138
139## Utilities
140
141### `Layout.Center`
142
143This component behaves like our old `CenteredView` component.
144
145### `Layout.SCROLLBAR_OFFSET` and `Layout.SCROLLBAR_OFFSET_POSITIVE`
146
147Provide a pre-configured CSS vars for use when aligning fixed position elements.
148More on this below.
149
150## Scrollbar gutter handling
151
152Operating systems allow users to configure if their browser _always_ shows
153scrollbars not. Some OSs also don't allow configuration.
154
155The presence of scrollbars affects layout, particularly fixed position elements.
156Browsers support `scrollbar-gutter`, but each behaves differently. Our approach
157is to use the default `scrollbar-gutter: auto`. Basically, we start from a clean
158slate.
159
160This handling becomes particularly thorny when we need to lock scroll, like when
161opening a dialog or dropdown. Radix uses the library `react-remove-scroll`
162internally, which in turn depends on
163[`react-remove-scroll-bar`](https://github.com/theKashey/react-remove-scroll-bar).
164We've opted to rely on this transient dependency. This library adds some utility
165classes and CSS vars to the page when scroll is locked.
166
167**It is this CSS variable that we use in `SCROLLBAR_OFFSET` values.** This
168ensures that elements do not shift relative to the screen when opening a
169dropdown or dialog.
170
171These styles are applied where needed and we should have very little need of
172adjusting them often.