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

@phun-ky/frameport

v2.0.7

Published

Create responsive documentation examples on the fly

Downloads

28

Readme

@phun-ky/frameport

logo

Frameport enables you to fake and display your responsive components in real life media queries!

Commitizen friendly PRs Welcome SemVer 2.0 npm version issues license size npm GitHub Repo stars codecov

About

Frameport was created so I could display frameports of components in a style guide. It creates iframes with your component (html, css and javascript) that acts as natural viewports, thus making use of your media queries! It is a zero dependency package!

npm i -S @phun-ky/frameport

API

Go here to read the full API documentation.

Demo

Click here for a demo on codepen.io

Options

| Option | Type | Required | Description | | ---------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | | | | | html | string | ✓ | The html you want to use in the viewport example | | height | string | number | | The height of the viewport, either as a string (e.g., '400') or a number (e.g., 400) | | width | string | number | | The width of the viewport, either as a string (e.g., '600') or a number (e.g., 600) | | className | string | | Class names to be given the generated iframe | | style | string | | Inline styles (CSS) to be inserted into a <style> -tag in the <head>-tag of the generated html | | css | string | | A CSS file to be appended to the <head>-tag of the generated html. NOTE! This needs to be on the same domain and relative to root! | | code | string | | Custom JavaScript code to be inserted into a <script>-tag in the <body>-tag in the generated html | | javascript | string | | A JavaScript file to be inserted in the <body>-tag of the generated html. NOTE! This needs to be on the same domain and relative to root! | | headers | string[] | | An array of HTTP headers to include when fetching the HTML content | | viewports | string | | The viewports to generate for examples. This is a string wxh for example: 375x667. If you want more viewports, you can separate them with a comma: 375x667,360x740,768x1024. NOTE! If not viewports are used, you need to set width! | | templateSelector | string | | Selector to the template | | templateElement | HTMLElement | | Template element | | target | string | | To identify this as a target to use to generate the frameports |

Usage

Typescript

Types can be found in @phun-ky/frameport/dist/frameport.d.ts.

ESM

Either import and run the required functions:

import frameport from '@phun-ky/frameport';

// do stuff
frameport(document.getElementById('target'), {
  width: 667,
  html: '<h1>FOO</h1>'
});

Script

Or place these script in your web page:

<script src="../path/to/frameport.js"></script>

And then follow the steps below that suites your needs :)

Advanced usage

If you want to control frameport a bit more, you have some options. Apply one of these attributes to the script element for different types of initialization:

<script src="../frameport.js" data-<manual|instant|dom|lazy></script>

| Tag | Description | | -------------- | --------------------------------------------------------------------- | | data-manual | Makes window.frameport() available to be used when you feel like it | | data-instant | fires off frameport() right away | | data-dom | Waits for DOMContentLoaded | | data-lazy | Lazy loads frameport() per specced element |

If no attribute is applied, it will default to data-dom, as in, it will initialize when DOMContentLoaded is fired.

Lazy

If you're importing frameport instead of with a script tag, you can use the following approach to apply lazy loading:

import frameport from '@phun-ky/frameport';

export const lazy = (): void => {
  const frameportObserverTarget = new IntersectionObserver((els, observer) => {
    els.forEach((el: IntersectionObserverEntry) => {
      if (el.intersectionRatio > 0) {
        const {
          dataset: {
            frameportTemplate: templateSelector,
            frameportVh: height,
            frameportVw: width,
            frameportCss: css,
            frameportStyle: style,
            frameportCode: code,
            frameportJs: javascript,
            frameportClass: className,
            frameportHeaders: headers,
            frameportViewports: viewports,
          },
        } = el.target as HTMLElement;

        let html = el.target.innerHTML;
        let templateElementToUse = el.target as HTMLElement;

        if (templateSelector) {
          const templateElement = document.querySelector(templateSelector);

          if (templateElement) {
            html = templateElement.innerHTML;
            templateElementToUse = templateElement as HTMLElement;
          }
        }

        const options = {
          templateSelector,
          templateElement: templateElementToUse,
          height,
          width,
          html,
          css,
          style,
          code,
          javascript,
          className,
          headers: getHeaders(headers),
          viewports,
        };
        dom(el.target as HTMLElement, options);
        observer.unobserve(el.target);
      }
    });
  });

  document.querySelectorAll('[data-frameport]').forEach((el) => {
    frameportObserverTarget.observe(el);
  });
};

Features

Via DOM

Place the script tag at the bottom of your page, right before the </body>-tag:

<script src="../path/to/@phun-ky/frameport/dist/frameport.js"></script>

Or with a CDN:

<script src="https://unpkg.com/@phun-ky/frameport/dist/frameport.js"></script>

And then follow the steps below to display the frameports you want :)

Use templates as a target

With this approach, the script will locate given template and produce frameports based on that template and insert them right after the template. The original template will be hidden:

<div
  data-frameport
  data-frameport-css="/css/ph.css"
  data-frameport-style="body{background-color: #84a295 !important;}"
  data-frameport-target
  data-frameport-template="#template"
  data-frameport-vw="667"
  data-frameport-vh="375"
></div>
<div id="template">
  <main class="ph" style="height: 100vh">
    <button class="ph button" type="button">Primary</button>
  </main>
</div>

The content of the [data-frameport]-container is the html you want to display in the frameport.

Use targets with different template

With this approach, you decide where the frameports are added. The script will locate given target and produce frameports based on the given template and insert them in that target. The original template will be hidden:

<div
  data-frameport
  data-frameport-css="/css/ph.css"
  data-frameport-style="body{background-color: #84a295 !important;}"
  data-frameport-viewports="375x667,360x740,768x1024"
>
  <main class="ph" style="height: 100vh">
    <div class="ph app">
      <p class="ph lead">Look mah, I'm in an iframe</p>
      <button class="ph button" type="button">Primary</button>
    </div>
  </main>
</div>

The above example code will generate 3 iframes with given viewports.

The content of the #template-container is the html you want to display in the frameport.

This approach is useful if you want to use a device decorator to mimic appearance of a device.

Allowed tags

| tag | description | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | data-frameport | To identify this as the template to use for generating the responsive examples. Required | | data-frameport-target | To identify this as a target to use to generate the frameports | | data-frameport-template | Selector to the template | | data-frameport-width | The viewport width. Required | | data-frameport-height | The viewport height. | | data-frameport-css | A CSS file to be appended to the <head>-tag of the generated html. NOTE! This needs to be on the same domain and relative to root! For example: /dist/yourcss.css | | data-frameport-style | Inline styles (CSS) to be inserted into a <style> -tag in the <head>-tag of the generated html | | data-frameport-code | Custom JavaScript code to be inserted into a <script>-tag in the <body>-tag in the generated html | | data-frameport-js | A JavaScript file to be inserted in the <body>-tag of the generated html. NOTE! This needs to be on the same domain and relative to root! For example: /dist/yourjs.js | | data-frameport-class | Class names to be given the generated iframe | | data-frameport-viewports | The viewports to generate for examples. This is a string wxh for example: 375x667. If you want more viewports, you can separate them with a comma: 375x667,360x740,768x1024. Required | | data-frameport-headers | An array of HTTP headers to include when fetching the HTML content |

Contributing

If you want to contribute, please read the CONTRIBUTING.md and CODE_OF_CONDUCT.md

Sponsor me

I'm an Open Source evangelist, creating stuff that does not exist yet to help get rid of secondary activities and to enhance systems already in place, be it documentation or web sites.

The sponsorship is an unique opportunity to alleviate more hours for me to maintain my projects, create new ones and contribute to the large community we're all part of :)

Support me with GitHub Sponsors.