Skip to content

Commit 598a7bd

Browse files
eldomaganeldomagan
committed
feat: add Typography and TypographyPresets setting types
1 parent 8055f3b commit 598a7bd

30 files changed

+2018
-46
lines changed

‎docs/core-concepts/settings/types.md‎

Lines changed: 324 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -338,10 +338,10 @@ The visual editor provides an intuitive interface with four individual number in
338338

339339
In addition to the standard attributes, Spacing type settings have the following attributes:
340340

341-
| Attribute | Description | Required |
342-
| :-------- | :----------------------------- | :------- |
343-
| `min` | Minimum value for each side | No |
344-
| `max` | Maximum value for each side | No |
341+
| Attribute | Description | Required |
342+
| :-------- | :-------------------------- | :------- |
343+
| `min` | Minimum value for each side | No |
344+
| `max` | Maximum value for each side | No |
345345

346346
```php
347347
use BagistoPlus\Visual\Settings\Spacing;
@@ -375,10 +375,11 @@ In Blade:
375375
<SettingPreview image="/setting-spacing.png" title="Spacing setting type preview"/>
376376

377377
::: info
378+
378379
- Default values: All sides default to `0` if not specified
379380
- The visual editor includes a link toggle to sync all sides
380381
- Negative values are supported for margins (set appropriate min value)
381-
:::
382+
:::
382383

383384
---
384385

@@ -925,6 +926,324 @@ Bagisto Visual provides a helper method to generate the full CSS output automati
925926

926927
---
927928

929+
### Typography
930+
931+
The `Typography` setting allows merchants to select a typography preset for text styling. Typography presets are defined once in the theme's settings using [TypographyPresets](#typographypresets), and sections or blocks can reference them using this setting.
932+
933+
```php
934+
use BagistoPlus\Visual\Settings\Typography;
935+
936+
public static function settings(): array
937+
{
938+
return [
939+
Typography::make('heading_typography', 'Heading Typography'),
940+
Typography::make('body_typography', 'Body Typography'),
941+
];
942+
}
943+
```
944+
945+
This creates a dropdown in the visual editor populated with all typography presets defined by the theme.
946+
947+
**In Blade:**
948+
949+
Apply the selected typography using the `attributes()` method:
950+
951+
```blade
952+
<h1 {{ $section->settings->heading_typography->attributes() }}>
953+
Welcome to our store
954+
</h1>
955+
```
956+
957+
This outputs:
958+
959+
```html
960+
<h1 data-typography="heading">Welcome to our store</h1>
961+
```
962+
963+
The `data-typography` attribute scopes typography CSS variables to this element.
964+
965+
<SettingPreview image="/setting-typography.png" title="Typography setting type preview"/>
966+
967+
---
968+
969+
### TypographyPresets
970+
971+
The `TypographyPresets` setting type allows theme developers to define a **set of named typography presets** that merchants can reuse across multiple sections. Each typography preset is a collection of font properties (fontFamily, fontSize, lineHeight, etc.) that can be selected using a [Typography](#typography) setting.
972+
973+
This is typically defined once in your theme's `config/settings.php` and is **editable by the merchant**.
974+
975+
- Acts as the **central registry of available typography presets**
976+
- Enables consistency in text styling across sections
977+
- Supports responsive typography for fontSize and lineHeight
978+
- Merchants can add, edit, or remove presets in the theme editor
979+
980+
#### Usage in `config/settings.php`
981+
982+
```php
983+
use BagistoPlus\Visual\Settings\TypographyPresets;
984+
985+
return [
986+
TypographyPresets::make('typography_presets', 'Typography Presets')
987+
->presets([
988+
'heading' => [
989+
'fontFamily' => 'Inter',
990+
'fontSize' => '2xl',
991+
'lineHeight' => 'tight',
992+
'fontStyle' => 'normal',
993+
'letterSpacing' => 'normal',
994+
'textTransform' => 'none',
995+
],
996+
'body' => [
997+
'fontFamily' => 'Inter',
998+
'fontSize' => 'base',
999+
'lineHeight' => 'normal',
1000+
'fontStyle' => 'normal',
1001+
'letterSpacing' => 'normal',
1002+
'textTransform' => 'none',
1003+
]
1004+
]),
1005+
];
1006+
```
1007+
1008+
<SettingPreview image="/setting-typography-presets.png" title="Typography presets setting type preview"/>
1009+
1010+
#### Generating CSS
1011+
1012+
After defining typography presets, you must generate the CSS in your theme's layout file. This makes the typography styles available to all sections using the `Typography` setting.
1013+
1014+
**Basic Usage:**
1015+
1016+
```blade
1017+
{{-- layouts/default.blade.php --}}
1018+
<style>
1019+
@foreach ($theme->settings->typography_presets as $typography)
1020+
{!! $typography->toCss() !!}
1021+
@endforeach
1022+
</style>
1023+
1024+
{{-- Load fonts from Bunny Fonts --}}
1025+
@pushOnce('styles')
1026+
@foreach ($theme->settings->typography_presets as $typography)
1027+
{!! $typography->toHtml() !!}
1028+
@endforeach
1029+
@endPushOnce
1030+
```
1031+
1032+
This generates CSS for typography styles:
1033+
1034+
```css
1035+
[data-typography='heading'] {
1036+
--typography-font-family: 'Inter', sans-serif;
1037+
--typography-font-style: normal;
1038+
--typography-font-size: 1.5rem;
1039+
--typography-line-height: 1.25;
1040+
--typography-letter-spacing: 0em;
1041+
--typography-text-transform: none;
1042+
}
1043+
1044+
[data-typography='body'] {
1045+
--typography-font-family: 'Inter', sans-serif;
1046+
--typography-font-style: normal;
1047+
--typography-font-size: 1rem;
1048+
--typography-line-height: 1.5;
1049+
--typography-letter-spacing: 0em;
1050+
--typography-text-transform: none;
1051+
}
1052+
```
1053+
1054+
And generates HTML to load fonts from Bunny Fonts:
1055+
1056+
```html
1057+
<link rel="preconnect" href="https://fonts.bunny.net" crossorigin />
1058+
<link href="https://fonts.bunny.net/css?family=inter:" rel="preload" as="style" />
1059+
<link href="https://fonts.bunny.net/css?family=inter:" rel="stylesheet" />
1060+
```
1061+
1062+
**With Custom Selectors:**
1063+
1064+
You can also apply typography directly to HTML elements by passing a custom selector:
1065+
1066+
```blade
1067+
<style>
1068+
{!! $theme->settings->typography_presets['heading']->toCss('h1, h2, h3') !!}
1069+
{!! $theme->settings->typography_presets['body']->toCss('p, li, td') !!}
1070+
</style>
1071+
```
1072+
1073+
This generates CSS that applies to both the `data-typography` attribute AND the custom selector:
1074+
1075+
```css
1076+
[data-typography='heading'],
1077+
h1,
1078+
h2,
1079+
h3 {
1080+
--typography-font-family: 'Inter', sans-serif;
1081+
--typography-font-style: normal;
1082+
--typography-font-size: 1.5rem;
1083+
--typography-line-height: 1.25;
1084+
--typography-letter-spacing: 0em;
1085+
--typography-text-transform: none;
1086+
}
1087+
1088+
[data-typography='body'],
1089+
p,
1090+
li,
1091+
td {
1092+
--typography-font-family: 'Inter', sans-serif;
1093+
--typography-font-style: normal;
1094+
--typography-font-size: 1rem;
1095+
--typography-line-height: 1.5;
1096+
--typography-letter-spacing: 0em;
1097+
--typography-text-transform: none;
1098+
}
1099+
```
1100+
1101+
**Applying CSS Variables:**
1102+
1103+
In your theme's CSS, apply the generated CSS variables to elements:
1104+
1105+
```css
1106+
[data-typography] {
1107+
font-family: var(--typography-font-family);
1108+
font-style: var(--typography-font-style);
1109+
font-size: var(--typography-font-size);
1110+
line-height: var(--typography-line-height);
1111+
letter-spacing: var(--typography-letter-spacing);
1112+
text-transform: var(--typography-text-transform);
1113+
}
1114+
```
1115+
1116+
#### Preset Format
1117+
1118+
Each preset is an array with the following properties:
1119+
1120+
| Property | Type | Description | Required | Values |
1121+
| --------------- | ------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
1122+
| `fontFamily` | string\|null | Font family name | No | Any font family name |
1123+
| `fontSize` | string\|array | Font size token or responsive config | Yes | `xs`, `sm`, `base`, `lg`, `xl`, `2xl`, `3xl`, `4xl`, `5xl`, `6xl`, `7xl`, `8xl`, `9xl` |
1124+
| `lineHeight` | string\|array | Line height token or responsive config | Yes | `none`, `tight`, `snug`, `normal`, `relaxed`, `loose` |
1125+
| `fontStyle` | string | Font style | Yes | `normal`, `italic` |
1126+
| `letterSpacing` | string | Letter spacing token | Yes | `tighter`, `tight`, `normal`, `wide`, `wider`, `widest` |
1127+
| `textTransform` | string | Text transform | Yes | `none`, `uppercase`, `lowercase`, `capitalize` |
1128+
1129+
**Font Size Tokens:**
1130+
1131+
| Token | CSS Value | Description |
1132+
| ------ | --------- | ------------------ |
1133+
| `xs` | 0.75rem | Extra small (12px) |
1134+
| `sm` | 0.875rem | Small (14px) |
1135+
| `base` | 1rem | Base size (16px) |
1136+
| `lg` | 1.125rem | Large (18px) |
1137+
| `xl` | 1.25rem | Extra large (20px) |
1138+
| `2xl` | 1.5rem | 2x large (24px) |
1139+
| `3xl` | 1.875rem | 3x large (30px) |
1140+
| `4xl` | 2.25rem | 4x large (36px) |
1141+
| `5xl` | 3rem | 5x large (48px) |
1142+
| `6xl` | 3.75rem | 6x large (60px) |
1143+
| `7xl` | 4.5rem | 7x large (72px) |
1144+
| `8xl` | 6rem | 8x large (96px) |
1145+
| `9xl` | 8rem | 9x large (128px) |
1146+
1147+
**Line Height Tokens:**
1148+
1149+
| Token | CSS Value |
1150+
| --------- | --------- |
1151+
| `none` | 1 |
1152+
| `tight` | 1.25 |
1153+
| `snug` | 1.375 |
1154+
| `normal` | 1.5 |
1155+
| `relaxed` | 1.625 |
1156+
| `loose` | 2 |
1157+
1158+
**Letter Spacing Tokens:**
1159+
1160+
| Token | CSS Value |
1161+
| --------- | --------- |
1162+
| `tighter` | -0.05em |
1163+
| `tight` | -0.025em |
1164+
| `normal` | 0em |
1165+
| `wide` | 0.025em |
1166+
| `wider` | 0.05em |
1167+
| `widest` | 0.1em |
1168+
1169+
#### Responsive Typography
1170+
1171+
Typography supports responsive configurations for `fontSize` and `lineHeight` using an array format with breakpoint keys:
1172+
1173+
```php
1174+
TypographyPresets::make('typography_presets', 'Typography Presets')
1175+
->presets([
1176+
'responsive-heading' => [
1177+
'fontFamily' => 'Inter',
1178+
'fontSize' => [
1179+
'_default' => '2xl', // Default size
1180+
'mobile' => 'xl', // max-width: 639px
1181+
'tablet' => '2xl', // 640px - 1023px
1182+
'desktop' => '3xl', // min-width: 1024px
1183+
],
1184+
'lineHeight' => [
1185+
'_default' => 'tight',
1186+
'mobile' => 'snug',
1187+
'desktop' => 'tight',
1188+
],
1189+
'fontStyle' => 'normal',
1190+
'letterSpacing' => 'normal',
1191+
'textTransform' => 'none',
1192+
],
1193+
]);
1194+
```
1195+
1196+
**Breakpoints:**
1197+
1198+
| Breakpoint | Media Query | Description |
1199+
| ---------- | ---------------------------------------- | --------------- |
1200+
| `_default` | (none) | Default value |
1201+
| `mobile` | `max-width: 639px` | Mobile devices |
1202+
| `tablet` | `min-width: 640px and max-width: 1023px` | Tablet devices |
1203+
| `desktop` | `min-width: 1024px` | Desktop devices |
1204+
1205+
Generated responsive CSS:
1206+
1207+
```css
1208+
[data-typography='responsive-heading'] {
1209+
--typography-font-size: 1.5rem;
1210+
--typography-line-height: 1.25;
1211+
}
1212+
1213+
@media (max-width: 639px) {
1214+
[data-typography='responsive-heading'] {
1215+
--typography-font-size: 1.25rem;
1216+
--typography-line-height: 1.375;
1217+
}
1218+
}
1219+
1220+
@media (min-width: 1024px) {
1221+
[data-typography='responsive-heading'] {
1222+
--typography-font-size: 1.875rem;
1223+
--typography-line-height: 1.25;
1224+
}
1225+
}
1226+
```
1227+
1228+
#### Behavior in the Theme Editor
1229+
1230+
- Merchants can **add, edit, or remove** typography presets
1231+
- Custom presets are assigned IDs like `typography-1`, `typography-2`, etc.
1232+
- Theme-defined presets cannot be deleted (only custom ones can be removed)
1233+
- Changes are immediately reflected in sections using the `Typography` setting
1234+
1235+
<SettingPreview image="/setting-edit-typography-preset.png" title="Edit typography preset setting type preview"/>
1236+
1237+
#### Notes
1238+
1239+
- Only one `TypographyPresets` setting should be defined per theme
1240+
- Sections reference presets via the `Typography` setting, not directly
1241+
- If no `TypographyPresets` is defined, `Typography` fields will not be functional
1242+
- Font families are automatically loaded from Bunny Fonts using the `toHtml()` method
1243+
- Bunny Fonts is the only supported font provider. See the [Font](#font) setting type for more details on font loading
1244+
1245+
---
1246+
9281247
### Header
9291248

9301249
Visual divider or label inside settings groups. Useful for organizing complex settings panels into meaningful sections.

‎docs/public/setting-edit-typography-preset.png‎

66.2 KB
Loading

‎docs/public/setting-typography-presets.png‎

32.1 KB
Loading

‎docs/public/setting-typography.png‎

9.08 KB
Loading

0 commit comments

Comments
 (0)