mcp/carbon-components-svelte
1
0
Fork 0
mirror of https://github.com/carbon-design-system/carbon-components-svelte.git synced 2025-09-15 02:11:05 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: enhance Component API documentation

Browse source 
Replaces PUBLIC_API.json with COMPONENT_API.json generated by sveld.
This commit is contained in:
Eric Liu 2020-11-19 06:13:18 -08:00
commit b313fb6787
9 changed files with 110 additions and 16516 deletions
Download patch file Download diff file Expand all files Collapse all files

0
COMPONENT_API.json → docs/src/COMPONENT_API.json
View file

16451
docs/src/PUBLIC_API.json
View file

File diff suppressed because it is too large Load diff

80
docs/src/components/ComponentApi.svelte
View file

@ -2,8 +2,8 @@
export let component = { export let component = {
props: [], props: [],
slots: [], slots: [],
forwarded_events: [], events: [],
dispatched_events: [], rest_props: undefined,
}; };
import { import {
@ -16,6 +16,7 @@
TooltipDefinition, TooltipDefinition,
UnorderedList, UnorderedList,
ListItem, ListItem,
Tag,
} from "carbon-components-svelte"; } from "carbon-components-svelte";
import InlineSnippet from "./InlineSnippet.svelte"; import InlineSnippet from "./InlineSnippet.svelte";
import Launch16 from "carbon-icons-svelte/lib/Launch16"; import Launch16 from "carbon-icons-svelte/lib/Launch16";
@ -28,6 +29,14 @@
null: "null", null: "null",
Date: "JavaScript Date", Date: "JavaScript Date",
}; };
$: source = `https://github.com/IBM/carbon-components-svelte/tree/master${component.filePath}`;
$: forwarded_events = component.events.filter(
(event) => event.type === "forwarded"
);
$: dispatched_events = component.events.filter(
(event) => event.type === "dispatched"
);
</script> </script>
<style> <style>
@ -53,6 +62,14 @@
} }
</style> </style>
<p style="margin-bottom: var(--cds-layout-02)">
View component
<Link href="{source}" target="_blank">
source code
<Launch16 />
</Link>
</p>
<h3 id="props">Props</h3> <h3 id="props">Props</h3>
{#if component.props.length > 0} {#if component.props.length > 0}
@ -69,16 +86,18 @@
</StructuredListRow> </StructuredListRow>
</StructuredListHead> </StructuredListHead>
<StructuredListBody> <StructuredListBody>
{#each component.props as prop} {#each component.props.sort((a, b) => {
if (a.reactive > b.reactive) return -1;
}) as prop (prop.name)}
<StructuredListRow> <StructuredListRow>
<StructuredListCell noWrap> <StructuredListCell noWrap>
<InlineSnippet code="{prop[0]}" /> <InlineSnippet code="{prop.name}" />
</StructuredListCell> </StructuredListCell>
<StructuredListCell> <StructuredListCell>
{#each prop[1].type.split(' | ') as type, i (type)} {#each prop.type.split(' | ') as type, i (type)}
<div <div
class="cell" class="cell"
style="z-index: {prop[1].type.split(' | ').length - i}" style="z-index: {prop.type.split(' | ').length - i}"
> >
{#if type.startsWith('typeof')} {#if type.startsWith('typeof')}
<TooltipDefinition <TooltipDefinition
@ -106,14 +125,24 @@
{/if} {/if}
</div> </div>
{/each} {/each}
{#if prop.reactive}
<div
style="white-space: nowrap; margin-left: calc(-1 * var(--cds-spacing-03)); margin-top: var(--cds-spacing-05)"
>
<Tag type="green">Reactive</Tag>
</div>
{/if}
</StructuredListCell> </StructuredListCell>
<StructuredListCell><code>{prop.value}</code></StructuredListCell>
<StructuredListCell> <StructuredListCell>
<code>{prop[1].value}</code> {#if prop.description}
</StructuredListCell> {#each prop.description.split('\n') as line}
<StructuredListCell>
{#each prop[1].description.split('\n') as line}
<div class="description">{line}.</div> <div class="description">{line}.</div>
{/each} {/each}
{:else}
<div class="description">No description available.</div>
{/if}
</StructuredListCell> </StructuredListCell>
</StructuredListRow> </StructuredListRow>
{/each} {/each}
@ -126,8 +155,8 @@
<h3 id="slots">Slots</h3> <h3 id="slots">Slots</h3>
{#if component.slots.length > 0} {#if component.slots.length > 0}
<UnorderedList class="my-layout-01-03"> <UnorderedList class="my-layout-01-03">
{#each component.slots as slot} {#each component.slots as slot (slot.name)}
<ListItem>{slot[0]}</ListItem> <ListItem>{slot.default ? 'default' : slot.name}</ListItem>
{/each} {/each}
</UnorderedList> </UnorderedList>
{:else} {:else}
@ -135,10 +164,10 @@
{/if} {/if}
<h3 id="forwarded-events">Forwarded events</h3> <h3 id="forwarded-events">Forwarded events</h3>
{#if component.forwarded_events.length > 0} {#if forwarded_events.length > 0}
<UnorderedList class="my-layout-01-03"> <UnorderedList class="my-layout-01-03">
{#each component.forwarded_events as event} {#each forwarded_events as event (event.name)}
<ListItem>on:{event[0]}</ListItem> <ListItem>on:{event.name}</ListItem>
{/each} {/each}
</UnorderedList> </UnorderedList>
{:else} {:else}
@ -147,12 +176,27 @@
<h3 id="dispatched-events">Dispatched events</h3> <h3 id="dispatched-events">Dispatched events</h3>
{#if component.dispatched_events.length > 0} {#if dispatched_events.length > 0}
<UnorderedList class="my-layout-01-03"> <UnorderedList class="my-layout-01-03">
{#each component.dispatched_events as event} {#each dispatched_events as event (event.name)}
<ListItem>on:{event[0]}</ListItem> <ListItem>on:{event.name}</ListItem>
{/each} {/each}
</UnorderedList> </UnorderedList>
{:else} {:else}
<p class="my-layout-01-03">No dispatched events.</p> <p class="my-layout-01-03">No dispatched events.</p>
{/if} {/if}
<h3 id="rest-props">$$restProps</h3>
<div class="my-layout-01-03">
{#if component.rest_props}
<code>{component.moduleName}</code>
spreads
<code>$$restProps</code>
to the
{#if component.rest_props.type === 'Element'}
<code>{component.rest_props.name}</code>
element.
{:else}<code>{component.rest_props.name}</code> component.{/if}
{:else}This component does not spread <code>restProps</code>{/if}
</div>

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

@ -12,18 +12,13 @@
Tabs, Tabs,
Tab, Tab,
TabContent, TabContent,
StructuredList,
StructuredListHead,
StructuredListRow,
StructuredListCell,
StructuredListBody,
} from "carbon-components-svelte"; } from "carbon-components-svelte";
import Code16 from "carbon-icons-svelte/lib/Code16"; import Code16 from "carbon-icons-svelte/lib/Code16";
import { page, metatags } from "@sveltech/routify"; import { page, metatags } from "@sveltech/routify";
import { onMount } from "svelte"; import { onMount } from "svelte";
import { theme } from "../store"; import { theme } from "../store";
import ComponentApi from "../components/ComponentApi.svelte"; import ComponentApi from "../components/ComponentApi.svelte";
import API from "../PUBLIC_API.json"; import COMPONENT_API from "../COMPONENT_API.json";
export let component = $page.title; export let component = $page.title;
export let components = [component]; export let components = [component];
@ -33,8 +28,10 @@
metatags.title = $page.title; metatags.title = $page.title;
$: api = components.map((_) => API.components[_]).filter(Boolean); $: api_components = components.map((i) =>
$: multiple = api.length > 1; COMPONENT_API.components.find((_) => _.moduleName === i)
);
$: multiple = api_components.length > 1;
onMount(() => { onMount(() => {
const currentTheme = window.location.search.split("?theme=")[1]; const currentTheme = window.location.search.split("?theme=")[1];
@ -173,15 +170,10 @@
<slot /> <slot />
<h2 id="component-api">Component API</h2> <h2 id="component-api">Component API</h2>
<p> <p>
Component API documentation is Component documentation is
<Link <Link inline href="https://github.com/IBM/sveld" target="_blank">
inline auto-generated by sveld.
href="https://github.com/IBM/carbon-components-svelte/blob/master/scripts/rollup/plugin-generate-docs.js"
target="_blank"
>
auto-generated
</Link> </Link>
from a build script.
</p> </p>
</Column> </Column>
</Row> </Row>
@ -190,11 +182,11 @@
<Column class="prose" noGutter="{multiple}"> <Column class="prose" noGutter="{multiple}">
{#if multiple} {#if multiple}
<Tabs class="override-tabs"> <Tabs class="override-tabs">
{#each api as component, i (component.moduleName)} {#each api_components as component (component.moduleName)}
<Tab label="{component.moduleName}" /> <Tab label="{component.moduleName}" />
{/each} {/each}
<div slot="content" style="padding-top: var(--cds-spacing-06)"> <div slot="content" style="padding-top: var(--cds-spacing-06)">
{#each api as component, i (component.moduleName)} {#each api_components as component (component.moduleName)}
<TabContent> <TabContent>
<ComponentApi component="{component}" /> <ComponentApi component="{component}" />
</TabContent> </TabContent>
@ -202,7 +194,7 @@
</div> </div>
</Tabs> </Tabs>
{:else} {:else}
<ComponentApi component="{api[0]}" /> <ComponentApi component="{api_components[0]}" />
{/if} {/if}
</Column> </Column>
</Row> </Row>

1
docs/src/layouts/Recipe.svelte
View file

@ -6,7 +6,6 @@
Content, Content,
Select, Select,
SelectItem, SelectItem,
InlineNotification,
} from "carbon-components-svelte"; } from "carbon-components-svelte";
import { page, metatags } from "@sveltech/routify"; import { page, metatags } from "@sveltech/routify";
import { onMount } from "svelte"; import { onMount } from "svelte";

3
docs/svelte.config.js
View file

@ -242,6 +242,9 @@ module.exports = {
<li class="bx--list__item"> <li class="bx--list__item">
<a class="bx--link" href="#dispatched-events">Dispatched events</a> <a class="bx--link" href="#dispatched-events">Dispatched events</a>
</li> </li>
<li class="bx--list__item">
<a class="bx--link" href="#rest-props">$$restProps</a>
</li>
</ul> </ul>
</li> </li>
</ul> </ul>

10
package.json
View file

@ -35,12 +35,12 @@
"postcss": "^7.0.32", "postcss": "^7.0.32",
"prettier": "^2.1.2", "prettier": "^2.1.2",
"prettier-plugin-svelte": "^1.4.1", "prettier-plugin-svelte": "^1.4.1",
"rollup": "^2.32.1", "rollup": "^2.33.3",
"rollup-plugin-svelte": "^6.1.0", "rollup-plugin-svelte": "^6.1.1",
"rollup-plugin-terser": "^7.0.2", "rollup-plugin-terser": "^7.0.2",
"sveld": "^0.1.0-rc.0", "sveld": "^0.1.0-rc.5",
"svelte": "^3.29.4", "svelte": "^3.29.7",
"svelte-check": "^1.1.6", "svelte-check": "^1.1.14",
"svelte-loader": "^2.13.6", "svelte-loader": "^2.13.6",
"typescript": "^4.0.5" "typescript": "^4.0.5"
}, },

3
rollup.config.js
View file

@ -35,6 +35,9 @@ export default ["es", "umd"].map((format) => {
}, },
}, },
json: true, json: true,
jsonOptions: {
outFile: "docs/src/COMPONENT_API.json",
},
}), }),
], ],
}; };

44
yarn.lock
View file

@ -2287,10 +2287,10 @@ rimraf@2:
dependencies: dependencies:
glob "^7.1.3" glob "^7.1.3"
rollup-plugin-svelte@^6.1.0: rollup-plugin-svelte@^6.1.1:
version "6.1.0" version "6.1.1"
resolved "https://registry.npmjs.org/rollup-plugin-svelte/-/rollup-plugin-svelte-6.1.0.tgz#bba94a37796fac1f73528161e84cc4976df431e1" resolved "https://registry.npmjs.org/rollup-plugin-svelte/-/rollup-plugin-svelte-6.1.1.tgz#66362cf0500fb7a848283ebcf19d289a60ef0871"
integrity sha512-TX1nIZSD6ePiSdYIEfpkvR7lLnP1nsSycCVz+vXbm5d5kIe5WMldo6fwcL/T8KPjc42XDgLaRcS74BorpQvpiA== integrity sha512-ijnm0pH1ScrY4uxwaNXBpNVejVzpL2769hIEbAlnqNUWZrffLspu5/k9/l/Wsj3NrEHLQ6wCKGagVJonyfN7ow==
dependencies: dependencies:
require-relative "^0.8.7" require-relative "^0.8.7"
rollup-pluginutils "^2.8.2" rollup-pluginutils "^2.8.2"
@ -2313,10 +2313,10 @@ rollup-pluginutils@^2.8.2:
dependencies: dependencies:
estree-walker "^0.6.1" estree-walker "^0.6.1"
rollup@^2.32.1: rollup@^2.33.2, rollup@^2.33.3:
version "2.32.1" version "2.33.3"
resolved "https://registry.npmjs.org/rollup/-/rollup-2.32.1.tgz#625a92c54f5b4d28ada12d618641491d4dbb548c" resolved "https://registry.npmjs.org/rollup/-/rollup-2.33.3.tgz#ae72ce31f992b09a580072951bfea76e9df17342"
integrity sha512-Op2vWTpvK7t6/Qnm1TTh7VjEZZkN8RWgf0DHbkKzQBwNf748YhXbozHVefqpPp/Fuyk/PQPAnYsBxAEtlMvpUw== integrity sha512-RpayhPTe4Gu/uFGCmk7Gp5Z9Qic2VsqZ040G+KZZvsZYdcuWaJg678JeDJJvJeEQXminu24a2au+y92CUWVd+w==
optionalDependencies: optionalDependencies:
fsevents "~2.1.2" fsevents "~2.1.2"
@ -2728,19 +2728,23 @@ supports-color@^7.0.0, supports-color@^7.1.0:
dependencies: dependencies:
has-flag "^4.0.0" has-flag "^4.0.0"
sveld@^0.1.0-rc.0: sveld@^0.1.0-rc.5:
version "0.1.0-rc.0" version "0.1.0-rc.5"
resolved "https://registry.npmjs.org/sveld/-/sveld-0.1.0-rc.0.tgz#3296df459116984f299bdd50bc8745e3cd48e66a" resolved "https://registry.npmjs.org/sveld/-/sveld-0.1.0-rc.5.tgz#32d35b3d2b9f2aaed28202da0e5f5adf69b6f181"
integrity sha512-z4SkRD8cVCOlsdd7UTMDRuG2TNDRHSGN201Fok/aTPoT0PjuXI4lcUJqGbJdxX4KBebenj8ph7y/UV8G0FqA0A== integrity sha512-TJY0mYN8vUPiPL8GGNn//IS6WicUF+MEbKCNzM6oXojIp6RSyBnJyJQsjIGFmfs6x5GIac+Sz8CjIFgQ40BfJQ==
dependencies: dependencies:
"@rollup/plugin-node-resolve" "^10.0.0"
comment-parser "^0.7.6" comment-parser "^0.7.6"
fs-extra "^9.0.1" fs-extra "^9.0.1"
prettier "^2.1.2" prettier "^2.1.2"
rollup "^2.33.2"
rollup-plugin-svelte "^6.1.1"
svelte "^3.29.7"
svelte-check@^1.1.6: svelte-check@^1.1.14:
version "1.1.6" version "1.1.14"
resolved "https://registry.npmjs.org/svelte-check/-/svelte-check-1.1.6.tgz#705fea71a757511f47894cdfa1ffab6e5c5cab4d" resolved "https://registry.npmjs.org/svelte-check/-/svelte-check-1.1.14.tgz#e6d94607b8d2e2e8738fbef39fe2f540f09a12b7"
integrity sha512-9CTehTTy02B4b7hsSp/F0JO8LrI3hNAgXfBtQ2JkxbDSLqlMPM5d2wcMrSzws9QQg6clRfBnn44wx3h/XYWWmg== integrity sha512-Vx/Nfesn29sRTsc7DJ9bAoTWT+gA+6ZWSiC+G+FMjWac2NP0CpNXdD0tjVvlztZY7HZNxya6D/QyNtCGFC9K6Q==
dependencies: dependencies:
chalk "^4.0.0" chalk "^4.0.0"
chokidar "^3.4.1" chokidar "^3.4.1"
@ -2774,10 +2778,10 @@ svelte-preprocess@^4.0.0:
detect-indent "^6.0.0" detect-indent "^6.0.0"
strip-indent "^3.0.0" strip-indent "^3.0.0"
svelte@^3.29.4: svelte@^3.29.7:
version "3.29.4" version "3.29.7"
resolved "https://registry.npmjs.org/svelte/-/svelte-3.29.4.tgz#d0f80cb58109ef52963855c23496f7153bb2eb7e" resolved "https://registry.npmjs.org/svelte/-/svelte-3.29.7.tgz#e254eb2d0d609ce0fd60f052d444ac4a66d90f7d"
integrity sha512-oW0fGHlyFFMvzRtIvOs84b0fOc0gmZNQcL5Is3hxuTpvaYX3pfd8oHy4KnOvbq4Ca6SG6AHdRMk7OhApTo0NqA== integrity sha512-rx0g311kBODvEWUU01DFBUl3MJuJven04bvTVFUG/w0On/wuj0PajQY/QlXcJndFxG+W1s8iXKaB418tdHWc3A==
tar@^2.0.0: tar@^2.0.0:
version "2.2.2" version "2.2.2"