if (!text) return '';

return text.replaceAll('|', '\\|')

.replaceAll('\n\n', '<br/><br/>')

.replaceAll('\n', ' ');

return (

declaration.kind === 'class' && declaration.customElement &&

declaration.tagName && !declaration.tagName.endsWith('-internal'));

const filePath = join(basePath, 'doc_src', `README.${section}.md`);

try {

return newParagraph(readFileSync(filePath));

} catch (e) {

return '';

}

if (_packageData) {

return _packageData;

}

_packageData = JSON.parse(readFileSync('package.json'));

return _packageData;

if (_exportsLookup) {

return _exportsLookup;

}

const npmExports = getPackageData().exports;

_exportsLookup = new Map();

for (let [alias, exportPath] of Object.entries(npmExports)) {

_exportsLookup.set(exportPath, alias);

}

return _exportsLookup;

let md = '';

const npmExports = getNpmExportsLookup();

const npmPath = './' + modulePath.replace(/ts$/, 'js');

// Only create a section if this component is specifically exported.

if (!npmExports.has(npmPath)) {

return md;

}

const npmAlias = npmExports.get(npmPath).replace(/^\.\//, '');

const packageName = getPackageData().name;

md += newParagraph(header(headerLevel, 'Importing'));

md += newParagraph(

'When loading the library with a &lt;script&gt; tag (referencing the CDN bundle), please refer to the instructions in the root-level Readme. You do not need to take additional steps to use this component.');

md += newParagraph(

`When bundling your dependencies and you want to include \`<${

tagName}>\` on a page:`);

md += newParagraph(

'```\n' +

`import '${packageName}/${npmAlias}';` +

'\n```');

md += newParagraph(

`When bundling your dependencies and you need to access the class \`${

className}\` directly (less common):`);

md += newParagraph(

'```\n' +

`import { ${className} } from '${packageName}/${npmAlias}';` +

'\n```');

return md;

const content = getStaticContent(basePath, 'apis');

if (!content) return '';

let md = newParagraph(header(headerLevel, 'APIs and Pricing'));

md += newParagraph(

'In addition to the [Maps JavaScript API](https://developers.google.com/maps/documentation/javascript?utm_source=github&utm_medium=documentation&utm_campaign=&utm_content=web_components), this component relies on the following Google Maps Platform APIs which may incur cost and must be enabled.');

md += content;

return md;

const content = getStaticContent(basePath, 'examples');

if (!content) return '';

return newParagraph(header(headerLevel, 'Examples')) + newParagraph(content);

const header = table[0];

const rows = table.slice(1);

rows.sort((a, b) => a[0].localeCompare(b[0]));

return [header, ...rows];

table.push([

`[${componentName}](${docUrl})`,

sanitizeForMarkdownTable(firstParagraphOf(description)),

]);

// Create a relative path without a beginning slash, e.g. "api_loader"

const relativePath = readmeDir.slice(BASE_PATH.length + 1);

if (!relativePath) return '';

const pathSegments = relativePath.split(pathSep);

const relativeReadmeUrl =

(toLevel) => {

let url = '';

for (let i = 0; i < (pathSegments.length - toLevel); i++) {

url += '../';

}

return url + 'README.md';

}

// https://stackoverflow.com/a/64489760

const titleCase = (s) =>

s.replace(/^[-_]*(.)/, (_, c) => c.toUpperCase())

.replace(/[-_]+(.)/g, (_, c) => ' ' + c.toUpperCase());

const breadcrumbs = [`[Extended Component Library](${relativeReadmeUrl(0)})`];

for (let i = 0; i < (pathSegments.length - 1); i++) {

breadcrumbs.push(

`[${titleCase(pathSegments[i])}](${relativeReadmeUrl(i + 1)})`);

}

return newParagraph(breadcrumbs.join(' » '));

const readmePath = join(basePath, 'README.md');

const md = generateBreadcrumbs(basePath) +

appendStaticHeaderAndFooter(basePath, content);

try {

writeFileSync(readmePath, md);

} catch (e) {

console.error(e);

process.exit(1);

}

let headerName = `${asCode(`<${declaration.tagName}>`)} (as class ${

asCode(declaration.name)})`;

if (FRIENDLY_NAMES[declaration.name]) {

headerName = FRIENDLY_NAMES[declaration.name] + ': ' + headerName;

}

let md = newParagraph(header(headerLevel, headerName));

md += newParagraph(declaration.description);

if (declaration.superclass &&

declaration.superclass.name === 'PlaceDataConsumer') {

md += newParagraph(

'> This component is designed to work with a Place Data Provider; please see [Place Building Blocks](../README.md) for more information.');

}

const importSection = makeImportSection(

headerLevel + 1, module.path, declaration.name, declaration.tagName);

if (importSection) {

md += importSection;

}

const fields = getPublicMembers(declaration, 'field');

if (fields.length > 0) {

md += newParagraph(header(headerLevel + 1, 'Attributes and properties'));

const fieldsTable = [

[

'Attribute',

'Property',

'Property type',

'Description',

'Default',

'Reflects?',

],

];

for (const field of fields) {

fieldsTable.push([

field.attribute ? asCode(field.attribute) : '',

field.name ? asCode(field.name) : '',

field?.type?.text ? asCode(sanitizeForMarkdownTable(field.type.text)) :

'',

sanitizeForMarkdownTable(field.description || ''),

field.default ? asCode(sanitizeForMarkdownTable(field.default)) : '',

field.reflects ? '✅' : '❌',

]);

}

md += newParagraph(markdownTable(fieldsTable));

}

if (declaration.slots) {

md += newParagraph(header(headerLevel + 1, 'Slots'));

const hasNamedSlot = declaration.slots.some(x => x.name);

if (hasNamedSlot) {

md += newParagraph(

`This component uses [named slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots#adding_flexibility_with_slots) to accept custom content. To place content in a named slot, set the content as an HTML child of \`<${

declaration

.tagName}>\` and add the attribute \`slot="SLOT_NAME"\` to it.`);

}

const slotsTable = [['Slot name', 'Description']];

for (const slot of declaration.slots) {

slotsTable.push([

slot.name || '*(default)*',

(slot.summary || '') + (slot.description || ''),

]);

}

md += newParagraph(markdownTable(slotsTable));

}

const methods = getPublicMembers(declaration, 'method');

if (methods.length > 0) {

md += newParagraph(header(headerLevel + 1, 'Methods'));

for (const method of methods) {

const argsSummary =

(method.parameters || []).map((x) => x.name).join(', ');

let fullMethodCall = `${method.name}(${argsSummary})`;

let staticComment = '';

if (method.static) {

fullMethodCall = `${declaration.name}.${fullMethodCall}`;

staticComment = ' (static method)';

}

md += newParagraph(

header(headerLevel + 2, asCode(fullMethodCall) + staticComment));

md += newParagraph(method.description);

if (method.return) {

md += newParagraph(`**Returns:** ${asCode(method.return.type.text)}`);

}

if (method.parameters) {

md += newParagraph('**Parameters:**');

const paramsTable = [['Name', 'Optional?', 'Type', 'Description']];

for (const param of method.parameters) {

paramsTable.push([

asCode(param.name),

param.optional ? 'optional' : '',

asCode(sanitizeForMarkdownTable(param.type.text)),

sanitizeForMarkdownTable(param.description),

]);

}

md += newParagraph(markdownTable(paramsTable));

}

}

}

if (declaration.events) {

md += newParagraph(header(headerLevel + 1, 'Events'));

const eventsTable = [['Name', 'Type', 'Description']];

for (const event of declaration.events) {

eventsTable.push([

asCode(event.name),

asCode(sanitizeForMarkdownTable(event.type.text)),

sanitizeForMarkdownTable(event.description),

]);

}

md += newParagraph(markdownTable(eventsTable));

}

const hasCustomStyling =

!!(declaration.cssProperties || declaration.cssParts);

const hasSimpleStyling = COMPONENTS_STYLED_AS_TEXT.has(declaration.name);

if (hasCustomStyling || hasSimpleStyling) {

md += newParagraph(header(headerLevel + 1, 'Styling'));

if (hasSimpleStyling) {

md += newParagraph(

`This is a low-level component designed to be styled with built-in CSS properties. For most styling purposes, it is equivalent to a \`<span>\` element.`);

md += newParagraph(

`For example, by default this component will inherit the color of its parent element. However, you can change the color by writing the following CSS:`);

md += newParagraph(`

\`\`\`css

${declaration.tagName} {

color: blue;

}

\`\`\``);

} else {

md += newParagraph(

`You can use most built-in CSS properties to control the positioning or display of this component, similar to a \`<span>\` element. The component also supports the following styling inputs for more customization:`);

if (declaration.cssProperties) {

md += newParagraph(header(headerLevel + 2, 'CSS Custom Properties'));

const cssTable = [['Name', 'Default', 'Description']];

let usesGlobalStyles = false;

for (const customProp of declaration.cssProperties) {

let description = customProp.summary ?? '';

description += customProp.description ?? '';

const styleDefault = CSS_CUSTOM_PROPERTY_DEFAULTS[customProp.name];

let defaultValue = customProp.default || styleDefault || '';

if (GLOBAL_STYLE_TOKENS.has(customProp.name)) {

description += ' 🌎';

usesGlobalStyles |= true;

}

cssTable.push([

asCode(customProp.name), asCode(defaultValue),

sanitizeForMarkdownTable(description)

]);

}

md += newParagraph(markdownTable(cssTable));

if (usesGlobalStyles) {

md += newParagraph(`🌎 _indicates a global style token shared by

multiple components. Please see the library

Readme for more information._`);

}

}

if (declaration.cssParts) {

md += newParagraph(header(headerLevel + 2, 'CSS Parts'));

let partsTable = [['Name', 'Description']];

for (const part of declaration.cssParts) {

partsTable.push(

[asCode(part.name), sanitizeForMarkdownTable(part.description)]);

}

md += newParagraph(markdownTable(partsTable));

}

}

}

return md;

return {

name: 'readme',

packageLinkPhase({customElementsManifest}) {

// Organize modules by the README file they should be documented in.

const moduleReadmes = new Map();

for (const module of customElementsManifest.modules) {

const moduleReadme = getReadmeForModule(module);

if (!moduleReadmes.has(moduleReadme)) {

moduleReadmes.set(moduleReadme, []);

}

moduleReadmes.get(moduleReadme).push(module);

}

// For each README file, generate contents from the modules assigned to

// it. At the same time, add the file's link to a table of contents.

const rootInventoryTable = [['Component', 'Description']];

const placeDataProviderInventoryTable = [['Component', 'Description']];

const placeConsumerInventoryTable = [['Component', 'Description']];

for (const [filename, modules] of moduleReadmes.entries()) {

let md = '';

for (const module of modules) {

const dirPath = join(BASE_PATH, dirname(module.path));

const manualHeader = getStaticContent(dirPath, 'header');

// If there's a header, assume it includes the top-level Markdown

// title.

const declHeaderLevel = manualHeader ? 2 : 1;

md += manualHeader ? newParagraph(manualHeader) : '';

for (const declaration of module.declarations) {

if (shouldDocumentDeclaration(declaration, module)) {

md += newParagraph(declarationToMarkdown(

declaration, module, /* headerLevel= */ declHeaderLevel));

const componentName = asCode(

declaration.tagName ? '<' + declaration.tagName + '>' :

declaration.name);

// Place Building Block components get their own mini-inventory

if (filename.startsWith(PLACE_BUILDING_BLOCKS_DIR)) {

const relativeFilename =

filename.substring(PLACE_BUILDING_BLOCKS_DIR.length + 1);

if (declaration.name === 'PlaceDataProvider') {

addInventoryRow(

placeDataProviderInventoryTable, componentName,

relativeFilename, declaration.description);

} else {

addInventoryRow(

placeConsumerInventoryTable, componentName,

relativeFilename, declaration.description);

}

} else {

addInventoryRow(

rootInventoryTable, componentName, filename,

declaration.description);

}

md += makeExamplesSection(

dirPath, /* headerLevel = */ declHeaderLevel + 1);

md += makeApiSkuSection(

dirPath, /* headerLevel= */ declHeaderLevel + 1);

}

}

}

if (md) {

md = generateBreadcrumbs(dirname(join(BASE_PATH, filename))) + md;

try {

writeFileSync(join(BASE_PATH, filename), md);

} catch (e) {

console.error(e);

process.exit(1);

}

}

}

// Write a group README for Place Building Blocks components.

const buildingBlocksInventory = newParagraph(header(2, 'Data provider')) +

newParagraph(markdownTable(

sortTable(placeDataProviderInventoryTable))) +

newParagraph(header(2, 'Details components')) +

newParagraph(markdownTable(sortTable(placeConsumerInventoryTable)));

writeReadme(

join(BASE_PATH, PLACE_BUILDING_BLOCKS_DIR), buildingBlocksInventory);

// Finally, write a package-level README with a table of contents.

writeReadme(

BASE_PATH, markdownTable([

...sortTable(rootInventoryTable),

[

`[Place building blocks](${PLACE_BUILDING_BLOCKS_DIR}/README.md)`,

'The place data provider component, along with individual place details components, lets you choose how to display Google Maps place information like opening hours, star reviews, and photos in a new, custom view. '

]

]));

},

};