A convenience wrapper to use Carbon Design System with Fulcro 3.
Go to file
Daniel Ziltener 0931ea24a8 Updated dependencies 2020-07-24 20:29:32 +02:00
resources/public In the beginning there was darkness 2020-05-31 14:26:20 +02:00
src This should work now. 2020-05-31 16:20:50 +02:00
target This should work now. 2020-05-31 16:20:50 +02:00
.gitignore In the beginning there was darkness 2020-05-31 14:26:20 +02:00
README.adoc In the beginning there was darkness 2020-05-31 14:26:20 +02:00
deps.edn This should work now. 2020-05-31 16:20:50 +02:00
package-lock.json Updated dependencies 2020-07-24 20:29:32 +02:00
package.json Updated dependencies 2020-07-24 20:29:32 +02:00
pom.xml This should work now. 2020-05-31 16:20:50 +02:00
shadow-cljs.edn In the beginning there was darkness 2020-05-31 14:26:20 +02:00


: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