This repository serves as a components library, its documentation, and a workshop. Storybook is able to provide both extensive documentation for the components by being able to pass in props to demonstrate high-level use cases, mocking data and events. It serves as workshop because you can see how the component looks with the dummy props and data alone through the web app it deploys.
This file demonstrates how to run the Storybook to see the components documentation and workshop, how to use the components library and some other software engineering considerations.
-
ES6 (the minimum recommended by the TSConfig Reference)
-
Corepack Enable to fix the error
This project's package.json defines "packageManager": "yarn@4.3.1npm install -g corepack corepack enable
We currently do not support apps being able to resolve to raw TypeScript instead of compiled JavaScript.
Run the commands below in the repository of your app to install this library.
The two main tags are latest and experimental. By default, latest will be
installed. You can install a different tag or version by postfixing
ikhlas-web-components with @<tag> and @<version> respectively. For
example, npm install ikhlas-web-components@experimental or yarn add ikhlas-web-components@0.0.0-exp-a-11. You can find all of our published
versions
here.
Using npm,
npm install ikhlas-web-componentsUsing pnpm,
pnpm install ikhlas-web-componentsUsing yarn,
yarn add ikhlas-web-componentsThis library relies on the CSS framework, Tailwind, to style its components. The
tailwind configurations are defined in tailwind.config.cjs, the raw tailwind
directives are defined in src/index.css, and the post-processed
style definitions are in dist/style.css.
This library exposes three files for styling: tailwind.config.cjs,
src/index.css and dist/style.css. The component definitions by themselves
have classes associated with them, which is a feature native to CSS for
defining groups of HTML elements that should have particular visual
properties. The library relies on the CSS framework, Tailwind, to provide and
create the definitions. The library comes with custom directives in
src/index.css, which Tailwind uses alongside the configurations defined in
tailwind.config.cjs in order to generate dist/style.css, the generated CSS
output with all the "Tailwind-ness" stripped away.
You may import the library's src/index.css or dist/style.css into your
project, with any appropriate means. For example, using @import in the main
css file of your project, direct CSS import, or link tag in HTML.
Why would one need src/index.css if dist/style.css is the same thing but the
generated CSS output? The generated dist/style.css may not contain all of the
directives in src/index.css because they may not be used in the component
definitions of the library and are shaken away by the post-processor. Thus, if
you would like to use the custom directives provided by this library for the
components in your own project, you will need to import src/index.css, and you
will need to have your project's own Tailwind post-processor process it.
If you only want to use the library's components but none of its directives, or
if you don't want to do any CSS post-processing in your project for this
library's components, you should just import from dist/style.css.
If you are importing from src/index.css and you are doing your own
post-processing, then you should not import from dist/style.css as it is at
best redundant, and at worst, creates conflicts.
By default, your project's Tailwind configuration knows nothing about this library's Tailwind configuration.
If you would like your project to have additional configurations on top of the
library's configuration, add the element
require('ikhlas-web-components/tailwind.config.js') to the presets field of
your project's tailwind configuration.
If you would like to override certain configuration of this library, you will need to read on how each specific configuration is merged and what it means to override the preset configuration here.
For more information on Tailwlind's presets, see their official
documentation.
If you would like to use your project's own tailwind post-processing to
interprete the tailwind styles, you need to have your own tailwind
configuration file, and in the content field of your configuration, have the
element "./node_modules/ikhlas-web-components/dist/*.js".
It is highly impractical not to use Tailwind to style the library's components, because you would have to manually provide the CSS style definitions for all of the tailwind styles used.
To use them, you will need to import from src/index.css. For their definitions,
go to src/index.css.
These are all aliases for the actual numbered definition. For example,
px-ikhlas is an alias for px-4. This is so that if we
want to change the number, we only have to change it in src/index.css, and the
changes will propagate to everywhere the alias is used.
px-ikhlas
mx-ikhlas
-mx-ikhlas (this is a hack for a child to ignore parent's paddings)
gap-x-ikhlas
gap-x-ikhlas-sm
gap-y-ikhlas
space-x-ikhlas
space-x-ikhlas-sm
space-y-ikhlas
Unlike Padding, Margin, Gap, this is just not just an alias. It also includes
mx-auto to keep its child elements centered.
max-w-ikhlas
scroll-edge-elements-center (scrollable overflow elements' edges are centered
when on visible)
no-scrollbar
This components library supports both ES and CommonJS modules.
import { ... } from "ikhlas-web-components";where you would put the component names, types and interfaces in ....
(WARNING: This is untested. Our build process makes CommonJS files, so this should work. If this works for you, please remove this warning.)
const x = require("ikhlas-web-components");and you can access the components, types and interfaces through dot notation,
like x.componentA. The name can be any thing other than x.
- Ensure the tree shaker of your app is allowed to tree shake unused exports. Each module in this library is guaranteed to have no side effects, so there's no harm to doing so.
You can view it at HISTORY.md.
For information on development and how to contribute, please see CONTRIBUTING.md.