mirror of
https://github.com/jambonz/next-static-site.git
synced 2026-11-02 01:24:39 +00:00
Initial refactor of jambonz-ui package library (#39)
* Initial refactor of jambonz-ui package library * Delete public/fonts directory * Jambonz UI test-app and some refinements * next lint * working on jambonz ui docs * Update package.json * Update package.json * Update package.json * Create package.json * typescript * Update components.tsx * Update components.tsx * Update utils.ts * Update icons.ts * Update components.tsx * Update components.tsx * Update icons.ts * Update components.tsx * Update _icons.scss * Update components.tsx * Update components.tsx * fix some thangs and compile all * wrap up the docs * Update tsconfig.json * icons refactor * refine docs * update readmes * update readme * fix props interfaces and test in TS app * Update components.tsx * button up some things * change package name... * include readme in pkg dist * use published package
This commit is contained in:
Brandon Lee Kitajchuk authored and GitHub committed
1 parent
e783a1d6a3
commit
e3cd0edeb6
61 files changed
+1613
-2112
No files matched your search
@@ -0,0 +1,162 @@
|
||||
# Components
|
||||
|
||||
The UI library would not be complete without some atomic components for use in your jambonz apps. Currently there are components for normalized typography, iconography and buttons. As jambonz frontend development continues to mature new use cases will become viable candidates to incorporate into this UI kit—form elements being the most notable upcoming candidates. To see all the components in action, visually in one place you can go [here](/jambonz-ui/).
|
||||
|
||||
The component library requires that some JS peer dependencies are met in your jambonz app. The component library itself is also written in [TypeScript](https://www.typescriptlang.org/) so it supports jambonz apps also using TypeScript.
|
||||
|
||||
```json
|
||||
"peerDependencies": {
|
||||
"react": ">=18.2.0",
|
||||
"react-dom": ">=18.2.0",
|
||||
"react-feather": ">=2.0.9"
|
||||
}
|
||||
```
|
||||
|
||||
##### Using components
|
||||
|
||||
You can import available components from the package into your jambonz app JS.
|
||||
|
||||
```jsx
|
||||
import { ButtonGroup, Button, Icon } from 'jambonz-ui';
|
||||
|
||||
function MyComponent() {
|
||||
return (
|
||||
<ButtonGroup className="pad">
|
||||
<Button mainStyle="pill">
|
||||
<Icons.GitHub />
|
||||
<span>github.com/jambonz</span>
|
||||
</Button>
|
||||
<Button mainStyle="pill">
|
||||
<Icons.GitHub />
|
||||
<span>github.com/drachtio</span>
|
||||
</Button>
|
||||
</ButtonGroup>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
##### Button with Link
|
||||
|
||||
The `Button` component takes a few props that are specific to rendering a link element, `<a>`, with button styles. If you just need a button, you can ignore these props. But if you would like links to be styled like buttons (CTAs) and you want them to route within the [React](https://reactjs.org/) context you can do that. The distinction between which one has to do with passing either the `to` or the `href` props that are passed on to the `Link` component in question.
|
||||
|
||||
Using the `Link` prop with [react-router-dom](https://reactrouter.com/docs/en/v6/components/link).
|
||||
|
||||
```jsx
|
||||
import { Link } from 'react-router-dom';
|
||||
import { Button } from 'jambonz-ui';
|
||||
|
||||
function MyComponent() {
|
||||
return (
|
||||
<Button
|
||||
as={Link}
|
||||
to="/someurl/"
|
||||
subStyle="dark">
|
||||
Some text
|
||||
</Button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
Using the `Link` prop with [next/link](https://nextjs.org/docs/api-reference/next/link) for [Next.js](https://nextjs.org/).
|
||||
|
||||
```jsx
|
||||
import Link from 'next/link';
|
||||
import { Button } from 'jambonz-ui';
|
||||
|
||||
function MyComponent() {
|
||||
return (
|
||||
<Button
|
||||
as={Link}
|
||||
href="/someurl/"
|
||||
subStyle="dark">
|
||||
Some text
|
||||
</Button>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
##### Importing your icon set
|
||||
|
||||
By default the UI library doesn't import any icons from [feathericons](https://feathericons.com/), however it declares [react-feather](https://github.com/feathericons/react-feather) as a peer dependency. This means you can import just the icons you are using in your jambonz app. This allows for [tree-shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) to take effect and ensures we don't load extra bloat into our dist JS that isn't explicitly used. The `Icon` component renders a stylized design icon with many visual variations.
|
||||
|
||||
You can see how we import the feather icons used on this site [here](https://github.com/jambonz/next-static-site/blob/main/src/components/icons.js). But for a quick reference here is a compressed example.
|
||||
|
||||
First we create a module in our jambonz app and import the icons we would like to use and export them for use in the rest of the app.
|
||||
|
||||
```jsx
|
||||
import {
|
||||
X,
|
||||
Lock,
|
||||
Send,
|
||||
Menu,
|
||||
Phone,
|
||||
Heart,
|
||||
ExternalLink,
|
||||
// ...
|
||||
} from 'react-feather';
|
||||
|
||||
export const Icons = {
|
||||
X,
|
||||
Lock,
|
||||
Send,
|
||||
Menu,
|
||||
Phone,
|
||||
Heart,
|
||||
ExternalLink,
|
||||
// ...
|
||||
};
|
||||
|
||||
export default Icons;
|
||||
```
|
||||
|
||||
Then we can use these icons both `inline` and with the `Icon` component for stylized designer icons.
|
||||
|
||||
```jsx
|
||||
import { Icons, Heart } from './my-icons';
|
||||
import { Icon } from 'jambonz-ui';
|
||||
|
||||
function MyComponent() {
|
||||
return (
|
||||
<>
|
||||
<Icon mainStyle="pill" subStyle="dark">
|
||||
<Icons.Heart />
|
||||
</Icon>
|
||||
<Link href="https://www.behance.net/gallery/60530395/Objectivity-Free-Font-Family">
|
||||
<a className="i" target="_blank">
|
||||
<span>design</span>
|
||||
<Icons.ExternalLink />
|
||||
</a>
|
||||
</Link>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
###### Atomic components
|
||||
|
||||
| Component | Props |
|
||||
|-----------|-------|
|
||||
| Icon | `{ children, subStyle, mainStyle, ...rest }` |
|
||||
| IconGroup | `{ children, className, set }` |
|
||||
| Button | `{ children, to, href, as, subStyle, mainStyle, ...rest }` |
|
||||
| ButtonGroup | `{ children, className }` |
|
||||
|
||||
###### Typography components
|
||||
|
||||
| Component | Props |
|
||||
|-----------|-------|
|
||||
| H1 | `{ children, ...rest }` |
|
||||
| H2 | `{ children, ...rest }` |
|
||||
| H3 | `{ children, ...rest }` |
|
||||
| H4 | `{ children, ...rest }` |
|
||||
| H5 | `{ children, ...rest }` |
|
||||
| H6 | `{ children, ...rest }` |
|
||||
| P | `{ children, ...rest }` |
|
||||
| M | `{ children }` |
|
||||
| MS | `{ children }` |
|
||||
| MXS | `{ children }` |
|
||||
|
||||
<p class="flex">
|
||||
<a href="/docs/jambonz-ui/styles/">Prev: Styles</a>
|
||||
<span> </span>
|
||||
</p>
|
||||
@@ -0,0 +1,75 @@
|
||||
# Fonts and icons
|
||||
|
||||
The point of the Jambonz UI library is for jambonz apps to be "on brand" and share a cohesive foundational design DNA. With that in mind, the official font family for jambonz is called [Objectivity](https://www.behance.net/gallery/60530395/Objectivity-Free-Font-Family). Objectivity is a free, open-source font available for download online. The UI kit provides the font files already optimized for web use in the `woff` format. Jambonz doesn't utilize every member of the font family but you can view the full font specimen [here](https://www.fontsquirrel.com/fonts/objectivity).
|
||||
|
||||
##### Available fonts for web use:
|
||||
|
||||
| Font | File | SASS Variable |
|
||||
|------|------|---------------|
|
||||
| Objectivity Regular | `objectivity-regular-webfont.woff(2)` | `$font-regular` |
|
||||
| Objectivity Regular Slanted | `objectivity-regularslanted-webfont.woff(2)` | `$font-regular-italic` |
|
||||
| Objectivity Medium | `objectivity-medium-webfont.woff(2)` | `$font-medium` |
|
||||
| Objectivity Medium Slanted | `objectivity-mediumslanted-webfont.woff(2)` | `$font-medium-italic` |
|
||||
| Objectivity Bold | `objectivity-bold-webfont.woff(2)` | `$font-bold` |
|
||||
| Objectivity Bold Slanted | `objectivity-boldslanted-webfont.woff(2)` | `$font-bold-italic` |
|
||||
|
||||
##### Loading the fonts
|
||||
|
||||
Fonts can be copied from the package to your static public directory. This can be done manually, at installation time or during app bundling depending on your preference. The package provides a singular `public` directory that consists of all static assets: CSS, JS and fonts. You can literally just copy these assets into your jambonz applications static directory if you want to.
|
||||
|
||||
##### Examples
|
||||
|
||||
For this [Next.js](https://nextjs.org/) app you're on right now we do this with the `postinstall` script in the `package.json` file. We are also opting to ignore the `fonts` directory inside of `public` since the fonts are always copied during `install` which works locally and in CI.
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"postinstall": "rm -rf public/fonts && cp -R ./node_modules/jambonz-ui/public/fonts ./public/fonts"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Of course you can serve them statically in development and bundle them at build time if you're using a tool like [webpack](https://webpack.js.org/). See the documentation on [devServer](https://webpack.js.org/configuration/dev-server/#devserverstatic) and check out the [copy-webpack-plugin](https://www.npmjs.com/package/copy-webpack-plugin) for resources on how to handle this. Beyond this the expectation is that you have a good handle on how you can get the static fonts into your jambonz app.
|
||||
|
||||
Example of dev server config:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
// ...
|
||||
devServer: {
|
||||
static: [path.resolve(__dirname, 'node_modules/jambonz-ui/public')],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Example of copy plugin config:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
new CopyWebpackPlugin({
|
||||
patterns: [
|
||||
{
|
||||
from: path.resolve(__dirname, 'node_modules/jambonz-ui/public'),
|
||||
// If you would like to omit the CSS/JS and only copy fonts
|
||||
globOptions: {
|
||||
ignore: ['**/css/**', '**/js/**'],
|
||||
},
|
||||
},
|
||||
],
|
||||
}),
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
##### Feather icons
|
||||
|
||||
Jambonz UI utilizes [feathericons](https://feathericons.com/), an open-source icon library available in many formats for implemention into frontend stacks. Feather has 280+ available icons and the UI library is designed to work with [react-feather](https://github.com/feathericons/react-feather). By default the UI library doesn't import any icons from feather, however it declares `react-feather` as a peer dependency. This means you can import just the icons you are using in your jambonz app. This allows for [tree-shaking](https://developer.mozilla.org/en-US/docs/Glossary/Tree_shaking) to take effect and ensures we don't load extra bloat into our dist JS that isn't explicitly used. There is an [Icon component](/docs/jambonz-ui/components/) that renders a stylized design icon with many visual variations.
|
||||
|
||||
You can see how we import the feather icons used on this site [here](https://github.com/jambonz/next-static-site/blob/main/src/components/icons.js).
|
||||
|
||||
<p class="flex">
|
||||
<a href="/docs/jambonz-ui/getting-started/">Prev: Getting started</a>
|
||||
<a href="/docs/jambonz-ui/styles/">Next: Styles</a>
|
||||
</p>
|
||||
@@ -0,0 +1,30 @@
|
||||
# Jambonz UI
|
||||
|
||||
The Jambonz UI library is a minimal, light-weight UI design package for developing frontends for jambonz apps. It's a kit-of-parts including fonts, a small set of CSS styles, a source set of SASS styles and JavaScript components. Whether you're developing a custom dev stack with tools like [webpack](https://webpack.js.org/) or using a framework (like [vite](https://vitejs.dev/)) you should have no issues utilizing the resources available in the Jambonz UI library package. You can view the available UI elements from the library on this site [here](/jambonz-ui/). Also—this site is using the UI library!
|
||||
|
||||
What this is not is an overopinionated UI framework. Jambonz UI aims to provide foundational design materials like colors, fonts and typography as well as [atomic design](https://bradfrost.com/blog/post/atomic-web-design/) materials like buttons, icons etc. Currently the library is very lean but is expected to grow thoughtfully as jambonz frontend development continues to mature along this line of thinking.
|
||||
|
||||
A primary goal of the library is to have a small footprint. Current sizes:
|
||||
|
||||
| Output format | CSS size | JS size |
|
||||
|---------------|----------|---------|
|
||||
| Minified and Gzipped | `2 KB` | `614 bytes` |
|
||||
| Minified | `10 KB` | `2 KB` |
|
||||
| Compiled | `14 KB` | `4 KB` |
|
||||
|
||||
##### Installation
|
||||
|
||||
Installing the package is easy. You can use any typical package manager for frontend stacks.
|
||||
|
||||
```shell
|
||||
npm install jambonz-ui # or yarn add jambonz-ui
|
||||
```
|
||||
|
||||
##### General usage
|
||||
|
||||
The UI kit can be used in any typical way we pull things into our modern frontend stacks. You can import the CSS, SASS and JS directly into your specific target entry points for bundling or you can load them statically the good-old-fashioned way. For the latter the package provides a singular `public` directory that consists of all static assets: CSS, JS and fonts. You can literally just copy these assets into your jambonz applications static directory if you want to. This is also handy for serving extra static assets during development with tools like [webpack-dev-server](https://webpack.js.org/configuration/dev-server/) and also for copying just the raw static assets at build time when bundling.
|
||||
|
||||
<p class="flex">
|
||||
<span> </span>
|
||||
<a href="/docs/jambonz-ui/fonts-and-icons/">Next: Fonts and icons</a>
|
||||
</p>
|
||||
@@ -0,0 +1,83 @@
|
||||
# Styles
|
||||
|
||||
Jambonz UI styles are provided a couple of ways. The raw source for the styles is [SASS]() so if you're also using SASS you have the beneficial ability to directly import either all the UI SASS or just the variables and mixins for use extending the UI kit in your jambonz app. If you import all the SASS you don't need to use the raw CSS anywhere in your app. The imported SASS will compile into your final CSS output.
|
||||
|
||||
##### Loading the CSS
|
||||
|
||||
You can load the raw CSS directly into your app with a `<link>` tag if you prefer that method. It is provided compiled, minified and minified + gzipped. Assuming you've copied the CSS from the `public` directory provided with the package into your own static directory and renamed it `jambonz-ui.css`:
|
||||
|
||||
```html
|
||||
<!-- loading the minified CSS -->
|
||||
<link rel="stylesheet" href="/css/jambonz-ui.css" />
|
||||
```
|
||||
|
||||
You can also import the CSS directly into your jambonz app entry point (JS) as most bundlers support extraction for this file type:
|
||||
|
||||
```js
|
||||
import 'jambonz-ui/public/css/styles.css';
|
||||
```
|
||||
|
||||
##### Available CSS selectors
|
||||
|
||||
Most of the styles are utilized directly by the [components](/dacs/jambonz-ui/components/) so you're better off just using those. These are the basic utility styles that can be used in an ad-hoc manor in your jambonz apps.
|
||||
|
||||
| CSS selector | Application |
|
||||
|--------------|-------------|
|
||||
| `bg--jambonz` | Applies main brand color as element `background-color` |
|
||||
| `bg--black` | Applies color as element `background-color` |
|
||||
| `bg--charcoal` | Applies color as element `background-color` |
|
||||
| `bg--grey` | Applies color as element `background-color` |
|
||||
| `bg--pink` | Applies color as element `background-color` |
|
||||
| `bg--blue` | Applies color as element `background-color` |
|
||||
| `bg--purple` | Applies color as element `background-color` |
|
||||
| `bg--teal` | Applies color as element `background-color` |
|
||||
| `color--jambonz` | Applies main brand color as element `color` |
|
||||
| `color--blue` | Applies color as element `color` |
|
||||
| `color--purple` | Applies color as element `color` |
|
||||
| `color--teal` | Applies color as element `color` |
|
||||
| `wrap` | Center contains content with a `max-width` and default left/right `padding` |
|
||||
| `wrap-text` | Flex center justifies text—combine with a `max-width` |
|
||||
| `pad` | Applies normalized top/bottom `padding` |
|
||||
| `pad-b` | Applies normalized bottom `padding` |
|
||||
| `pad-t` | Applies normalized top `padding` |
|
||||
| `i` | Inline icon wrapper—normalizes display of `Icon` alongside text |
|
||||
|
||||
That `i` class is pretty useful. Here's an example of how it's used on this site to inline an icon with some text.
|
||||
|
||||
```jsx
|
||||
<Link href="https://www.behance.net/gallery/60530395/Objectivity-Free-Font-Family">
|
||||
<a className="i" target="_blank">
|
||||
<span>design</span>
|
||||
<Icons.ExternalLink />
|
||||
</a>
|
||||
</Link>
|
||||
```
|
||||
|
||||
|
||||
##### Loading in SASS
|
||||
|
||||
As mentioned you can import either the whole kit or just the variables and mixins. If you're already using SASS for your jambonz app the recommendation would be to just import the whole thing and not worry about managing another CSS import target anywhere in your frontend stack.
|
||||
|
||||
```scss
|
||||
// This imports the entire SASS lib
|
||||
@import 'jambonz-ui/src/styles/index.scss';
|
||||
|
||||
// This imports just the mixins and variables
|
||||
@import 'jambonz-ui/src/styles/_vars.scss';
|
||||
@import 'jambonz-ui/src/styles/_mixins.scss';
|
||||
```
|
||||
|
||||
##### Available SASS variables
|
||||
|
||||
A more comprehensive table of available variables here is coming soon. For now the easiest place to visualize this is in the source file for the variables [here](https://github.com/jambonz/next-static-site/tree/main/jambonz-ui/src/styles/_vars.scss).
|
||||
|
||||
|
||||
##### Available SASS mixins
|
||||
|
||||
A more comprehensive table of available mixins here is coming soon. For now the easiest place to visualize this is in the source file for the mixins [here](https://github.com/jambonz/next-static-site/tree/main/jambonz-ui/src/styles/_mixins.scss).
|
||||
|
||||
|
||||
<p class="flex">
|
||||
<a href="/docs/jambonz-ui/icons/">Prev: Icons</a>
|
||||
<a href="/docs/jambonz-ui/components/">Next: Components</a>
|
||||
</p>
|
||||
Reference in new issue
Block a user