npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@oakstudios/mechanical-ragger

v0.5.0

Published

A layout tool that automatically rags long text by line

Downloads

247

Readme

Mechanical Ragger

Demo

Installation

npm i @oakstudios/mechanical-ragger

Web Component

  1. Load the web component. Choose the option that best suits your needs:

    Using a script tag placed at the end of the body:

    <!-- this automatically registers the component in the window as mechanical-ragger -->
    <script src="https://unpkg.com/@oakstudios/[email protected]/web-component-auto-register.js"></script>

    OR importing the same auto-register function in JS:

    import "@oakstudios/mechanical-ragger/web-component-auto-register";

    OR registering the component manually:

    import MechanicalRagger from "@oakstudios/mechanical-ragger/web-component";
       
    customElements.define("mechanical-ragger", MechanicalRagger);
  2. Then add it to your HTML:

    <mechanical-ragger>
      Lorem ipsum dolor sit amet consectetur adipisicing elit.
    </mechanical-ragger>

React Component

import MechanicalRagger from "@oakstudios/mechanical-ragger/react";

export default () => {
  return <MechanicalRagger>Lorem ipsum dolor sit amet.</MechanicalRagger>;
};

Other Frameworks

While web components can be used in most any framework, if you'd like deep integration with the framework of your choosing, you can use src/web-component.js and src/react.jsx to reference in implementing mechanical-ragger elsewhere.

The npm package also exposes the MechanicalRaggerCore module that these use. eg:

import MechanicalRaggerCore from "@oakstudios/mechanical-ragger/core";

Options

--ragging-width

mechanical-ragger inherits the depth of the mechanical ragging from a CSS custom property. To set this to a value other than the default, apply the custom property anywhere in the DOM containing the mechanical-ragger.

/* Globally... */
body {
  --ragging-width: 3rem;
}

/* Or Locally */
mechanical-ragger:nth-child(1) {
  --ragging-width: 4rem;
}
mechanical-ragger:nth-child(2) {
  --ragging-width: 2rem;
}

Because this is a CSS custom property, you can change this value in the same place that you set the rest of your styles. The value will also respect other runtime conditions like media queries and application state.

mechanical-ragger {
  --ragging-width: 2rem;
}
/* Media Queries */
@media (min-width: 480px) {
  mechanical-ragger {
    --ragging-width: 3rem;
  }
}
/* User Preferences */
body.no-ragging mechanical-ragger {
  --ragging-width: 0px;
}

You can also use any css unit (ch, em, rem, vw, etc)

Best Practices

ℹ️ Tidying line-ends

You may hope for text lines to reach closer to the end of each line to make the ragging cleaner. HTML and CSS both offer tools to manage this.

In CSS:

mechanical-ragger {
  /* Insert hyphens according to browser hyphenation dictionaries */
  hyphens: auto;

  /* Or only inserts hyphens at the author's request */
  hyphens: manual;
}

With hyphens: manual, use the &shy; HTML entity in your text to suggest hyphenation breakpoints to the browser.

In HTML, the <wbr> tag can be used to suggest a word breakpoint without hyphenation.

⚠️ Browser handling of line-heights.

Chrome and other browsers do not allow for floating-point decimal line-heights. All line-heights are rounded to the nearest CSS pixel (px values that do not factor in screen pixel-density). To ensure that the ragging does not fall out of sync with the text it controls, opt for line-heights that evaluate to whole pixels.

Development

Package

npm run build in the root directory. The resulting modules are generated from the src/ directory, to the root directory. This is the structure used in the npm package.

Docs

cd into the docs/ directory, where you can interact with the create-react-app instance.

cd docs

npm run start