README.md in lookbook-2.3.4 vs README.md in lookbook-3.0.0.alpha.0
- old
+ new
@@ -1,84 +1,361 @@
-<div align="center">
-<br>
-<p><a href="https://lookbook.build"><img src=".github/assets/lookbook_logo.svg" width="240"></a></p>
+<img src=".github/assets/lookbook_logo.svg" width="240">
-<p>A UI development environment for Ruby on Rails applications.</p>
+<hr>
-<p><strong><a href="https://lookbook.build">Documentation</a> | <a href="http://demo.lookbook.build/lookbook">Demo site</a></strong></p>
+## Lookbook v3.0 [development branch]
-<p><a href="https://rubygems.org/gems/lookbook"><img src="https://img.shields.io/gem/v/lookbook" alt="Gem version"></a>
-<a href="https://github.com/lookbook-hq/lookbook/actions/workflows/ci.yml"><img src="https://github.com/lookbook-hq/lookbook/actions/workflows/ci.yml/badge.svg" alt="CI status"></a></p>
+This branch contains a work-in-progress, exploratory, from-scratch rebuild of Lookbook, intended to form the basis of a future v3.0 release.
-</div>
+[Demo](#demo-site) ใป [Usage](#usage) ใป [Development](#development) ใป [Background & motivation](#v3-rebuild---background-and-motivation) ใป [Current status](#v3-rebuild---current-status)
----
+
-<div align="center">
-Lookbook combines a powerful <strong>component browser</strong> and <strong>preview system</strong> with an <strong>integrated documentation engine</strong> to help teams build robust, modular, maintainable user interfaces.<br><br>
-It's compatible with <a href="https://viewcomponent.org/">ViewComponent</a>, <a href="https://www.phlex.fun/">Phlex</a>, ActionView partials and more.
-<br><br>
-<a href="https://lookbook.build"><strong>Read the docs →</strong></a>
+## Demo site
-</div>
+You can find a hosted version of the [demo/test app](#demo-app) here: https://v3-demo-app.lookbook.build/lookbook
+This pulls directly from the `v3` development branch and so may occasionally be broken.
----
+## Usage
-[](http://lookbook.build/)
+Lookbook v3 is currently under heavy development and **should not be considered stable**.
+However, intrepid individuals who are familiar with Lookbook and wish to kick the tyres or get a preview of the upcoming changes can install the Lookbook gem directly from the `v3` branch of this repository.
+
+> Alternatively you can pull down the codebase and [run the included demo app](#demo-app) to see some of the new features in action.
+
+### Requirements
+
+* Ruby >= 3.0.0
+* Rails >= 6.1.0
+
+### Installation
+
+Add Lookbook to the `development` group in your Gemfile:
+
+```rb
+group :development do
+ gem "lookbook", github: "lookbook-hq/lookbook", branch: "v3"
+ gem "listen" # Required for 'live' UI updates when file changes are detected
+end
+```
+
+Lookbook will automatically be mounted at `/lookbook` within your app when the server is started.
+
+> ๐จ Previously Lookbook required manual mounting in your app. This is **no longer the case**, so if trialing v3 in a project with an existing Lookbook install you must remove [the mounting code](https://lookbook.build/guide/installation#step-2) from your routes.rb file first.
+
+### Configuration
+
+The currently implemented v3 configuration options are not yet documented, but can be seen in the [config.rb](lib/lookbook/config.rb) file.
+
+> ๐จ If testing out the v3 branch on an existing Lookbook install you may see errors if setting v2.x config options that have not yet been re-implemented in v3.
+
+### Breaking changes
+
+Lookbook v3.0 will contain a number of breaking changes from the v2.x releases.
+
+The majority of these changes will be in the _extending_, _theming_ and _API_ areas, so heavily customised Lookbook installations may find upgrading a more involved process. As yet there is no documentation on the exact scope of these changes.
+
+In addition, until v3 development reaches beta release stage there are likely to be _unintentional breaking changes_ due to missing or partly-implemented features.
+
+For these reasons, it is recommended that anyone who wants to kick the tyres on the pre-alpha v3 codebase do so **on new projects** or **existing projects with simple, 'vanilla' Lookbook installs** to minimise the chance of running into issues.
+
+### Running in production
+
+ Please don't do this. It's really not ready yet.
+
## Development
-Lookbook is implemented as an isolated [Rails Engine](https://guides.rubyonrails.org/engines.html) and uses [ViewComponent](https://viewcomponent.org), [Tailwind](https://tailwindcss.com/) and [Alpine](https://alpinejs.dev/) for its UI.
+### Demo app
-This repository contains:
+The Lookbook v3 codebase includes a runnable dummy/demo app for development and testing purposes.
-* The Lookbook source code ([`/app`](https://github.com/lookbook-hq/lookbook/tree/main/app), [`/lib`](https://github.com/lookbook-hq/lookbook/tree/main/lib), [`/config`](https://github.com/lookbook-hq/lookbook/tree/main/config), etc)
-* The Lookbook [documentation site](#docs-site) source code and content ([`/docs`](https://github.com/lookbook-hq/lookbook/tree/main/docs)).
-* A [test suite](#testing) with a 'runable' dummy app ([`/spec`](https://github.com/lookbook-hq/lookbook/tree/main/spec)).
+To run the app, clone the contents of the `v3` branch to your machine and then run the following commands from within the root directory:
+```
+bundle install
+npm install
+bin/dev
+```
+
+Visit http://localhost:4444/lookbook to view the Lookbook UI.
+
+> In development mode assets will be rebuilt as changes are made but there is not yet any asset live-reloading in place.
+
+### Testing
+
+Run the tests:
+
+```
+bin/test
+```
+
+> Integration tests run against the demo app.
+
### Documentation site
-The [Lookbook docs site](https://lookbook.build) is built using [Bridgetown](https://www.bridgetownrb.com/) and the source files can be found in the `./docs` directory.
+Run the docs site locally in dev mode:
-To preview changes locally you can run a development version of the docs site:
+```
+bin/docs
+```
-1. Clone this repo
-2. Install dependencies: `bundle install`
-3. Start the app: `bin/docs`
-4. Visit http://localhost:4000
+Visit http://localhost:4000 to view the docs. Not much to see there at the moment!
-### Testing
+### Logging and debugging
-Lookbook uses [RSpec](https://relishapp.com/rspec) for testing.
+`Lookbook` logs its activity to `Lookbook.logger`.
+This is the primary method of debugging.
-Tests can be run using the `rake spec` or `bundle exec rspec` commands.
+#### Custom logger
-The dummy app that the tests are being run against can be viewed by running the `bin/dummy` command and then browsing to http://localhost:9292/lookbook
+You can call `Lookbook.logger =` to set a custom `Lookbook` logger for the process. For example:
-### Releases
+```rb
+Lookbook.logger = Rails.logger
+```
-Lookbook uses [Release It!](https://github.com/release-it/release-it) to automate the release process.
+#### Default logger
-Running `npm run release` will start the process of publishing a new release and walks though all the steps from picking a version number to publishing the updated gem.
+If no custom logger is set, a default `Lookbook` logger which logs to to `STDERR` will be created and assigned to `Lookbook.logger`.
-Publishing a release requires write permissions for this repository (lookbook-hq/lookbook) and 2FA publish permissions for Lookbook on RubyGems.
+The default logger defaults to the `error` logging level (severity).
+You can override the logging level by setting the environment variable `LOOKBOOK_LOG_LEVEL=<level>`.
+For `<level>`, all standard `::Logger` levels are supported, with any mix of upper-/lower-case:
-## Contributing
+```bash
+export LOOKBOOK_LOG_LEVEL=debug
+export LOOKBOOK_LOG_LEVEL=info
+export LOOKBOOK_LOG_LEVEL=warn
+export LOOKBOOK_LOG_LEVEL=fatal
+export LOOKBOOK_LOG_LEVEL=error
+```
-Lookbook is an un-funded open source project and contributions of all types and sizes are most welcome!
+The default of `error` will be used if an unsupported value is set.
-Please take the time to read over the [Contributing](./CONTRIBUTING.md) guide before making your first contribution and if anything isn't clear then [start a discussion](https://github.com/lookbook-hq/lookbook/discussions) and we will do our best to help you out.
+#### Disabling logging
-## Contributors
+If you want to disable `Lookbook` logging, set
-Lookbook was created by [Mark Perkins](https://github.com/allmarkedup) and continues to grow
-& improve thanks to the ideas, suggestions and hard work of all of [these excellent humans](https://github.com/lookbook-hq/lookbook/graphs/contributors):
-<br>
-<br>
-<a href="https://github.com/lookbook-hq/lookbook/graphs/contributors">
- <img src="https://contrib.rocks/image?repo=lookbook-hq/lookbook&columns=14" width="800" />
-</a>
+```rb
+Lookbook.logger = ::Logger.new('/dev/null')
+```
+
+## v3 rebuild - background and motivation
+
+The current Lookbook codebase has grown organically and haphazardly from a few custom ViewComponent preview templates into a standalone Rails Engine gem with support for previewing many different types of components and views.
+
+In order to provide a solid foundation for future development this v3 branch was created with aspirations to improve the quality of the Lookbook codebase, reduce the number of third party dependencies, fix long-standing issues that are hard to address in the current implementation
+and explore building out new (and experimental) feature ideas.
+
+More concretely, a number of **key goals** are helping shape the development work:
+
+#### UI
+
+* Improve accessibilty and usability of the app (#17)
+* Expose a better theming system using CSS variables (with light and dark modes out of the box)
+* Replace ViewComponent dependency with bespoke component system for building the UI
+
+#### Previews
+
+* Add support for ActionMailer previews (#570)
+* Implement customisable preview overview/documentation pages
+* Fix compatability issues with partial/view template previews (#581, #555)
+* Improve handling and logging of parser errors (#593)
+
+#### Preview embeds
+
+* Add more granualar security configuration options for embed iframes (#571)
+* Implement `<lookbook-embed></lookbook-embed>` as a native web component
+
+#### Pages
+
+* Make it easier to customise the look and feel of pages
+* Expand set of UI and path helpers available in pages
+
+#### Development/Testing
+
+* Streamline Lookbook development process - runnable test/demo/development app, simpler asset dev/build pipeline
+* Improve test setup - switch to Minitest, run tests against demo app, better integration test coverage
+* Make logging play nicer with standard Rails logging options and third party gems
+
+#### Other
+
+* Remove ActionCable requirement, use SSE for live UI updates in dev
+* Improve error handling and compatability with `better_errors` etc (#528)
+* Remove some of the madness from codebase ๐
+
+## v3 rebuild - Current status
+
+Lookbook v3 is currently in a pre-alpha stage and is under active, exploratory development.
+
+The 'todo' list below is intended to provide a _very rough_ overview of the current state of progress. **It is not exhaustive**. Checked off items may still be revisited/refactored/removed in the future without warning.
+
+**Emoji key:**
+
+* ๐ - New feature in v3
+* ๐ง - In progress or implemented but incomplete
+* ๐งช - Experimental feature/implementation
+
+### UI
+
+#### General
+
+* [x] Basic desktop UI implementation
+* [x] Replace Tailwind with vanilla CSS
+* [x] Bespoke component system to replace ViewComponent
+* [x] Status bar ๐ ๐ง
+* [x] Notifications for parser errors
+* [x] SSE-based live UI updating ๐งช
+* [x] Expand nav to current item when opening app
+* [x] Don't fetch/render entire DOM on navigation (no need to re-render sidebar etc)
+* [ ] Improve accessibilty (exact requirements tbd)
+* [ ] Mobile/small screen layout optimisations
+* [ ] Side-dockable preview inspector drawer
+* [ ] Search fields 'clear' buttons
+* [ ] Use custom icon sprite instead of inlined icons
+
+#### Code samples
+
+* [x] Syntax highlighting ๐ ๐ง ๐งช
+* [ ] Replace Shiki with something lighter (server-side?)
+* [ ] Click to copy
+* [ ] Line wrap toggle
+
+#### Theming/branding
+
+* [x] Light/dark mode themes + toggle ๐ ๐ง
+* [x] Project links in header ๐
+* [ ] Theme system based on CSS custom properties ๐ง
+* [ ] Project logo customisation
+
+### Previews
+
+#### Preview types
+
+* [x] ViewComponent previews
+* [x] Phlex previews
+* [x] Partials/templates previews
+* [x] ActionMailer previews ๐ ๐งช
+
+#### Tags/annotations
+
+* [x] Notes
+* [x] `@label`
+* [x] `@hidden`
+* [x] `@param`
+* [x] `@display`
+* [x] `@!group ... @!endgroup`
+* [x] `@id` ๐
+* [x] `@priority` ๐
+* [x] `@location/@logical_path`
+* [ ] `@component/@renders`
+* [ ] `@source`
+* [ ] `@after_render`
+* [ ] `@status/@wip` ?
+
+#### Dynamic params
+
+* [x] Text input
+* [x] Textarea input
+* [x] Select input
+* [x] Checkbox input ๐
+* [ ] Toggle input
+* [ ] Color picker input
+* [ ] Range input
+
+#### Display options
+
+* [x] Static display options
+* [x] Dynamic display options
+
+#### Inspector
+
+* [x] Preview panel
+* [x] Output panel
+* [x] Usage panel (combination of old 'source' and 'notes' panels)
+* [x] Metadata panel ๐ง ๐ ๐งช
+* [x] Params panel ๐ง
+* [ ] Configurable breakpoints for quick preview viewport resizing
+* [ ] Embed code dropdown
+* [ ] Preview URL copy button
+* [ ] Manual preview refresh button
+
+#### Other
+
+* [x] Grouped scenarios
+* [x] Preview overview pages ๐ง ๐
+* [x] Custom preview controllers support
+* [x] Custom preview layouts support
+* [x] Preview parser error reporting
+* [x] Render previews in parent app context to fix path helper issues
+* [x] JSON endpoint
+* [x] ActionView annotation stripping
+* [ ] Option to specify order of preview directories in nav (i.e. non-alphabetical)
+* [ ] Output transformation
+
+### Preview Embeds
+
+* [x] `<lookbook-embed>` implemented as HTML custom element
+* [x] Internal embeds (within pages in Lookbook)
+* [ ] External embeds (outside of Lookbook)
+* [ ] Configurable frame ancestors
+
+### Pages
+
+* [x] Basic markdown + ERB pages system
+* [x] YAML Frontmatter config
+* [x] Landing page
+* [ ] Tabbed pages
+* [ ] Page layout and styling options ๐ง
+
+### Extending
+
+* [x] Custom inspector panels ๐ง
+* [ ] Custom param inputs
+* [ ] Custom tags
+* [ ] Lifecycle hooks
+* [ ] Global data store
+* [ ] Ruby API
+
+### Development
+
+* [x] Replace Parcel with PostCSS + esbuild for compiling assets
+* [x] Runnable, bundled demo app for development
+* [x] Minitest test suite setup
+* [x] Setup GH actions CI
+* [ ] Comprehensive set of test components + previews ๐ง
+* [ ] UI integration tests ๐ง
+* [ ] Set up Ruby & Rails versions test matrix via Appraisal
+* [ ] Release script (automate from GH?)
+
+### Internals
+
+* [x] Auto-mounting of Lookbook engine ๐
+* [x] Remove ActionCable dependency, use SSE for triggering UI live updates ๐ ๐งช
+* [x] File change detection system
+* [x] Config options defined in Ruby and not YAML
+* [x] Config options synced with ViewComponent where appropriate
+* [x] UUID-based permalink endpoint ๐ ๐งช
+* [x] Improved logger implementation
+* [ ] Rationalise & document entity method names
+* [ ] Make debug logging more consitent
+* [ ] Improve parsing/tree building performance
+
+### Documentation
+
+* [ ] Switch to Nanoc for static docs building?
+* [ ] Document new features in v3
+* [ ] Port and update existing docs to new docs site
+* [ ] Automate config option documentation via YARD
+* [ ] Automate API docs via YARD
+* [ ] Set up automated build & deploy process for docs
+
+### Other/Ideas/Maybe
+
+* [ ] CLI tool
+* [ ] JSON API
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
\ No newline at end of file