Skip to content

Commit fee470e

Browse files
author
stlc-bot
committed
refactor(fonts): share font link schemas and inferred types
Merge pull request #1838 from context-dot-dev/codex/font-faces-api Stainless-Generated-From: 4d6664b20d53e6f896d040ba1adb1d40adf0652e
1 parent 78b6717 commit fee470e

3 files changed

Lines changed: 214 additions & 31 deletions

File tree

‎src/Web/WebExtractStyleguideResponse/Styleguide.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ final class Styleguide implements BaseModel
5959
public ElementSpacing $elementSpacing;
6060

6161
/**
62-
* Font assets keyed by family name as it appears in fontFamily/fontFallbacks (non-generic names only). Clients match typography.fontFamily / fontWeight or button styles to pick a file URL from files.
62+
* Font assets keyed by family name as it appears in fontFamily/fontFallbacks (non-generic names only). Match font style and weight against faces to select a file URL.
6363
*
6464
* @var array<string,FontLink> $fontLinks
6565
*/
@@ -196,7 +196,7 @@ public function withElementSpacing(
196196
}
197197

198198
/**
199-
* Font assets keyed by family name as it appears in fontFamily/fontFallbacks (non-generic names only). Clients match typography.fontFamily / fontWeight or button styles to pick a file URL from files.
199+
* Font assets keyed by family name as it appears in fontFamily/fontFallbacks (non-generic names only). Match font style and weight against faces to select a file URL.
200200
*
201201
* @param array<string,FontLink|FontLinkShape> $fontLinks
202202
*/

‎src/Web/WebExtractStyleguideResponse/Styleguide/FontLink.php‎

Lines changed: 59 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -8,29 +8,25 @@
88
use ContextDev\Core\Attributes\Required;
99
use ContextDev\Core\Concerns\SdkModel;
1010
use ContextDev\Core\Contracts\BaseModel;
11+
use ContextDev\Web\WebExtractStyleguideResponse\Styleguide\FontLink\Face;
1112
use ContextDev\Web\WebExtractStyleguideResponse\Styleguide\FontLink\Type;
1213

