Nonprofit Pizza Maker

    augm-it
    TypeScript icon, indicating that this package has built-in type declarations

    0.5.3 • Public • Published
    augm logo

    augm-it

    Lightweight components with multiple delivery strategies

    🚧 Under active development. Come back soon! 🚧

    Features

    • Write markup (HTML), styles (CSS), and handler (JS) in a single file (modeled after svelte)
    • Extremely lightweight
    • Built on uhtml, which is a fast tagged-template alternative to virtual-dom architectures (vue,react,preact, etc...)
    • Automatically generates
      • SSR-friendly scripts
        • Optimized saturation script for minimal TTI (time to interactive)
        • Load component render functions on demand
        • Bundled and optimized CSS stylesheet
      • Standalone components (for easy imports from an external script / page)
        • Automatic saturation of existing elements with matching css query (class="SpecialButton")
        • Importable (props)=>(HTML Fragment) standalone component for scripts that handle rendering

    Usage

    CLI

    TODO

    Scripts to import

    TODO

    Writing Components

    Components are functions that return HTML snippets. On the server, these snippets are strings. On the browser, they're specialized HTML fragments powered by uhtml.

    Here's a very simple example:

    Greeting.js

    import { html } from 'augm-it'
    
    export default (name) => html`
      <h1>Hello, ${name}</h1>
    `

    test.js

    import Greeting from './Greeting'
    
    Greeting("Marshall")
    // ~> <h1>Hello, Marshall</h1>

    To add styles and make our components interactive, we'll need to use the style and handlers exports.

    • style a function that returns a CSS snippet that will style that component
    • handlers an object with keys that correspond to class names and values that correspond to custom-element handlers for HTML nodes with that class

    You can think of handlers and style as generic definitions that apply to all instances of the component. If we have 29 greetings on one page, there will only be one invocation of style and handlers, while the default render function will be called 29 times.

    To create readable and portable class names that won't suffer from name-clashing, we'll use the classify function to connect the render, styles, and handlers.

    import { html, svg, css, classify } from 'augm-it'
    
    // `classify` generates a proxy that outputs class names that avoid name-clashing
    let Example = classify('Example')
    
    // on server, returns string. on browser, returns HTML fragment
    export default ({ name }) =>html`
      <div class=${Example}>
        <span class=${Example.greeting}>
          Hello ${name}
        </span>
      </div>
    `
    
    // custom-element-like handlers to be attached to elements with corresponding classes
    export let handlers={
      [Example]: {
        init(){
          console.log("Example is live!")
        }
      },
      [Example.greeting]: {
        onClick(){
          console.log("The greeting was clicked!")
          this.element.classList.toggle('active')
        }
      }
    }
    
    // added to aggregate stylesheet for SSR
    export let style = () => css`
      .${Example}{
        border: 1px dashed #c89;
        padding: 1rem;
        text-align: center;
      }
      .${Example.greeting}{
        font-size: 2rem;
        color: #412;
      }
      .${Example.greeting}.active{
        color: #179;
      }
    `

    Getting Started

    • Get VSCode Extensions for syntax highlighting:
      • literally-html: Syntax highlighting for html inside of JS tagged template strings
      • vscode-styled-componets: Offers CSS syntax highlighting and code completion inside css tagged template strings

    How it Works

    TODO

    Acknowledgements

    Heavily inspired by @WebReflection's libraries. augm-it uses uhtml for browser-side rendering and wicked-elements for attaching handlers.

    DevX inspired by svelte

    Keywords

    none

    Install

    npm i augm-it

    DownloadsWeekly Downloads

    6

    Version

    0.5.3

    License

    MIT

    Unpacked Size

    35 kB

    Total Files

    9

    Last publish

    Collaborators

    • marshallcb