polyclass

v0.1.4

Published

5 months ago

JavaScript library designed to provide dynamic and real-time manipulation of CSS stylesheets. Whether you're looking to animate elements, adjust styles on-the-fly, or create responsive designs without the overhead of traditional CSS

Downloads

0High
0Medium
0Low

strangemother

automatic-css css-class pre-generated-classes just-in-time css declarative css

Polyclass.js

A procedural just-in-time declarative stylesheet for instant well-behaved functional CSS styling.

NPM License

<body polyclass> <!-- Activate -->
  <div class="margin-1em-20vw
              background-color-#111
              padding-2em">  <!-- Write classes -->
      <h1 class='color-#EEE'>
          Instant CSS margin, padding, background and text color - with zero effort.
      </h1>
  </div>
</body>

Quick Install • More Install
Example
Extras:
- Fonts Install and use fonts dynamically
- Vendor Prefix Scope Polyclass usage to a prefix
- Aliases Reduce typing by aliasing long word
- Events Apply JavaScript event listeners using class-names
- Icons Instant Google material icons
- Extended Colors Use all other CSS color types
- Inserting Rules Inject CSS declarations and custom detection functions
- Variables
  - CSS var() Utilise variables for declarative properties and values
  - Polyclass vars() object Use JavaScript objects as CSS vars
Deeper
- Running Instances
- Polyclass and CSS Anatomy Understand a CSS Property
- Addons Read more on the addon platform for customising Polyclass internals
Knowledge

🚀 In a Hurry?

Include from jsdelivr:

<!-- Immediate browser drop-in -->
<script src="https://cdn.jsdelivr.net/npm/polyclass@latest/dist/polyclass.browser-full.js"></script>

All Done. Let's use it.

Apply polyclass to your target, such as the body:

<body polyclass> <!-- Activate -->
  <h1 class='color-rebeccapurple'> <!-- Write classes -->
    Purple Title!
  </h1>
</body>

Polyclass anything! More Install

Your Instant, Pluggable, Dynamic CSS Base Library

Polyclass is a just-in-time CSS class library, built dynamically from your class-names using "Declarative CSS".

Just-in-Time runtime to declare CSS on-the-fly
No opinion no factory, forced, or predefined CSS included!
Supports any CSS length you need, from px to cqmax
All CSS Properties are ready, even: order-block-start-style-dotted!
Less than 7 Kilobytes (gzipped) including all addons.
over 5 quadrillion available properties *(and counting) 😅
No compilation, installation, dependencies, or IDE configurations!

<head>
  <script type="text/javascript" src='polyclass.full.js'></script>
</head>

<body polyclass
  class="margin-0
         padding-0
         background-color-#111
         font-roboto
         font-pack-roboto-100-400-i400-800-900
         color-#DDD
         display-grid
         grid-template-flow-columns">

      <h1 class"font-size-5rem">ET VOILÀ! Polyclassed.</h1>
</body

Features

It's open-source, lightweight and runtime pluggable. With only HTML class names, immediately generate CSS declarations in a dynamic stylesheet:

Real-time or pre-render compatible
Instant plug-and-play with no compilation required
No dependencies, pure JavaScript
MIT License

Invisible

Consider Polyclass as the missing link for class attribute your CSS stylesheet.

The style attribute works as expected
Existing classes and libraries remain unaffected
Override Polyclass declarations without complex selectors
Works along-side any JavaScript library

It's an instant CSS base - use the classical CSS for your seriously cool stuff.

Don't Tree-Shake! Tree Build!

Whether you're working with pre-rendered content or making live DOM changes, Polyclass ensures the stylesheet is declared as needed. No compilation steps or tree-shaking required, as Polyclass detects usage through a runtime tree immediately.

<header polyclass
    class='display-flex
           position-sticky
           top-1em'>
    Flexy sticky header! No mess!
</header>

Polyclass.getInstance(header).asString()
// Rendered CSS Stylesheet.

Polyclass possibilities are loaded from the processed HTML entity, ensuring the library is always ever-green, naturally adopting CSS engine changes as soon as they exist, such as Use Logical Properties

<h2 class='scroll-margin-top-var-header-height text-wrap-balance'>
  Text balanced h2,
  With a scrolling margin,
  for the page header from the CSS Var "header-height"
</h2>

Install & Use

Polyclass is designed to be quick to initiate.

Grab from jsdelivr and apply it directly to your HTML:

