ben.carrasco/next-static-site
1
0
Fork 0
mirror of https://github.com/jambonz/next-static-site.git synced 2025-12-18 20:37:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

upgrade jambonz-ui

Browse Source
This commit is contained in:
kitajchuk
2022-08-05 12:24:13 -07:00
parent dd0c607a13
commit 8448c56190
10 changed files with 10480 additions and 4121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@@ -22,7 +22,7 @@
npm-debug.log*
yarn-debug.log*
yarn-error.log*
package-lock.json
yarn.lock
# local env files
.env*

4
.husky/pre-commit
View File

@@ -1,5 +1,5 @@
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
yarn lint-staged
yarn build
npx lint-staged
npm run build

34
markdown/docs/jambonz-ui/components.md
View File

@@ -1,10 +1,18 @@
# 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 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 itself is written in [TypeScript](https://www.typescriptlang.org/) so it supports jambonz apps also using TypeScript. Documentation on jambonz UI type definitions will be implemented as we go.
The component library is written in [TypeScript](https://www.typescriptlang.org/) so it supports
jambonz apps also using TypeScript. Documentation on jambonz UI type definitions will be implemented
as we go.
The component library requires that some JS peer dependencies are met in your jambonz app. These are likely the most common, however it's worth noting that you can also use the library with [preact](https://preactjs.com/). In fact, this site is a `Next.js` app using `preact/compat` in place of the `React` packages.
The component library requires that some JS peer dependencies are met in your jambonz app. These are
likely the most common, however it's worth noting that you can also use the library with [preact](https://preactjs.com/).
In fact, this site is a `Next.js` app using `preact/compat` in place of the `React` packages.
```json
"peerDependencies": {
@@ -84,7 +92,11 @@ function MyComponent() {
##### Notes on Button as Link (polymorphic)
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.
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).
@@ -126,11 +138,19 @@ function MyComponent() {
##### 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.
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.
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.
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 {

39
markdown/docs/jambonz-ui/fonts-and-icons.md
View File

@@ -1,6 +1,11 @@
# Fonts and icons
The point of the Jambonz UI library is for jambonz apps to be "on brand" and share a cohesive foundational design system. 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).
The point of the Jambonz UI library is for jambonz apps to be "on brand" and share a cohesive
foundational design system. 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:
@@ -15,9 +20,14 @@ The point of the Jambonz UI library is for jambonz apps to be "on brand" and sha
##### 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.
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
You can even support browser `preload` for the fonts which will optimize the performance even more since the UI library ships with `font-display: swap` already. In your HTML `<head>` you can add some variation of this depending on which fonts render above the fold.
You can even support browser `preload` for the fonts which will optimize the performance even more
since the UI library ships with `font-display: swap` already. In your HTML `<head>` you can add some
variation of this depending on which fonts render above the fold.
```html
<link rel="preload" href="/fonts/objectivity-medium-webfont.woff2" crossOrigin="anonymous" as="font" type="font/woff" />
@@ -29,7 +39,9 @@ You can even support browser `preload` for the fonts which will optimize the per
##### 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.
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
{
@@ -39,7 +51,11 @@ For this [Next.js](https://nextjs.org/) app you're on right now we do this with
}
```
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.
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.
Example of dev server config:
@@ -75,9 +91,18 @@ module.exports = {
##### 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.
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
ake 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).
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/">Prev: Getting started</a>

22
markdown/docs/jambonz-ui/index.md
View File

@@ -1,8 +1,17 @@
# Jambonz UI
A minimal, light-weight UI design system 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/).
A minimal, light-weight UI design system 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 [vite](https://vitejs.dev/) or [webpack](https://webpack.js.org/) 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/).
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:
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:
View on [bundlephobia](https://bundlephobia.com/package/jambonz-ui)
@@ -22,7 +31,14 @@ 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.
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.
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>&nbsp;</span>

39
markdown/docs/jambonz-ui/styles.md
View File

@@ -1,17 +1,26 @@
# Styles
Jambonz UI styles are provided a couple of ways. The raw source for the styles is [SASS](https://sass-lang.com/) so if you're also using SASS you have the beneficial ability to directly use either all the UI SASS or just the variables and mixins for use extending the UI kit in your jambonz app. If you use all the SASS you don't need to use the raw CSS anywhere in your app. The utilized SASS modules will compile into your final CSS output.
Jambonz UI styles are provided a couple of ways. The raw source for the styles is
[SASS](https://sass-lang.com/) so if you're also using SASS you have the beneficial
ability to directly use either all the UI SASS or just the variables and mixins for
use extending the UI kit in your jambonz app. If you use all the SASS you don't need
to use the raw CSS anywhere in your app. The utilized SASS modules 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`:
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:
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';
@@ -19,7 +28,9 @@ 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.
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 |
|--------------|-------------|
@@ -37,13 +48,15 @@ Most of the styles are utilized directly by the [components](/dacs/jambonz-ui/co
| `txt--teal` | Applies color as element `color` |
| `txt--red` | Applies color as element `color` |
| `txt--green` | Applies color as element `color` |
| `wrap` | Center contains content with a `max-width` and default left/right `padding` |
| `txt--grey` | Applies color as element `color` |
| `wrap` | Center contains content with default left/right `padding` |
| `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.
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">
@@ -57,7 +70,9 @@ That `i` class is pretty useful. Here's an example of how it's used on this site
##### Loading in SASS
As mentioned you can use 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 load the whole thing and not worry about managing another CSS import target anywhere in your frontend stack.
As mentioned you can use 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 load the whole
```scss
// This loads the entire SASS lib
@@ -74,12 +89,18 @@ As mentioned you can use either the whole kit or just the variables and mixins.
##### 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/jambonz-ui/tree/main/src/styles/_vars.scss).
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/jambonz-ui/tree/main/src/styles/_vars.scss). Every variable
is also exposed via CSS `:root` for use as [custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*)
in other CSS files or for access in JavaScript.
##### 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/jambonz-ui/tree/main/src/styles/_mixins.scss).
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/jambonz-ui/tree/main/src/styles/_mixins.scss).
<p class="flex">

10358
package-lock.json generated Normal file
View File

File diff suppressed because it is too large Load Diff

6
package.json
View File

@@ -24,7 +24,7 @@
],
"license": "MIT",
"dependencies": {
"jambonz-ui": "^0.0.8",
"jambonz-ui": "^0.0.10",
"nanoid": "^3.1.22",
"next": "^12.1.4",
"next-plugin-preact": "^3.0.6",
@@ -54,7 +54,7 @@
"yamljs": "^0.3.0"
},
"lint-staged": {
"src/**/*.js": "yarn lint",
"pages/**/*.js": "yarn lint"
"src/**/*.js": "npm run lint",
"pages/**/*.js": "npm run lint"
}
}

8
src/styles/_layout.scss
View File

@@ -4,6 +4,14 @@
@use 'jambonz-ui/src/styles/vars' as ui-vars;
@use 'jambonz-ui/src/styles/mixins' as ui-mixins;
/******************************************************************************
* Extend jambonz-ui classes
*******************************************************************************/
.wrap {
max-width: calc(#{ui-vars.$width-laptop} + #{ui-vars.$width-padding} * 2);
margin: 0 auto;
}
/******************************************************************************
* Above the fold
*******************************************************************************/

4089
yarn.lock
View File

File diff suppressed because it is too large Load Diff