mcp/carbon-components-svelte
1
0
Fork 0
mirror of https://github.com/carbon-design-system/carbon-components-svelte.git synced 2025-09-14 18:01:06 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: add component API information

Browse source
This commit is contained in:
Eric Liu 2020-10-16 18:20:39 -07:00
commit 0d0d35e715
36 changed files with 18462 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

18043
docs/src/PUBLIC_API.json Normal file
View file

File diff suppressed because it is too large Load diff

152
docs/src/components/ComponentApi.svelte Normal file
View file

@ -0,0 +1,152 @@
<script>
export let component = {
props: [],
slots: [],
forwarded_events: [],
dispatched_events: [],
};
import {
Link,
StructuredList,
StructuredListHead,
StructuredListRow,
StructuredListCell,
StructuredListBody,
TooltipDefinition,
UnorderedList,
ListItem,
} from "carbon-components-svelte";
import InlineSnippet from "./InlineSnippet.svelte";
import Launch16 from "carbon-icons-svelte/lib/Launch16";
const mdn_api = "https://developer.mozilla.org/en-US/docs/Web/API/";
const typeMap = {
string: "string",
boolean: "boolean",
number: "number",
null: "null",
Date: "JavaScript Date",
};
</script>
<style>
.description {
margin-bottom: var(--cds-spacing-04);
}
.cell {
position: relative;
z-index: 9;
min-height: 1.25rem;
margin-bottom: var(--cds-spacing-02);
}
.overflow {
overflow-x: auto;
}
:global(.my-layout-01-03),
:global(.overflow .bx--structured-list) {
margin-top: var(--cds-layout-01);
margin-bottom: var(--cds-layout-04);
}
</style>
<h3 id="props">Props</h3>
<div class="overflow">
<StructuredList
style="margin-left: calc(-1 * var(--cds-spacing-05)); margin-right: calc(-1 * var(--cds-spacing-05))"
>
<StructuredListHead>
<StructuredListRow head>
<StructuredListCell head>Prop name</StructuredListCell>
<StructuredListCell head>Type</StructuredListCell>
<StructuredListCell head noWrap>Default value</StructuredListCell>
<StructuredListCell head>Description</StructuredListCell>
</StructuredListRow>
</StructuredListHead>
<StructuredListBody>
{#each component.props as prop}
<StructuredListRow>
<StructuredListCell noWrap>
<InlineSnippet code="{prop[0]}" />
</StructuredListCell>
<StructuredListCell>
{#each prop[1].type.split(' | ') as type, i (type)}
<div
class="cell"
style="z-index: {prop[1].type.split(' | ').length - i}"
>
{#if type.startsWith('typeof')}
<TooltipDefinition
direction="top"
align="start"
tooltipText="{`From "carbon-icons-svelte"`}"
>
Carbon Svelte icon
</TooltipDefinition>
{:else if type.startsWith('HTML')}
<Link
href="{mdn_api}{type}"
target="_blank"
style="white-space: nowrap"
>
{type}
<Launch16 />
</Link>
{:else if type in typeMap}
<code>{typeMap[type]}</code>
{:else if type.startsWith('(')}
<code>{type}</code>
{:else}
<InlineSnippet code="{type}" />
{/if}
</div>
{/each}
</StructuredListCell>
<StructuredListCell><code>{prop[1].value}</code></StructuredListCell>
<StructuredListCell>
{#each prop[1].description.split('\n') as line}
<div class="description">{line}.</div>
{/each}
</StructuredListCell>
</StructuredListRow>
{/each}
</StructuredListBody>
</StructuredList>
</div>
<h3 id="slots">Slots</h3>
{#if component.slots.length > 0}
<UnorderedList class="my-layout-01-03">
{#each component.slots as slot}
<ListItem>{slot[0]}</ListItem>
{/each}
</UnorderedList>
{:else}
<p class="my-layout-01-03">No slots.</p>
{/if}
<h3 id="forwarded-events">Forwarded events</h3>
{#if component.forwarded_events.length > 0}
<UnorderedList class="my-layout-01-03">
{#each component.forwarded_events as event}
<ListItem>on:{event[0]}</ListItem>
{/each}
</UnorderedList>
{:else}
<p class="my-layout-01-03">No forwarded events.</p>
{/if}
<h3 id="dispatched-events">Dispatched events</h3>
{#if component.dispatched_events.length > 0}
<UnorderedList class="my-layout-01-03">
{#each component.dispatched_events as event}
<ListItem>on:{event[0]}</ListItem>
{/each}
</UnorderedList>
{:else}
<p class="my-layout-01-03">No dispatched events.</p>
{/if}

22
docs/src/components/InlineSnippet.svelte Normal file
View file

@ -0,0 +1,22 @@
<script>
export let code = "";
import { CodeSnippet } from "carbon-components-svelte";
import copy from "clipboard-copy";
</script>
<style>
div {
margin-bottom: var(--cds-spacing-04);
}
</style>
<div>
<CodeSnippet
code="{code}"
type="inline"
on:click="{() => {
copy(code);
}}"
/>
</div>

53
docs/src/layouts/ComponentLayout.svelte
View file

@ -1,6 +1,7 @@
<script>
import {
Grid,
Link,
Row,
Column,
Content,
@ -8,19 +9,33 @@
Select,
SelectItem,
InlineNotification,
Tabs,
Tab,
TabContent,
StructuredList,
StructuredListHead,
StructuredListRow,
StructuredListCell,
StructuredListBody,
} from "carbon-components-svelte";
import Code16 from "carbon-icons-svelte/lib/Code16";
import { page, metatags } from "@sveltech/routify";
import { onMount } from "svelte";
import { theme } from "../store";
import ComponentApi from "../components/ComponentApi.svelte";
import API from "../PUBLIC_API.json";
export let component = $page.title;
export let components = [component];
export let source = "";
export let unreleased = false;
export let unstable = false;
metatags.title = $page.title;
$: api = components.map((_) => API.components[_]).filter(Boolean);
$: multiple = api.length > 1;
onMount(() => {
const currentTheme = window.location.search.split("?theme=")[1];
@ -36,6 +51,12 @@
</script>
<style global>
.override-tabs a.bx--tabs__nav-link,
.override-tabs a.bx--tabs__nav-link:focus,
.override-tabs a.bx--tabs__nav-link:active {
width: auto !important;
}
#select-theme {
width: auto;
}
@ -150,6 +171,38 @@
</div>
<h2 id="usage">Usage</h2>
<slot />
<h2 id="component-api">Component API</h2>
<p>
Component API documentation is
<Link
inline
href="https://github.com/IBM/carbon-components-svelte/blob/master/scripts/rollup/plugin-generate-docs.js"
target="_blank"
>
auto-generated
</Link>.
</p>
</Column>
</Row>
<Row>
<Column class="prose" noGutter="{multiple}">
{#if multiple}
<Tabs class="override-tabs">
{#each api as component, i (component.moduleName)}
<Tab label="{component.moduleName}" />
{/each}
<div slot="content" style="padding-top: var(--cds-spacing-06)">
{#each api as component, i (component.moduleName)}
<TabContent>
<ComponentApi component="{component}" />
</TabContent>
{/each}
</div>
</Tabs>
{:else}
<ComponentApi component="{api[0]}" />
{/if}
</Column>
</Row>
</Grid>

3
docs/src/pages/_layout.svelte
View file

@ -184,7 +184,6 @@
icon="{{ render: LogoGithub20 }}"
href="https://github.com/IBM/carbon-components-svelte"
target="_blank"
rel="noopener"
/>
<HeaderAction bind:isOpen>
<HeaderPanelLinks>
@ -217,7 +216,7 @@
<SideNav bind:isOpen="{isSideNavOpen}">
<SideNavItems>
<SideNavMenu
expanded="{$isActive($url('/components'))}"
expanded="{$isActive($url('')) || $isActive($url('/components'))}"
text="Components"
>
{#each components.children as child, i (child.path)}

4
docs/src/pages/components/Accordion.svx
View file

@ -1,3 +1,7 @@
---
components: ["Accordion", "AccordionItem", "AccordionSkeleton"]
---
<script>
import {
Accordion,

4
docs/src/pages/components/Breadcrumb.svx
View file

@ -1,3 +1,7 @@
---
components: ["Breadcrumb", "BreadcrumbItem"]
---
<script>
import {
Breadcrumb,

4
docs/src/pages/components/ComposedModal.svx
View file

@ -1,3 +1,7 @@
---
components: ["ComposedModal", "ModalHeader", "ModalBody", "ModalFooter", "Checkbox"]
---
<script>
import Preview from "../../components/Preview.svelte";
</script>

4
docs/src/pages/components/ContentSwitcher.svx
View file

@ -1,3 +1,7 @@
---
components: ["ContentSwitcher", "Switch"]
---
<script>
import { ContentSwitcher, Switch } from "carbon-components-svelte";
import Add16 from "carbon-icons-svelte/lib/Add16";

4
docs/src/pages/components/DatePicker.svx
View file

@ -1,3 +1,7 @@
---
components: ["DatePicker", "DatePickerInput", "DatePickerSkeleton"]
---
<script>
import { DatePicker, DatePickerSkeleton, DatePickerInput } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/Dropdown.svx
View file

@ -1,3 +1,7 @@
---
components: ["Dropdown", "DropdownSkeleton"]
---
<script>
import { Dropdown, DropdownSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/FileUploader.svx
View file

@ -1,3 +1,7 @@
---
components: ["FileUploaderButton", "FileUploader", "FileUploaderDropContainer", "FileUploaderItem", "FileUploaderSkeleton"]
---
<script>
import { FileUploaderButton, FileUploader, FileUploaderDropContainer, FileUploaderItem, FileUploaderSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/Form.svx
View file

@ -1,3 +1,7 @@
---
components: ["Form", "FormGroup"]
---
<script>
import { Form,
FormGroup,

4
docs/src/pages/components/Grid.svx
View file

@ -1,3 +1,7 @@
---
components: ["Grid", "Row", "Column"]
---
<script>
import Preview from "../../components/Preview.svelte";
</script>

4
docs/src/pages/components/NumberInput.svx
View file

@ -1,3 +1,7 @@
---
components: ["NumberInput", "NumberInputSkeleton"]
---
<script>
import { NumberInput, NumberInputSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/OrderedList.svx
View file

@ -1,3 +1,7 @@
---
components: ["OrderedList", "ListItem"]
---
<script>
import { OrderedList, ListItem, Link } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/OverflowMenu.svx
View file

@ -1,3 +1,7 @@
---
components: ["OverflowMenu", "OverflowMenuItem"]
---
<script>
import { OverflowMenu, OverflowMenuItem } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/Pagination.svx
View file

@ -1,3 +1,7 @@
---
components: ["Pagination", "PaginationSkeleton"]
---
<script>
import { Pagination, PaginationSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/ProgressIndicator.svx
View file

@ -1,3 +1,7 @@
---
components: ["ProgressIndicator", "ProgressStep", "ProgressIndicatorSkeleton"]
---
<script>
import { ProgressIndicator, ProgressStep, ProgressIndicatorSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/RadioButton.svx
View file

@ -1,3 +1,7 @@
---
components: ["RadioButtonGroup", "RadioButton", "RadioButtonSkeleton"]
---
<script>
import { FormGroup, RadioButton, RadioButtonSkeleton, RadioButtonGroup } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/RadioTile.svx
View file

@ -1,3 +1,7 @@
---
components: ["TileGroup", "RadioTile"]
---
<script>
import { TileGroup, RadioTile } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/Select.svx
View file

@ -1,3 +1,7 @@
---
components: ["Select", "SelectItem", "SelectItemGroup", "SelectSkeleton"]
---
<script>
import { Select, SelectItem, SelectItemGroup, SelectSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/SelectableTile.svx
View file

@ -1,3 +1,7 @@
---
components: ["TileGroup", "SelectableTile"]
---
<script>
import { TileGroup, SelectableTile } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/Slider.svx
View file

@ -1,3 +1,7 @@
---
components: ["Slider", "SliderSkeleton"]
---
<script>
import { Slider, SliderSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/StructuredList.svx
View file

@ -1,3 +1,7 @@
---
components: ["StructuredList", "StructuredListSkeleton", "StructuredListBody", "StructuredListHead", "StructuredListCell", "StructuredListRow", "StructuredListInput"]
---
<script>
import { StructuredList, StructuredListSkeleton, StructuredListBody, StructuredListHead, StructuredListCell ,StructuredListRow, StructuredListInput } from "carbon-components-svelte";
import CheckmarkFilled16 from "carbon-icons-svelte/lib/CheckmarkFilled16";

4
docs/src/pages/components/Tabs.svx
View file

@ -1,3 +1,7 @@
---
components: ["Tabs", "Tab", "TabContent", "TabsSkeleton"]
---
<script>
import { Tabs, Tab, TabContent, TabsSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/TextArea.svx
View file

@ -1,3 +1,7 @@
---
components: ["TextArea", "TextAreaSkeleton"]
---
<script>
import { TextArea, TextAreaSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/TextInput.svx
View file

@ -1,3 +1,7 @@
---
components: ["TextInput", "TextInputSkeleton"]
---
<script>
import { TextInput, TextInputSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/TimePicker.svx
View file

@ -1,3 +1,7 @@
---
components: ["TimePicker", "TimePickerSelect", "SelectItem"]
---
<script>
import { TimePicker, TimePickerSelect, SelectItem } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/Toggle.svx
View file

@ -1,3 +1,7 @@
---
components: ["Toggle", "ToggleSkeleton"]
---
<script>
import { Toggle, ToggleSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

4
docs/src/pages/components/ToggleSmall.svx
View file

@ -1,3 +1,7 @@
---
components: ["ToggleSmall", "ToggleSmallSkeleton"]
---
<script>
import { ToggleSmall, ToggleSmallSkeleton } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

24
docs/src/pages/components/UIShell.svx
View file

@ -1,3 +1,27 @@
---
components: ["Header",
"HeaderAction",
"HeaderActionLink",
"HeaderActionSearch",
"HeaderNav",
"HeaderNavItem",
"HeaderNavMenu",
"HeaderPanelDivider",
"HeaderPanelLink",
"HeaderPanelLinks",
"HeaderUtilities",
"SideNav",
"SideNavItems",
"SideNavLink",
"SideNavMenu",
"SideNavMenuItem",
"Content",
"SkipToContent",
"HeaderGlobalAction"]
---
<script>
import Preview from "../../components/Preview.svelte";
</script>

4
docs/src/pages/components/UnorderedList.svx
View file

@ -1,3 +1,7 @@
---
components: ["UnorderedList", "ListItem"]
---
<script>
import { UnorderedList, ListItem, Link } from "carbon-components-svelte";
import Preview from "../../components/Preview.svelte";

17
docs/svelte.config.js
View file

@ -227,6 +227,23 @@ module.exports = {
.join("")}
</ul>
</li>
<li class="bx--list__item">
<a class="bx--link" href="#component-api">Component API</a>
<ul class="bx--list--unordered bx--list--nested">
<li class="bx--list__item">
<a class="bx--link" href="#props">Props</a>
</li>
<li class="bx--list__item">
<a class="bx--link" href="#slots">Slots</a>
</li>
<li class="bx--list__item">
<a class="bx--link" href="#forwarded-events">Forwarded events</a>
</li>
<li class="bx--list__item">
<a class="bx--link" href="#dispatched-events">Dispatched events</a>
</li>
</ul>
</li>
</ul>
</div>
</Layout_MDSVEX_DEFAULT>`

29
scripts/rollup/generate-public-api.js Normal file
View file

@ -0,0 +1,29 @@
/**
* Use library component metadata to generate component documentation in JSON format.
* @param {Map<string, { component: { exported_props: Map<string, any>; slots: Map<string, any>; } typedefs: {name: string; type: string;}[] }>} components
* @param {Map<string, string[]>} groups
* @param {{name: string; version: string; homepage: string;}} pkg
*/
export function generatePublicAPI(components, groups, pkg) {
const code = {
version: pkg.version,
components: {},
};
components.forEach((component, moduleName) => {
const props = Array.from(component.component.exported_props);
const slots = Array.from(component.component.slots);
const forwarded_events = Array.from(component.component.forwarded_events);
const dispatched_events = Array.from(component.component.dispatched_events);
code.components[moduleName] = {
moduleName,
props,
slots,
forwarded_events,
dispatched_events,
};
});
return { code };
}

16
scripts/rollup/plugin-generate-docs.js
View file

@ -1,10 +1,14 @@
import fs from "fs";
import path from "path";
import { promisify } from "util";
import pkg from "../../package.json";
import { format } from "prettier";
import { parseComponent } from "./parse-component";
import { generateTypes } from "./generate-types";
import { generateIndex } from "./generate-index";
import { generatePublicAPI } from "./generate-public-api";
const writeFile = promisify(fs.writeFile);
/**
* Rollup plugin to generate library TypeScript definitions and documentation.
@ -58,15 +62,21 @@ function pluginGenerateDocs() {
}
}
},
writeBundle() {
async writeBundle() {
const { code: types } = generateTypes(components, pkg);
fs.writeFileSync(pkg.types, format(types, { parser: "typescript" }));
await writeFile(pkg.types, format(types, { parser: "typescript" }));
const { code: index } = generateIndex(components, groups, pkg);
fs.writeFileSync(
await writeFile(
"./COMPONENT_INDEX.md",
format(index, { parser: "markdown" })
);
const { code: json } = generatePublicAPI(components, groups, pkg);
await writeFile(
"./docs/src/PUBLIC_API.json",
JSON.stringify(json, null, 2)
);
},
};
}