1314
/**
15+
* @phpstan-import-type FaceShape from \ContextDev\Web\WebExtractStyleguideResponse\Styleguide\FontLink\Face
16+
*
1417
* @phpstan-type FontLinkShape = array{
15-
* files: array<string,string>,
1618
* type: Type|value-of<Type>,
1719
* category?: string|null,
1820
* displayName?: string|null,
21+
* faces?: list<Face|FaceShape>|null,
22+
* files?: array<string,string>|null,
1923
* }
2024
*/
2125
final class FontLink implements BaseModel
2226
{
2327
/** @use SdkModel<FontLinkShape> */
2428
use SdkModel;
2529

26-
/**
27-
* Upright font files keyed by weight string (e.g. "400" for regular, "500", "700"). Values are absolute URLs.
28-
*
29-
* @var array<string,string> $files
30-
*/
31-
#[Required(map: 'string')]
32-
public array $files;
33-
3430
/** @var value-of<Type> $type */
3531
#[Required(enum: Type::class)]
3632
public string $type;
@@ -42,23 +38,41 @@ final class FontLink implements BaseModel
4238
public ?string $category;
4339

4440
/**
45-
* Present when type is custom: human-readable name derived from the fontLinks key (strip build/hash suffixes, split camelCase / PascalCase, normalize separators). Google entries omit this.
41+
* Human-readable family name. For custom fonts, derived from the fontLinks key; for Google fonts, the canonical Google Fonts family name.
4642
*/
4743
#[Optional]
4844
public ?string $displayName;
4945

46+
/**
47+
* Discovered font faces, including style, weight, and distinct Unicode subsets.
48+
*
49+
* @var list<Face>|null $faces
50+
*/
51+
#[Optional(list: Face::class)]
52+
public ?array $faces;
53+
54+
/**
55+
* @deprecated
56+
*
57+
* Deprecated upright font lookup keyed by weight string. A variable font can map several standard weight keys to the same URL; faces retains its actual weight range.
58+
*
59+
* @var array<string,string>|null $files
60+
*/
61+
#[Optional(map: 'string')]
62+
public ?array $files;
63+
5064
/**
5165
* `new FontLink()` is missing required properties by the API.
5266
*
5367
* To enforce required parameters use
5468
* ```
55-
* FontLink::with(files: ..., type: ...)
69+
* FontLink::with(type: ...)
5670
* ```
5771
*
5872
* Otherwise ensure the following setters are called
5973
*
6074
* ```
61-
* (new FontLink)->withFiles(...)->withType(...)
75+
* (new FontLink)->withType(...)
6276
* ```
6377
*/
6478
public function __construct()
@@ -71,35 +85,25 @@ public function __construct()
7185
*
7286
* You must use named parameters to construct any parameters with a default value.
7387
*
74-
* @param array<string,string> $files
7588
* @param Type|value-of<Type> $type
89+
* @param list<Face|FaceShape>|null $faces
90+
* @param array<string,string>|null $files
7691
*/
7792
public static function with(
78-
array $files,
7993
Type|string $type,
8094
?string $category = null,
8195
?string $displayName = null,
96+
?array $faces = null,
97+
?array $files = null,
8298
): self {
8399
$self = new self;
84100

85-
$self['files'] = $files;
86101
$self['type'] = $type;
87102

88103
null !== $category && $self['category'] = $category;
89104
null !== $displayName && $self['displayName'] = $displayName;
90-
91-
return $self;
92-
}
93-
94-
/**
95-
* Upright font files keyed by weight string (e.g. "400" for regular, "500", "700"). Values are absolute URLs.
96-
*
97-
* @param array<string,string> $files
98-
*/
99-
public function withFiles(array $files): self
100-
{
101-
$self = clone $this;
102-
$self['files'] = $files;
105+
null !== $faces && $self['faces'] = $faces;
106+
null !== $files && $self['files'] = $files;
103107

104108
return $self;
105109
}
@@ -127,7 +131,7 @@ public function withCategory(string $category): self
127131
}
128132