<script src="https://cdn.jsdelivr.net/npm/polyclass@latest/dist/polyclass.full.js"></script>

Grab from NPM and do node things:

npm install polyclass

An ESM import:

import Polyclass from "polyclass"

new Polyclass()

import() on the node terminal:

// Fetch the esm node default using import()
const { default: Polyclass } = await import("polyclass")

new Polyclass()

require() on the terminal:

// Collect a .cjs module with require()
const polyclass = await require("polyclass")

new polyclass.Polyclass()

Or if you have the source-code locally:

<!-- All included -->
<script src="polyclass/dist/polyclass.full.js"></script>

<script type="text/javascript">
    new Polyclass()
</script>

Load

To load Polyclass use the automatic attribute polyclass, or create a new JavaScript instance Polyclass(). Multiple instances of Polyclass can exist in one view

HTML `polyclass` attribute

Use the Polyclass automatic detection:

<!-- previously installed -->
<body polyclass>
  <h1 class='color-#999'>Grey Title!</h1>
</body>

JavaScipt `Polyclass` Instance

Run Polyclass somewhere in your code. It can run in the <head>, the <footer>, or installed asynchronously.

// Run when the DOM is prepared
const pc = Polyclass({
  processOnLoad: document.body
})

If the page is already loaded, run the process() method:

// DOM Loaded
const pc = Polyclass()
pc.process(document.body) // detect after load

// or provide a `target` to process immediately:
const pc = Polyclass({ target: document.body })

Processing isn't required when using the <Node polyclass></Node> attribute. Read more in Running Polyclass: Instance

Using Classes

Once installed, populate the html classes to see it in action:

<!-- previously imported polyclass -->
<div id="demo_space"
    class='foo
           padding-1em-2em
           margin-1em
           color-#333'>  <!-- That's it. Polyclass classes are ready-to-use. -->

    <p>Styled content from <strong>only</strong> CSS classes.</p>
</div>

What's Created

The styles are automatically generated:

| class | description | | --- | --- | | padding-1em-2em | Padding, top and bottom 1em, left and right 2em | | margin-1em | Margin, all sides 1em | | color-#333| Text color, nearly black #333 |

Here's the CSS Polyclass created:

.padding-1em-2em {
    padding: 1em 2em;
}

.margin-1em {
    margin: 1em;
}

.color-\#333 {
    color: #333;
}

Useful Functionality:

Fonts Install and use fonts dynamically
Icons Install and use Google material dynamically
Vendor Prefix Scope Polyclass usage to a prefix
Aliases Reduce typing by aliasing long word
Events Apply JavaScript event listeners using class-names
More Colors Expanded color types, such as hsl and rgb ...
Inserting Rules Inject CSS declarations and custom detection functions.
CSS var() Utilise --vars for declarative properties and values
Polyclass vars() object Use JavaScript objects as CSS vars

Who is this for?

Designers

Iterate on your styles until you're happy. With a massive base of rules there is less to build as you invent.

Developers

Don't spend time caring for your base styles. Use a declarative naming convention for your class names for easy to document, easy to integrate core styles, and less bytes to download.

Vendors

Build your layout engine or style library. Enable the vendor prefix and invent your own dynamic classes.

Why?

Reduce Boilerplate Ideas change. Designs alter. Polyclass can help kill the junk CSS and massive boiler-sheets of pre defined classes.
Become your own vendor! Don't settle for a forever locked-in eco-system, supporting enormous stylesheets. Build out your own boilerplate, add a vendor switch and job done!
Generate Dynamic Classes Build dynamic names to write base and generate layouts without limits, such as a column-structure: acme-grid-columms-4, acme-grid-columms-3, acme-grid-columms-12
Faster page load times CSS mean bytes down the pipe. Polyclass builds CSS on the fly.
Dynamic CSS tooling With ALL CSS Properties ready to go, you can offer this tool in your buildouts; for dynamic styling of your components - without base sheets and limits.
- CMS theming addons
- HTML edit only environments
- extend to make your own dynamic sheet inclusions.

What is "Just-in-Time"?

Polyclass does not have a pre-compiled list of CSS Classes. Definitions are generated through a process of detected used classes, and immediately creating a corresponding CSS declaration.

Just-In-Time (JIT) compilation in Polyclass dynamically generates CSS classes as they're needed, optimizing efficiency by focusing only on the styles actively used in the document. This process ensures lean performance-oriented styling, eliminating pre-compiled CSS clutter and enhancing web application responsiveness.

