Skip to content

Commit eb75bac

Browse files
sam-b-rosesam-b-rose
authored
Merge pull request #3281 from Shopify/add-admin-modal-docs
Add Admin Modal docs and improve preview size
2 parents 710e31c + f5aceb0 commit eb75bac

File tree

8 files changed

+162
-33
lines changed

8 files changed

+162
-33
lines changed

‎.changeset/small-roses-double.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@shopify/ui-extensions': patch
3+
---
4+
5+
Add documentation for Admin Modal

‎packages/ui-extensions/docs/surfaces/admin/build-docs.mjs‎

Lines changed: 80 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -48,41 +48,90 @@ const decodeHTML = (str) => {
4848
.replace(/'/g, "'");
4949
};
5050

51-
const htmlWrapper = (htmlString, layout) => {
52-
return `<!DOCTYPE html><html><head><style>html, body {height:100%} body {box-sizing: border-box; margin: 0; padding:0.5rem; ${layout}}</style><script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script></head><body>${decodeHTML(
51+
const composeStyles = (...styles) => {
52+
return styles
53+
.filter(Boolean)
54+
.map((style) => style.trim())
55+
.filter((style) => style.length > 0)
56+
.join(' ');
57+
};
58+
59+
// Don't allow all CSS properties to be used in the customStyles property
60+
// DO NOT ADD MORE PROPERTIES TO THIS LIST
61+
const allowedProperties = ['minHeight', 'minBlockSize'];
62+
63+
const stylesToString = (styles) => {
64+
if (!styles) return '';
65+
return Object.entries(styles)
66+
.filter(
67+
([property, value]) =>
68+
allowedProperties.includes(property) &&
69+
value !== undefined &&
70+
value !== null,
71+
)
72+
.map(([property, value]) => {
73+
const kebabProperty = property.replace(
74+
/[A-Z]/g,
75+
(match) => `-${match.toLowerCase()}`,
76+
);
77+
return `${kebabProperty}: ${value}`;
78+
})
79+
.join('; ');
80+
};
81+
82+
const htmlWrapper = (htmlString, layoutStyles = '', customStyles = '') => {
83+
const baseStyles = 'box-sizing: border-box; margin: 0; padding: 0.5rem;';
84+
const composedStyles = composeStyles(baseStyles, layoutStyles, customStyles);
85+
86+
return `<!DOCTYPE html><html><head><style>html, body {height:100%} body {${composedStyles}}</style><script src="https://cdn.shopify.com/shopifycloud/polaris.js"></script></head><body>${decodeHTML(
5387
htmlString,
5488
)}</body></html>`;
5589
};
5690

91+
const createTemplate = ({
92+
layoutStyles,
93+
wrapperElement = null,
94+
wrapperAttributes = '',
95+
}) => {
96+
return (htmlString, customStyles) => {
97+
const wrappedHtml = wrapperElement
98+
? `<${wrapperElement}${
99+
wrapperAttributes ? ` ${wrapperAttributes}` : ''
100+
}>${htmlString}</${wrapperElement}>`
101+
: htmlString;
102+
const customStylesString = stylesToString(customStyles);
103+
104+
return htmlWrapper(wrappedHtml, layoutStyles, customStylesString);
105+
};
106+
};
107+
57108
const templates = {
58-
default: (htmlString) =>
59-
htmlWrapper(htmlString, 'display: grid; place-items: center; gap: 0.5rem;'),
60-
alignStart: (htmlString) =>
61-
htmlWrapper(
62-
`<div>${htmlString}</div>`,
63-
'display: grid; place-items: start center; gap: 0.5rem;',
64-
),
65-
wrapped: (htmlString) =>
66-
htmlWrapper(
67-
`<div>${htmlString}</div>`,
68-
'display: grid; place-items: center; gap: 0.5rem;',
69-
),
70-
inline: (htmlString) =>
71-
htmlWrapper(
72-
htmlString,
109+
default: createTemplate({
110+
layoutStyles: 'display: grid; place-items: center; gap: 0.5rem;',
111+
}),
112+
alignStart: createTemplate({
113+
layoutStyles: 'display: grid; place-items: start center; gap: 0.5rem;',
114+
wrapperElement: 'div',
115+
}),
116+
wrapped: createTemplate({
117+
layoutStyles: 'display: grid; place-items: center; gap: 0.5rem;',
118+
wrapperElement: 'div',
119+
}),
120+
inline: createTemplate({
121+
layoutStyles:
73122
'display: flex; justify-content: center; align-items: center; gap: 0.5rem;',
74-
),
75-
section: (htmlString) =>
76-
htmlWrapper(
77-
`<s-section padding="none">${htmlString}</s-section>`,
78-
'display: grid; place-items: center; background: #F1F1F1',
79-
),
80-
page: (htmlString) =>
81-
htmlWrapper(
82-
htmlString,
83-
'display: grid; place-items: center; background: #F1F1F1;',
84-
),
85-
none: (htmlString) => htmlWrapper(htmlString, 'padding: 0'),
123+
}),
124+
section: createTemplate({
125+
layoutStyles: 'display: grid; place-items: center; background: #F1F1F1',
126+
wrapperElement: 's-section',
127+
wrapperAttributes: 'padding="none"',
128+
}),
129+
page: createTemplate({
130+
layoutStyles: 'display: grid; place-items: center; background: #F1F1F1;',
131+
}),
132+
none: createTemplate({
133+
layoutStyles: 'padding: 0;',
134+
}),
86135
};
87136

88137
const transformJson = async (filePath, isExtensions) => {
@@ -124,8 +173,8 @@ const transformJson = async (filePath, isExtensions) => {
124173

125174
const previewHTML =
126175
tab.layout && tab.layout in templates
127-
? templates[tab.layout](tab.code)
128-
: templates.default(tab.code);
176+
? templates[tab.layout](tab.code, tab.customStyles)
177+
: templates.default(tab.code, tab.customStyles);
129178

130179
newTabs.push(
131180
{code: tab.code, language: 'html'},

‎packages/ui-extensions/docs/surfaces/admin/screenshots/components/modal.png‎

23.2 KB
Loading

‎packages/ui-extensions/src/docs/shared/components/Modal.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ const data: SharedReferenceEntityTemplateSchema = {
55
description:
66
'Use modal to display content in a overlay. This component is useful for creating a distraction-free experience, such as a confirmation dialog or a settings panel.',
77
category: 'Polaris web components',
8-
subCategory: 'Overlay',
8+
subCategory: 'Overlays',
99
related: [],
1010
};
1111

‎packages/ui-extensions/src/surfaces/admin/components/DateField/DateField.doc.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ const data: AdminReferenceEntityTemplateSchema = {
2727
code: './examples/default.html',
2828
language: 'preview',
2929
layout: 'alignStart',
30+
customStyles: {
31+
minHeight: '300px',
32+
},
3033
},
3134
],
3235
},

‎packages/ui-extensions/src/surfaces/admin/components/Modal/Modal.ab.doc.ts‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
import {AdminReferenceEntityTemplateSchema} from '../../docs-types';
2+
import sharedContent from '../../../../docs/shared/components/Modal';
3+
4+
const data: AdminReferenceEntityTemplateSchema = {
5+
...sharedContent,
6+
thumbnail: '/assets/templated-apis-screenshots/admin/components/modal.png',
7+
isVisualComponent: true,
8+
definitions: [
9+
{
10+
title: 'Properties',
11+
description: '',
12+
type: 'Modal',
13+
},
14+
{
15+
title: 'Events',
16+
description:
17+
'Learn more about [registering events](/docs/api/app-home/using-polaris-components#event-handling).',
18+
type: 'ModalEvents',
19+
},
20+
{
21+
title: 'Slots',
22+
description: '',
23+
type: 'ModalSlots',
24+
},
25+
],
26+
defaultExample: {
27+
codeblock: {
28+
title: 'Code',
29+
tabs: [
30+
{
31+
code: './examples/default.html',
32+
language: 'preview',
33+
customStyles: {
34+
minHeight: '300px',
35+
},
36+
},
37+
],
38+
},
39+
},
40+
};
41+
42+
export default data;

‎packages/ui-extensions/src/surfaces/admin/components/Modal/examples/default.html‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<s-button commandFor="modal">
2+
Open
3+
</s-button>
4+
5+
<s-modal id="modal" heading="Details">
6+
<s-paragraph>
7+
Displaying more details here.
8+
</s-paragraph>
9+
10+
<s-button
11+
slot="secondary-actions"
12+
commandFor="modal"
13+
command="--hide">
14+
Close
15+
</s-button>
16+
<s-button
17+
slot="primary-action"
18+
variant="primary"
19+
commandFor="modal"
20+
command="--hide">
21+
Save
22+
</s-button>
23+
</s-modal>

‎packages/ui-extensions/src/surfaces/admin/docs-types.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
1+
import type {CSSProperties} from 'react';
12
import {
23
ReferenceEntityTemplateSchema,
34
CodeTabType,
45
} from '@shopify/generate-docs';
56

7+
// Don't allow all CSS properties to be used in the customStyles property
8+
type AllowedCSSProperties = Pick<CSSProperties, 'minHeight' | 'minBlockSize'>;
9+
610
export interface AdminReferenceEntityTemplateSchema
711
extends Omit<ReferenceEntityTemplateSchema, 'defaultExample'> {
812
defaultExample?: Omit<
@@ -11,7 +15,10 @@ export interface AdminReferenceEntityTemplateSchema
1115
> & {
1216
codeblock?: {
1317
title: string;
14-
tabs: (CodeTabType & {layout?: string})[];
18+
tabs: (CodeTabType & {
19+
layout?: string;
20+
customStyles?: AllowedCSSProperties;
21+
})[];
1522
};
1623
};
1724
}

0 commit comments

Comments
 (0)