mirror of
https://github.com/discourse/discourse.git
synced 2026-08-05 21:57:36 +08:00
bdcc4f6c98Follow-up to #42100, which added the `?source=` bundler plugin and converted two examples as a proof. This converts the rest. The hand-written samples had drifted: components under names they no longer go by, import paths that moved to `discourse/ui-kit/*`, a `discourse/helpers/mut` module that has never existed, and one sample that was not valid gjs. Each example now lives in its own module under `examples/<group>/<section>/` and the section imports it twice, once as a component and once for its source, so a sample cannot disagree with what renders beside it. `plugins/styleguide/README.md` records the criteria for adding new ones.
68 lines
2.5 KiB
Markdown
Vendored
68 lines
2.5 KiB
Markdown
Vendored
# styleguide
|
|
|
|
Adds a URL of `/styleguide` to discourse that renders widgets in various
|
|
configurations to aid in styling.
|
|
|
|
|
|
|
|
## Code examples
|
|
|
|
Discourse's build pipeline allows adding `?source=file` or `?source=template` to
|
|
a module import. This provides a string of the raw source code for the entire
|
|
file, or just for the `<template>`. Put the example in its own module under
|
|
`examples/`, import it twice, and pass the string to `@code`:
|
|
|
|
```gjs
|
|
import StyleguideExample from "discourse/plugins/styleguide/discourse/components/styleguide-example";
|
|
import CharCounterExample from "../../examples/molecules/char-counter";
|
|
import charCounterSource from "../../examples/molecules/char-counter?source=file";
|
|
|
|
export default <template>
|
|
<StyleguideExample @title="<DCharCounter>" @code={{charCounterSource}}>
|
|
<CharCounterExample />
|
|
</StyleguideExample>
|
|
</template>
|
|
```
|
|
|
|
The import must resolve within the same plugin or theme bundle, and
|
|
`?source=template` requires the module to contain exactly one `<template>`.
|
|
|
|
### Criteria
|
|
|
|
Samples typed by hand drift from the code they describe. These rules keep that
|
|
from being possible.
|
|
|
|
1. Every `<StyleguideExample>` that passes `@code` passes a `?source=` import,
|
|
never a hand-written string.
|
|
|
|
2. Each example is its own module under `examples/`. A module may back several
|
|
examples when the variants differ only in the data passed in.
|
|
|
|
3. Use `?source=file` when the module has imports or JS, so the reader sees
|
|
what to paste into a new file. Use `?source=template` when it is pure markup.
|
|
|
|
4. The example module holds only the API being taught. Styleguide-only chrome
|
|
stays in the section file, wrapping the example.
|
|
|
|
5. An example receives only what it cannot build itself. Store-backed records
|
|
come in as named args; literal fixtures, state and callbacks the example
|
|
owns. Examples never take `@dummy` itself.
|
|
|
|
6. An example demonstrating a design token, a color or a type scale does not
|
|
need `@code` at all.
|
|
|
|
7. A hand-written `@code` string is admissible only when the sample cannot be a
|
|
module that renders on this page: it is computed from the page's live
|
|
controls, or the block is a gallery rather than a usage example. It must
|
|
carry a comment saying which.
|
|
|
|
### Layout
|
|
|
|
```
|
|
examples/<group>/<section>/<name>.gjs
|
|
```
|
|
|
|
`<group>` is `atoms`, `molecules` or `organisms`; `<section>` is the section
|
|
file name without its numeric prefix; `<name>` is a kebab-case slug for the
|
|
variant. Import with a relative specifier and no file extension, and name the
|
|
bindings `<Name>Example` and `<name>Source`.
|
