Skip to content

Commit ebf1aaa

Browse files
szuperazszuperaz
authored
docs: simplify CSS docs (#309)
### 🎯 Goal With the new documentation design, we want to have nice and crisp docs. The docs of CSS variables have complex tables that are hard to understand, and harder to style. To help the docs effort, we're creating a simplified version of the docs. If customers don't like the simplified version, we can restore it.
1 parent 4ec7b2e commit ebf1aaa

7 files changed

Lines changed: 67 additions & 303 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -110,6 +110,7 @@ dist
110110
# Generated docs
111111
docs/**/*.mdx
112112
!docs/theming/introduction.mdx
113+
!docs/theming/palette-variables.mdx
113114

114115
# Mac
115116
.DS_Store

‎doc-templates/component-variables.template.mdx‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,13 @@ CSS variables are the easiest way to customize the theme. The variables are orga
2323
- Global
2424
- Component
2525

26-
This page contains information about the component variables.
26+
Global variables change the layout/look-and-feel of the whole chat UI, meanwhile component variables change only a part of it (for example message component).
27+
28+
Component variables can be further grouped in the following ways:
29+
30+
- **Theme variables** for changing text and background colors, borders and shadows
31+
- **Layout variables** defined for some components (but not all) to change the size of a specific part of a component
32+
33+
You can find the list of components below:
2734

2835
[//]: # '#SLOT-autogenerated-component-variables'

‎doc-templates/global-variables.template.mdx‎

Lines changed: 3 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -23,21 +23,11 @@ CSS variables are the easiest way to customize the theme. The variables are orga
2323
- Global
2424
- Component
2525

26-
This page contains information about the global variables.
26+
Global variables change the layout/look-and-feel of the whole chat UI, meanwhile component variables change only a part of it (for example message component).
2727

2828
Global variables can be grouped into the following categories:
2929

30-
- Theme: colors, typography and border radiuses
31-
- Layout: spacing (padding and margin) and sizing
32-
33-
You can read about each category in detail in the tables below.
34-
35-
## Theme variables
36-
37-
[//]: # '#SLOT-autogenerated-theme-variables'
38-
39-
## Layout variables
40-
41-
[//]: # '#SLOT-autogenerated-layout-variables'
30+
- **Theme**: colors, typography and border radiuses [//]: # '#SLOT-autogenerated-theme-variables'
31+
- **Layout**: spacing (padding and margin) and sizing [//]: # '#SLOT-autogenerated-layout-variables'
4232

4333
If you find that these variables are too high-level and you need more granular control, you also have the option to provide [component layer overrides](./component-variables.mdx).

doc-templates/palette-variables.template.mdx renamed to docs/theming/palette-variables.mdx

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,4 @@ import V2Warning from './V2Warning';
2020

2121
A color palette is defined inside the library that used to define default values for the [global theme variables](./global-variables.mdx). If you want to work with the default theme but want to adjust the shades (for example, change `blue500` to a lighter color), you can update the palette variables. However, if you want to change the color scheme of the theme (for example, change the primary color from blue to green), you should take a look at [global theme variables](./global-variables.mdx).
2222

23-
[//]: # '#SLOT-autogenerated-palette-variables'
24-
25-
Palette variables are defined in: [https://github.com/GetStream/stream-chat-css/blob/main/src-v2/styles/\_palette-variables.scss](https://github.com/GetStream/stream-chat-css/blob/main/src-v2/styles/_palette-variables.scss)
23+
You can find the [list of palette variables on GitHub](https://github.com/GetStream/stream-chat-css/blob/main/src-v2/styles/_palette-variables.scss).

‎scripts/generate-docs.ts‎

Lines changed: 6 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,12 @@
11
import * as fs from 'fs';
2-
import { extractVariables } from './parser';
3-
import { getComponentVariablesOutput, getPaletteVariablesOutput, getGlobalVariablesOutput } from './output';
2+
import { getComponentVariablesOutput, getGlobalVariablesOutput } from './output';
3+
import { extractComponents } from './parser';
44

5-
const globalThemeVariables = extractVariables('./src/v2/styles/_global-theme-variables.scss');
6-
const globalLayoutVariables = extractVariables('./src/v2/styles/_global-layout-variables.scss');
7-
const componentVariables = extractVariables('./src/v2/**/*-@(theme|layout).scss', globalThemeVariables);
8-
const paletteVariables = extractVariables('./src/v2/styles/_palette-variables.scss');
5+
const componentInfos = extractComponents('./src/v2/**/*-@(theme|layout).scss');
96

10-
const globalThemeVariablesOutput = getGlobalVariablesOutput(globalThemeVariables, 'theme');
11-
const globalLayoutVariablesOutput = getGlobalVariablesOutput(globalLayoutVariables, 'layout');
12-
const componentVariablesOutput = getComponentVariablesOutput(componentVariables);
13-
const paletteVariablesOutput = getPaletteVariablesOutput(paletteVariables);
7+
const globalThemeVariablesOutput = getGlobalVariablesOutput('theme');
8+
const globalLayoutVariablesOutput = getGlobalVariablesOutput('layout');
9+
const componentVariablesOutput = getComponentVariablesOutput(componentInfos);
1410

1511
const updateAutogeneratedSlot = (
1612
templateFilePath: string,
@@ -23,13 +19,6 @@ const updateAutogeneratedSlot = (
2319
fs.writeFileSync(targetFilePath, targetContent, 'utf8');
2420
};
2521

26-
updateAutogeneratedSlot(
27-
`./doc-templates/palette-variables.template.mdx`,
28-
`[//]: # '#SLOT-autogenerated-palette-variables'`,
29-
paletteVariablesOutput,
30-
`./docs/theming/palette-variables.mdx`,
31-
);
32-
3322
updateAutogeneratedSlot(
3423
`./doc-templates/global-variables.template.mdx`,
3524
`[//]: # '#SLOT-autogenerated-theme-variables'`,
@@ -44,7 +33,6 @@ updateAutogeneratedSlot(
4433
`./docs/theming/global-variables.mdx`,
4534
);
4635

47-
4836
updateAutogeneratedSlot(
4937
`./doc-templates/component-variables.template.mdx`,
5038
`[//]: # '#SLOT-autogenerated-component-variables'`,

‎scripts/output.ts‎

Lines changed: 21 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -1,201 +1,46 @@
11
import dedent from 'dedent';
22
import prettier from 'prettier';
3-
import type { VariableGroup, VariableInfo } from './parser';
3+
import type { ComponentInfo } from './parser';
44
import * as packagejson from '../package.json';
55

6-
type Column = {
7-
name: string;
8-
key: keyof VariableInfo | 'usedIn';
9-
type: 'code' | 'text' | 'values';
10-
};
11-
type Group = { name: string; regexp: RegExp; columns: Column[]; definedIn?: Function };
12-
13-
const row = (v: VariableInfo, group: Group) => {
14-
const usedIn = [...v.referencedIn].map(componentThemeLink).join(', ');
15-
const info = { ...v, usedIn };
16-
return dedent`${group.columns.map((c) => `| ${getColumn(c, info)}`).join('')}|`;
17-
};
18-
19-
const getColumn = (column: Column, info: VariableInfo & { usedIn?: string }) => {
20-
if (column.type === 'values') {
21-
return getValuesColumn(info);
22-
} else {
23-
return getTextOrCodeColumn(column, info);
24-
}
25-
};
26-
27-
const getValuesColumn = (info: VariableInfo & { usedIn?: string }) => {
28-
return `<table>${info.values
29-
.map((v) => `<tr><th>\`${v.scope}\`</th></tr><tr><td>\`${v.value}\`</td></tr>`)
30-
.join('')}</table>`;
31-
};
32-
33-
const getTextOrCodeColumn = (column: Column, info: VariableInfo & { usedIn?: string }) => {
34-
return `${column.type === 'code' ? '`' : ''}${info[column.key] || ''}${
35-
column.type === 'code' ? '`' : ''
36-
}`;
37-
};
38-
39-
export const getGlobalVariablesOutput = (
40-
data: Map<string, VariableInfo>,
41-
type: 'theme' | 'layout',
42-
) => {
43-
const nameColumn: Column = { name: 'Name', key: 'name', type: 'code' };
44-
const valueColumn: Column = { name: 'Value(s)', key: 'values', type: 'values' };
45-
const descriptionColumn: Column = { name: 'Description', key: 'description', type: 'text' };
46-
const usedInColumn: Column = { name: 'Used in', key: 'usedIn', type: 'text' };
47-
48-
const groups = [
49-
{
50-
name: 'Colors',
51-
regexp: /color/,
52-
columns: [nameColumn, valueColumn, descriptionColumn, usedInColumn],
53-
},
54-
{
55-
name: 'Typography',
56-
regexp: /(__font|-text)/,
57-
columns: [nameColumn, valueColumn, descriptionColumn, usedInColumn],
58-
},
59-
{ name: 'Spacing', regexp: /spacing/, columns: [nameColumn, valueColumn, descriptionColumn] },
60-
{
61-
name: 'Radius',
62-
regexp: /__border-radius/,
63-
columns: [nameColumn, valueColumn, descriptionColumn, usedInColumn],
64-
},
65-
{ name: 'Others', regexp: /.*/, columns: [nameColumn, valueColumn, descriptionColumn] },
66-
];
67-
68-
const variablesByGroups: Map<Group, string[]> = new Map();
69-
70-
data.forEach((variable) => {
71-
for (const group of groups) {
72-
if (group.regexp.test(variable.name)) {
73-
if (!variablesByGroups.get(group)) {
74-
variablesByGroups.set(group, []);
75-
}
76-
variablesByGroups.get(group)!.push(row(variable, group));
77-
break;
78-
}
79-
}
80-
});
81-
82-
let output = '';
83-
groups.forEach((group) => {
84-
if (variablesByGroups.get(group)) {
85-
const header =
86-
group.columns.map((c) => `| ${c.name}`).join('') +
87-
`| \n` +
88-
group.columns.map(() => '|-').join('') +
89-
`|`;
90-
output += dedent`
91-
### ${group.name}
92-
${header}
93-
${variablesByGroups.get(group)!.join('\n')}\n\n`;
94-
}
95-
});
96-
97-
output += `All global ${type} variables are defined in: [https://github.com/GetStream/stream-chat-css/tree/v${packagejson.version}/src/v2/styles/_global-${type}-variables.scss](https://github.com/GetStream/stream-chat-css/tree/v${packagejson.version}/src/v2/styles/_global-${type}-variables.scss)\n\n`;
6+
export const getGlobalVariablesOutput = (type: 'theme' | 'layout') => {
7+
const output = `([list of global ${type} variables](https://github.com/GetStream/stream-chat-css/tree/v${packagejson.version}/src/v2/styles/_global-${type}-variables.scss))`;
988

999
return format(output);
10010
};
10111

102-
export const getComponentVariablesOutput = (data: Map<string, VariableInfo>) => {
103-
const nameColumn: Column = { name: 'Name', key: 'name', type: 'code' };
104-
const valueColumn: Column = { name: 'Value(s)', key: 'values', type: 'values' };
105-
const descriptionColumn: Column = { name: 'Description', key: 'description', type: 'text' };
106-
107-
const subgroupDefinitions = [
108-
{
109-
name: 'Theme variables',
110-
regexp: /color|border|box-shadow|overlay|background/,
111-
columns: [nameColumn, valueColumn, descriptionColumn],
112-
definedIn: componentThemeLink,
113-
},
114-
{
115-
name: 'Layout variables',
116-
regexp: /.*/,
117-
columns: [nameColumn, valueColumn, descriptionColumn],
118-
definedIn: componentLayoutLink,
119-
},
120-
];
121-
122-
const componentsGroups: Map<VariableGroup, Map<Group, string[]>> = new Map();
123-
data.forEach((v) => {
124-
const variableGroup = v.definedIn;
125-
if (variableGroup) {
126-
let existingVariableGroup = Array.from(componentsGroups.keys()).find(
127-
(g) => g.componentName === variableGroup.componentName,
128-
);
129-
if (!existingVariableGroup) {
130-
componentsGroups.set(variableGroup, new Map());
131-
existingVariableGroup = variableGroup;
132-
}
133-
const componentGroup = componentsGroups.get(existingVariableGroup)!;
134-
const subgroup = subgroupDefinitions.find((subgroup) => subgroup.regexp.test(v.name));
135-
if (subgroup) {
136-
if (!componentGroup.get(subgroup)) {
137-
componentGroup.set(subgroup, []);
138-
}
139-
componentGroup.get(subgroup)?.push(row(v, subgroup));
140-
}
141-
}
142-
});
143-
144-
let output = '';
145-
Array.from(componentsGroups.entries())
146-
.sort((e1, e2) => e1[0].componentName.localeCompare(e2[0].componentName))
147-
.forEach(([variableGroup, variablesBySubgroups]) => {
148-
output += dedent`
149-
## ${variableGroup.componentName}${
150-
variableGroup.sdkRestriction
151-
? ` - Only available in ${variableGroup.sdkRestriction} SDK`
152-
: ''
153-
}\n`;
154-
155-
subgroupDefinitions.forEach((group) => {
156-
if (variablesBySubgroups.get(group)) {
157-
const header =
158-
group.columns.map((c) => `| ${c.name}`).join('') +
159-
`| \n` +
160-
group.columns.map(() => '|-').join('') +
161-
`|`;
162-
output += dedent`
163-
### ${group.name}
164-
${header}
165-
${variablesBySubgroups.get(group)!.join('\n')}\n
166-
Defined in: ${group.definedIn(variableGroup.componentName)}\n\n`;
167-
}
168-
});
12+
export const getComponentVariablesOutput = (componentInfos: ComponentInfo[]) => {
13+
const header = `Component name | Variables | \n |-|-| \n`;
14+
let output = header;
15+
componentInfos
16+
.sort((e1, e2) => e1.name.localeCompare(e2.name))
17+
.forEach((componentInfo) => {
18+
output += dedent`\`${componentInfo.name}\`${
19+
componentInfo.sdkRestriction ? ` (${componentInfo.sdkRestriction} SDK only)` : ''
20+
} | ${componentInfo.variableTypes
21+
.map((t) =>
22+
t === 'theme'
23+
? componentThemeLink(componentInfo.name)
24+
: componentLayoutLink(componentInfo.name),
25+
)
26+
.join(', ')}|`;
27+
output += `\n`;
16928
});
17029

17130
return format(output);
17231
};
17332

174-
export const getPaletteVariablesOutput = (data: Map<string, VariableInfo>) => {
175-
const row = (variableInfo: VariableInfo) => {
176-
return `| \`${variableInfo.name}\` | ${getValuesColumn(variableInfo)} |`;
177-
};
178-
const rows = Array.from(data.values()).map(row);
179-
180-
let output = dedent`
181-
| Name | Value(s) |
182-
|------|-------|
183-
${rows.join('\n')}`;
184-
185-
return format(output);
186-
};
187-
18833
const componentThemeLink = (componentName: string) => {
18934
const pathInRepo = `https://github.com/GetStream/stream-chat-css/tree/v${packagejson.version}/src/v2/styles/`;
190-
return `[${componentName}](${pathInRepo}#COMP#/#COMP#-theme.scss)`.replaceAll(
35+
return `[theme variables](${pathInRepo}#COMP#/#COMP#-theme.scss)`.replaceAll(
19136
'#COMP#',
19237
componentName,
19338
);
19439
};
19540

19641
const componentLayoutLink = (componentName: string) => {
19742
const pathInRepo = `https://github.com/GetStream/stream-chat-css/tree/v${packagejson.version}/src/v2/styles/`;
198-
return `[${componentName}](${pathInRepo}#COMP#/#COMP#-layout.scss)`.replaceAll(
43+
return `[layout variables](${pathInRepo}#COMP#/#COMP#-layout.scss)`.replaceAll(
19944
'#COMP#',
20045
componentName,
20146
);

0 commit comments

Comments
 (0)