A convenience wrapper to use Carbon Design System with Fulcro 3.
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Daniel Ziltener 0931ea24a8 Updated dependencies 3 years ago
resources/public In the beginning there was darkness 3 years ago
src This should work now. 3 years ago
target This should work now. 3 years ago
.gitignore In the beginning there was darkness 3 years ago
README.adoc In the beginning there was darkness 3 years ago
deps.edn This should work now. 3 years ago
package-lock.json Updated dependencies 3 years ago
package.json Updated dependencies 3 years ago
pom.xml This should work now. 3 years ago
shadow-cljs.edn In the beginning there was darkness 3 years ago


:toc-placement: preamble
:toc-levels: 2

= Fulcro 3 Carbon Wrappers

Fulcro 3 convenience wrappers for using https://react.carbondesignsystem.com[Carbon Design System] components.

This library offers improved integration with the carbon design system packages with predefined
factories and doc strings generated directly from the Carbon source. It also includes symbols for
all icon names.

NOTE: This library requires that you use Fulcro 3 and Shadow CLJS as the compiler.


== Usage

Shadow-cljs has much better integration with the NPM ecosystem, which allows you to
easily upgrade your carbon dependency without worrying about cljsjs, and also
allows you to easily use individual components for a smaller build size. Simply add
the carbon components to your `package.json`:

$ npm install --save-dev carbon-components-react carbon-components carbon-icons

=== Using Components

Individual factories can be found in namespaces that mirror the carbon-react module structure:

e.g. `Grid > Row` is available as
(:require [ch.lyrion.carbon.grid.ui-row :refer [ui-row]])

and `Accordion > Accordion` is available as
(:require [ch.lyrion.carbon.accordion.ui-accordion :refer [ui-accordion]])

While this is a bit tedious in the requires, it ensures that you don't get components in your
build that you don't use.

== Porting from Carbon React Documentation Examples

Props are required. The factories will convert them to js for you, but if you want every ounce of
possible speed you can pre-tag your props with `#js`.

React Version:
  onClick={function noRefCheck(){}}
    <a href="/#">
      Breadcrumb 1
  <BreadcrumbItem href="#">
    Breadcrumb 2
    Breadcrumb 3

This library:

{:className "some-class"
 :noTrailingSlash true
 :onClick (fn [] nil)
 :children [
      (dom/a {:href "/#"} "Breadcrumb 1"))
      "Breadcrumb 2")
      {:aria-current "page"
       :href "#"}
      "Breadcrumb 3")

== Examples

You can see some example usage in the workspaces of this repository. To play with them live
clone this repo, and start the compiler:

cd carbon-wrapper
npm install
npx shadow-cljs server
Navigate to http://localhost:9000 and start the workspaces build

Then navigate to http://localhost:8023

== Regenerating Factories

The factory files are generated from a checkout of the (https://github.com/carbon-design-system/carbon)[Carbon]
source (to automatically get the docstrings). The `user` namespace can be run in a normal Clojure REPL, and
contains the function to generate the files.

First clone the semantic-ui-react repo:
git clone https://github.com/carbon-design-system/carbon

In the cloned repository, run:
yarn install
yarn build

Then using the path to the generated packages/react/build/docgen/components folder, start a repl and run
(gen-factories "path/to/generated/docgen/components")


Copyright 2020 Daniel Ziltener

MIT Public License