Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve single-component usage #195

Open
4 of 5 tasks
sapegin opened this issue Oct 12, 2016 · 16 comments
Open
4 of 5 tasks

Improve single-component usage #195

sapegin opened this issue Oct 12, 2016 · 16 comments
Labels
enhancement good first issue Good for newcomers help wanted

Comments

@sapegin
Copy link
Member

sapegin commented Oct 12, 2016 •
edited
Loading

React Styleguidist could be awesome for documenting components, like this, but now it’s not.

  • New option to disable sidebar.
  • New option, getComponentName(), to change the title. @visibleName JSDoc tag — Add custom component display names #933
  • “Fork me” ribbon with customisable URL.
  • New option to hide isolated link (needs discussion).
  • Hide path line if it’s empty.

Anything else? Any feedback?
@sapegin sapegin added this to the 4.2.0 milestone Nov 1, 2016
@sapegin sapegin added the good first issue Good for newcomers label Jun 7, 2017
@sapegin sapegin removed this from the 4.2.0 milestone Jun 26, 2017
@natearn
Copy link
Contributor

natearn commented Jul 25, 2017

Is this change still desired? I'd like to contribute and I'm looking for an easy place to start.

@sapegin
Copy link
Member Author

sapegin commented Jul 25, 2017

@natearn Yes, please do it! Feel free to ping me on Gitter if you have any questions ;-)

@natearn natearn mentioned this issue Aug 1, 2017
Merged
@snmslavk
Copy link
Contributor

@sapegin Hi, where do you want to add this "fork me" ribbon?

Hide path line if it’s empty.

I think it's done, could we make this checkbox checked?

@sapegin
Copy link
Member Author

sapegin commented Aug 30, 2017

@snmslavk I think a new option in style guide config would work:

ribbon: {
  url: 'http://example.com/',
  text: 'Fork me on GitHub', // Default if the ribbon option passed
  color: '#fff', // Default if the ribbon option passed
  background: '#24292e' // Default if the ribbon option passed
}

You can use this CSS as a starting point:

https://github.com/sapegin/social-likes-next/blob/7018e8d51c05853eb04b437d8fce7bc0a34a663e/gh-pages/gh-pages.styl#L97-L123

image 2017-08-30 at 2 31 34 pm

@wkwiatek wkwiatek mentioned this issue Oct 19, 2017
Closed
@M-ZubairAhmed
Copy link

@sapegin are all tasks done? if not i would like to pick one

@sapegin
Copy link
Member Author

sapegin commented Nov 16, 2017

@M-ZubairAhmed Only checked ones are done. And there’s an abandoned PR for the ribbon.

@kizu
Copy link

kizu commented Nov 18, 2017

What I would love to have is to have some way to configure example both per example (maybe in a way the static keyword is done? i.e. in the first line after the language), and per section (so we could have one style of example in one part of docs, and another — at another).

Things I would like to configure:

  1. The default state of the example: if the code is visible or folded. Right now we can control this option only globally.
  2. To have some layouts to choose from: the current one, with full-width code, the side-by-side (see how it looks like there: http://kizu.ru/bemto-components/#html-structure), or in some other way.
  3. I'd like to have a way to demonstrate generated code for the example in some way, like, the HTML you'd see in the browser's devtools.
  4. I would like to not wrap multiple components with a wrapper all the time: when you need some items, it is kinda frustrating to have those empty <div>s.

@sapegin
Copy link
Member Author

sapegin commented Nov 18, 2017

  1. You can do it with showCode modifier, or { "showCode": false }.

  2. Any ideas on the API?

  3. That’s for plugins ;-)

  4. It would be very hard to get rid or them, if possible. What’s the issue here?

@kizu
Copy link

kizu commented Nov 20, 2017

  1. Was that mentioned somewhere in the docs? If so, I have completely missed it :) Also, are all of the options that are available for configuration in styleguid.config.js could be used this way or just a subset?

  2. Hmm, I'd need to think more about it, but it would be nice to have a way to register the different layout components as an object with different keys probably? And then use them as value of a new layout option?

  3. Proooobably, yeah.

  4. Just minor annoyance that when you need to have side-by-side comparison of two components in one example, right now we need to use that <div></div> that would be there in the CODE. What are the difficulties there? I think React allows to return arrays of components, and if you'd write an example like this:

    [
  <strong>aaa</strong>,
  <em>bbb</em>
]

    If would render it without problem. So maybe there'd be a way to either wrap examples that return multiple components in arrays? As they don't work already, I don't think it would break anything if some of the examples that throw error now would actually render sometimes :)

@sapegin sapegin mentioned this issue Nov 20, 2017
Closed
@sapegin
Copy link
Member Author

sapegin commented Nov 20, 2017

  1. Looks like no :-( Would be nice to fix that.

  2. Yeah, something like that may work, we need to try something. Maybe something similar to CSS Grids? Not sure will be easy to use or implement ;-)

  3. I’m going to release the very first draft to 6.1.0. It will be almost useless, but you’ll be able to try and tell me what’s missed ;-)

  4. Do you mean a div that you have to use in examples to wrap multiple components or divs that Styleguidist adds around your examples (there are two or three of them)? If you mean the former than we can fix that but we’ll have to think about backward compatibility with React 15 because returning arrays is a new feature of React 16.

@catherinefromont
Copy link

Hi there, I would love to try and fix this issue, how did everyone else go about fixing it?