129133
/**
130-
* Present when type is custom: human-readable name derived from the fontLinks key (strip build/hash suffixes, split camelCase / PascalCase, normalize separators). Google entries omit this.
134+
* Human-readable family name. For custom fonts, derived from the fontLinks key; for Google fonts, the canonical Google Fonts family name.
131135
*/
132136
public function withDisplayName(string $displayName): self
133137
{
@@ -136,4 +140,30 @@ public function withDisplayName(string $displayName): self
136140

137141
return $self;
138142
}
143+
144+
/**
145+
* Discovered font faces, including style, weight, and distinct Unicode subsets.
146+
*
147+
* @param list<Face|FaceShape> $faces
148+
*/
149+
public function withFaces(array $faces): self
150+
{
151+
$self = clone $this;
152+
$self['faces'] = $faces;
153+
154+
return $self;
155+
}
156+
157+
/**
158+
* Deprecated upright font lookup keyed by weight string. A variable font can map several standard weight keys to the same URL; faces retains its actual weight range.
159+
*
160+
* @param array<string,string> $files
161+
*/
162+
public function withFiles(array $files): self
163+
{
164+
$self = clone $this;
165+
$self['files'] = $files;
166+
167+
return $self;
168+
}
139169
}
Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
namespace ContextDev\Web\WebExtractStyleguideResponse\Styleguide\FontLink;
6+
7+
use ContextDev\Core\Attributes\Optional;
8+
use ContextDev\Core\Attributes\Required;
9+
use ContextDev\Core\Concerns\SdkModel;
10+
use ContextDev\Core\Contracts\BaseModel;
11+
12+
/**
13+
* @phpstan-type FaceShape = array{
14+
* style: string,
15+
* url: string,
16+
* weight: string,
17+
* unicodeRange?: string|null,
18+
* width?: string|null,
19+
* }
20+
*/
21+
final class Face implements BaseModel
22+
{
23+
/** @use SdkModel<FaceShape> */
24+
use SdkModel;
25+
26+
/**
27+
* CSS font-style descriptor: normal, italic, or oblique, including an optional oblique angle or angle range (e.g. oblique 10deg 20deg).
28+
*/
29+
#[Required]
30+
public string $style;
31+
32+
/**
33+
* Preferred font file URL or inline font data URL.
34+
*/
35+
#[Required]
36+
public string $url;
37+
38+
/**
39+
* CSS font-weight descriptor. A variable font file can have a range such as "300 500", covering intermediate weights without separate files.
40+
*/
41+
#[Required]
42+
public string $weight;
43+
44+
/**
45+
* CSS unicode-range descriptor.
46+
*/
47+
#[Optional]
48+
public ?string $unicodeRange;
49+
50+
/**
51+
* CSS font-width or font-stretch descriptor.
52+
*/
53+
#[Optional]
54+
public ?string $width;
55+
56+
/**
57+
* `new Face()` is missing required properties by the API.
58+
*
59+
* To enforce required parameters use
60+
* ```
61+
* Face::with(style: ..., url: ..., weight: ...)
62+
* ```
63+
*
64+
* Otherwise ensure the following setters are called
65+
*
66+
* ```
67+
* (new Face)->withStyle(...)->withURL(...)->withWeight(...)
68+
* ```
69+
*/
70+
public function __construct()
71+
{
72+
$this->initialize();
73+
}
74+
75+
/**
76+
* Construct an instance from the required parameters.
77+
*
78+
* You must use named parameters to construct any parameters with a default value.
79+
*/
80+
public static function with(
81+
string $style,
82+
string $url,
83+
string $weight,
84+
?string $unicodeRange = null,
85+
?string $width = null,
86+
): self {
87+
$self = new self;
88+
89+
$self['style'] = $style;
90+
$self['url'] = $url;
91+
$self['weight'] = $weight;
92+
93+
null !== $unicodeRange && $self['unicodeRange'] = $unicodeRange;
94+
null !== $width && $self['width'] = $width;
95+
96+
return $self;
97+
}
98+
99+
/**
100+
* CSS font-style descriptor: normal, italic, or oblique, including an optional oblique angle or angle range (e.g. oblique 10deg 20deg).
101+
*/
102+
public function withStyle(string $style): self
103+
{
104+
$self = clone $this;
105+
$self['style'] = $style;
106+
107+
return $self;
108+
}
109+
110+
/**
111+
* Preferred font file URL or inline font data URL.
112+
*/
113+
public function withURL(string $url): self
114+
{
115+
$self = clone $this;
116+
$self['url'] = $url;
117+
118+
return $self;
119+
}
120+
121+
/**
122+
* CSS font-weight descriptor. A variable font file can have a range such as "300 500", covering intermediate weights without separate files.
123+
*/
124+
public function withWeight(string $weight): self
125+
{
126+
$self = clone $this;
127+
$self['weight'] = $weight;
128+
129+
return $self;
130+
}
131+
132+
/**
133+
* CSS unicode-range descriptor.
134+
*/
135+
public function withUnicodeRange(string $unicodeRange): self
136+
{
137+
$self = clone $this;
138+
$self['unicodeRange'] = $unicodeRange;
139+
140+
return $self;
141+
}
142+
143+
/**
144+
* CSS font-width or font-stretch descriptor.
145+
*/
146+
public function withWidth(string $width): self
147+
{
148+
$self = clone $this;
149+
$self['width'] = $width;
150+
151+
return $self;
152+
}
153+
}

0 commit comments

Comments
 (0)