<div class='margin-5em-20vw'>
    <p>This div immediately generates the class</p>
</div>

<div class='margin-5em-20vw'>
    <p>This div reuses the previously generated class</p>
</div>

What is "Declarative" CSS?

In its simplified form the term "declarative" means what to do, where the antonym "imperative" would be how to do:

| Declarative | Imperative | | --- | --- | | What to do | How to do | | Expression | Statement | | Less Variable Mutation | More Variable Mutation |

HTML is declarative, allowing the developer to perceive an object as the literal entity. For example we have a layout including a single header h1. The identity of the object is "what is does". A h1 will never be a input.

<body>
  <div>
    <h1>This is a H1</h1>
  </div>
</body>

Declarative CSS with Polyclass

By naming a class to mirror CSS properties and their values, such as border-color-red, users explicitly define what to do without delving into how to achieve it. This approach removes the verbosity and complexity traditionally associated with CSS, streamlining style application and changes.

| Declarative Class Name | CSS Output | |------------------------|------------------------| | margin-1em | margin: 1em; | | border-color-red | border-color: red; | | text-align-center | text-align: center; |

Declarative CSS with Polyclass means direct, readable, and maintainable code, where style modifications are as simple as swapping class names, ensuring a seamless and intuitive design experience.

Developer Speed

A declarative method for CSS styles ensure:

Developers know how a class affects the view As the class-name is the declaration, is extremely unlikely to find color-red representing another colour.
Immediate Learning Existing developer knowledge is an advantage, with a base library using real hex, hsl or even Q measurements for values.
Instant Integration Using a clean naming convention allows the developer to instantly update the view to reflect changes with no cleanup of old classes is required.

Polyclass's JIT approach exemplifies how on-demand generation of styles can streamline development workflows, offering a flexible, efficient solution for real-time CSS management.

<div class='display-flex
            max-width-80vw
            font-size-1.222ch
            padding-0-10vw'>

        <h1 class='font-size-5rem'>
          Instant styling,
          Immediately generated,
          Never stale.
        </h1>
</div>

Example

If there is a CSS Property, it can be defined in Polyclass. Here's some HTML, with some Polyclass CSS class attributes:

<div class="my-container some-other-primary-area
    font-pack-roboto-100-400-i400
    background-#333"> <!-- Load fonts, and a background-color -->

      <div class="demo-box
        gap-1em
        display-flex
        flex-direction-column
        "> <!-- convert to the flex box model, with a gap -->

          <div class="my-text-thing
            background-color-#111
            border-solid-3px-green
            border-radius-.4em
            padding-.8em-1.4em
            color-#EEE
            font-roboto-400
            margin-1em"> <!-- A rounded border, background, color, and font changes -->

              Text content.

          </div>
      </div>
</div>

Once defined, the constructed classes are invented on-the-fly:

| class | property | values | | --- | --- | --- | | background-color-#111 | background-color | #111 | | background-#333 | background | #333 | | border-solid-3px-green | border | 3px green | | border-radius-.4em | border | 0.4em | | color-#EEE | color | #EEE | | display-flex | display | flex | | flex-direction-column | flex | column | | gap-1em | gap | gap-1em | | margin-1em | margin | 1em | | padding-.8em-1.4em | padding | 0.8em 1.4em | | font-pack-roboto-100-400-i400 | *Special case | Install font "Roboto", 100, 400, italic 400 | | font-roboto-400 | font-family, font-size | "Roboto", 400 |

As expected each class exactly represents the key:value of any declarable CSS Property.

Without using any existing CSS sheets, Polyclass will generate all the expected CSS as a constructed stylesheet.

Build

Polyclass utilises Rollup

npm run build
npx rollup -c

License

This project is licensed under the terms of the MIT License.

The MIT License offers you the freedom to use, modify, and distribute this code. While it’s not a formal requirement, taking a moment to acknowledge the original contributors reflects a deep-seated respect that is fundamental to the open-source community.

Contributing

We sincerely welcome contributions! There is no barrier for entry and all input is valid input. If you find a bug or have a feature request, please open an issue. If you'd like to contribute code, please fork the repository and submit a pull request.

Open-source is as much about collaboration and mutual respect as it is about code. As a project committed to this ethos, we promise to always recognize and credit contributions with gratitude and respect.

We value the thoughtfulness and care put into each contribution, not to reduce them to mere numbers or to brush them off with a cavalier "...that’s what open source is...". A project thrives on its community’s spirit and collective efforts.