Ariadne ViewComponents

This repository contains View Components used by Yetto.app which we incorporate into a design system called Ariadne. We were frustrated by the lack of quality View Components which make use of TailwindCSS and Stimulus. So we contracted EvilMartians to build a system, which we then extracted.

These Ariadne view components are composed of several projects:

Our eternal gratitude to GitHub's design team for open sourcing Primer View Components; we were inspired by a lot of their development tooling and foundational work.

Installation

Like tailwindcss-rails, this gem also wraps the standalone executable version of the Tailwind CSS v3 framework. These executables are platform specific, so there are actually separate underlying gems per platform, but the correct gem will automatically be picked for your platform. Supported platforms are Linux x64, macOS arm64, macOS x64, and Windows x64. (Note that due to this setup, you must install the actual gems – you can't pin your gem to the GitHub repo.)

Using the gem

todo, lol

 <%= render(Ariadne::HeadingComponent.new(tag: :h1)) { "H1 Text" } %>

DEFAULT_TAG = :div
DEFAULT_CLASSES = "bg-yellow-400"
    def initialize(tag: DEFAULT_TAG, classes: "", attributes: {})
      @tag = check_incoming_tag(DEFAULT_TAG, tag)
      @classes = merge_class_names(DEFAULT_CLASSES, classes)
      @attributes = attributes
      @attributes[:id] = "myId"
    end

document schemes, fetch_or_raise, all that

@import '@ariadne/stylesheets/ariadne_view_components.css';

@import "tailwindcss/base";

@import "scrollbar.css";
@import "@ariadne/stylesheets/ariadne_view_components.css";

@tailwind components;
@tailwind utilities;

const ariadneAssetsPath = process.env.ARIADNE_ASSETS_PATH || "";

export default defineConfig({
  plugins: [
    # ...
  ],
  resolve: {
    alias: {
      "@ariadne": ariadneAssetsPath,
    },
  },
});

rearrange @tailwind base;

this resets styles applied by ariadne, which already resets styles!!

Helpers

Ariadne::ViewHelpers

Wrappers

render_if
with_tooltip

Style

use content when you want everything slurped up prefer renders_one :text etc to limit the type of data which can be entered

item means one click only option means one selection or one of many

use option for config stuff, not rendering

Incorporating Rubocop and other linters

This gem comes with some standard linters to keep your code fresh and consistent. Refer to the documentation for more information.

Getting started with development

So, you just cloned the repo, huh? Great. In addition to Ruby, install Overmind and Node/NPM. Then, run the following script to set up your local environment:

script/setup

This will install all the necessary dependencies, plus get you ready for viewing the components and generating the documentation.

If you then run script/server, this will build and run both the documentation site and launch Lookbook.

4000 lookbook 4100 vite

Adding new components

There is a generator set up to produce new components:

thor generate_view_component ComponentName [attribute] [attribute]

For example:

thor generate_view_component Profile name age

This creates a component called Ariadne::UI::Profile::Component, with two optional attributes (name and age). It also creates Lookbook preview files, tests, and factories.

See more details on this generator at rakelib/generators/view_component/USAGE.

Running tests

See the documentation on testing.

Generating Documentation and Lookbook

Run script/docs_doctocat_lookbook to get a build of the documentation running at localhost:5300. The documentation comes from the YARD comments, and all of the markdowns files in ./docs. The TOC navigation is defined in docs/src/@primer/gatsby-theme-doctocat/nav.yml, and new entries are created automatically for you after you run script/generate_component.

A Lookbook site is also running on localhost:4000. You can also choose to run Lookbook separately via the script/lookbook command.

For more information on writing documentation and presenting the components via Loobook, here's more information

Publishing a Release

To publish a release, you must have an account on rubygems and npmjs. Additionally, you must have been added as a maintainer to the project. Please verify that you have 2FA enabled on both accounts.

Once the changesets release PR has been approved and merged, run script/publish. This will build and publish the packages. You may be prompted to log into your rubygem and npm account.