@sapegin
Copy link
Member Author

sapegin commented Feb 21, 2018

@catherinefromont That’s awesome! But I’m not sure what exactly are you asking. Do you have question about specific task?

@sapegin sapegin mentioned this issue Feb 21, 2018
Open
@glebez glebez mentioned this issue Mar 6, 2018
Merged
@glebez
Copy link
Contributor

glebez commented Mar 18, 2018

Hey, I wanna try to go on with this issue. Can you explain a little more on the "New option, getComponentName(), to change the title." part? What is the general idea behind it? Or if that has already been discussed somewhere, be so kind to point me in that direction. Thanks!

@sapegin
Copy link
Member Author

sapegin commented Mar 19, 2018

@glebez The general idea is to be able to show anything instead of an actual component name in the style guide UI. I think #868 could be the first step, and the we'll need to split displayName into two properties: actual component name, and name visible in the UI. So probably we don't need a separate option for that, but we'll still need to do some refactoring.

sapegin pushed a commit that referenced this issue Mar 21, 2018
@glebez @sapegin
Feat: 'Fork me' ribbon (#861)
5eaae36 
Part of #195, closes #647.
sapegin pushed a commit that referenced this issue Mar 22, 2018
Changelog: 🚀
a5cd8f4 
👋 **[Support Styleguidist](https://opencollective.com/styleguidist) on Open Collective** 👋

## New features

### Page per section 🚧

This is a huge improvement for large style guides: now you can show only one component at a page instead of all components.

![](https://d3vv6lp55qjaqc.cloudfront.net/items/0W2q2K2s3n2k311O1J0y/Screen%20Recording%202018-03-22%20at%2010.06%20AM.gif)

To enable:

```js
module.exports = {
  pagePerSection: true
};
```

This is an experimental feature and we need your feedback to make it better and really useful. For example, right now there’s no isolated mode. So feel free to share your ideas [in issues](https://github.com/styleguidist/react-styleguidist/issues).

(#835 by @bitionaire and @stepancar, closes #494 and #768)

### “Fork me” ribbon

One more step to make Styleguidist usable for documenting open source projects:

![](https://d3vv6lp55qjaqc.cloudfront.net/items/1t331n2a3v0F2i290K0Z/Image%202018-03-22%20at%209.13.11%20AM.png)

New config option to enable the ribbon, define the URL and change the label:

```js
module.exports = {
  ribbon: {
    url: 'http://example.com/',
    text: 'Fork me on GitHub'
  }
};
```

And two new [theme variables](https://github.com/styleguidist/react-styleguidist/blob/master/src/styles/theme.js) to change colors: `color.ribbonBackground` and `color.ribbonText`.

(#861 by @glebez and @wkwiatek, part of #195, closes #647)

### Options to change CLI output on server start and build

Two new options, `printServerInstructions` and `printBuildInstructions`:

```js
module.exports = {
  printBuildInstructions(config) {
    console.log(
      `Style guide published to ${
        config.styleguideDir
      }. Something else interesting.`
    );
  }
};
```

(#878 by @roblevintennis, closes #876)

### Option to modify props

A new option, `updateDocs` to modify props before rendering. For example, you can load a component version number from a JSON file:

```js
module.exports = {
  updateDocs(docs) {
    if (docs.doclets.version) {
      const versionFilePath = path.resolve(
        path.dirname(file),
        docs.doclets.version
      );
      const version = require(versionFilePath).version;

      docs.doclets.version = version;
      docs.tags.version[0].description = version;
    }

    return docs;
  }
};
```

(#868 by @ryanoglesby08)

### Limited support for named exports

Styleguidist used to require default exports for components. Now you can use named exports too, though Styleguidist still supports only one component per file. I hope this change will make some users happier, see more details [in the docs](https://react-styleguidist.js.org/docs/components.html#loading-and-exposing-components).

(#825 by @marcdavi-es, closes #820 and #633)

### Allow arrays of component paths in sections

More flexibility in structuring your style guide:

```js
module.exports = {
  sections: [
    {
      name: 'Forms',
      components: [
        'lib/components/ui/Button.js',
        'lib/components/ui/Input.js'
      ]
    }
  ]
};
```

(#794 by @glebez, closes #774)

### Sort properties by `required` and `name` attributes

This change should make props tables more predictable for the users. Instead of relying on developers to sort props in a meaningful way, Styleguidist will show required props first, and sort props in each group alphabetically.

To disable sorting, use the identity function:

```javascript
module.exports = {
  sortProps: props => props
};
```

(#784 by @dotcs)

## Bug fixes

* Allow `Immutable` state in examples (#870 by @nicoffee, closes #864)
* Change template container ID to prevent clashes (#859 by @glebez, closes #753)
* Better props definitions with Flow types (#781 by @nanot1m)
@glebez glebez mentioned this issue Apr 10, 2018
Merged
@Dishantydv7
Copy link

Dishantydv7 commented Jun 8, 2024 •
edited
Loading

@sapegin Hey are all the issues resolved , If that's not the case , i would love to work on some

@john310897
Copy link

Hey i would like contribute, any issues which are easy and i can start on?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement good first issue Good for newcomers help wanted
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
10 participants
@sapegin @kizu @natearn @tizmagik @snmslavk @glebez @M-ZubairAhmed @catherinefromont @john310897 @Dishantydv7