@root-goblin/snapkin

v0.2.0

Published

2 years ago

yet another implementation of resizable panels in vanillajs

0High
0Medium
0Low

root-goblin

html css javascript typescript

Snapkin

Resizable panels

Design Goals

Snapkin is a framework agnostic library that attempts to play as nicely as possible with existing html/css/js paradigms. It does not try to bend page layout to its whim unless absolutely necessary to achieve its results.

Ideally this means that snapkin will be well behaved in any context it is imported it and play well with modern frontend frameworks.

Usage

Snapkin is intended to be used as a standalone JS+CSS library that adds custom HTML elements.

Framework Based Projects

Frameworks currently under test:

React
Vue

HTML

Snapkin works by creating custom HTML elements, thus it can be imported via a <script> tag, and <snap-drawer> elements will be turned into panels.

Note snapkin.css is required for snapkin to function correctly

<!-- index.html -->
<head>
    ...
    <link rel="stylesheet" type="text/css" href="/path/to/snapkin.css">
    ...
</head>
<body>
...

<snap-drawer direction="column" 
             class="border" 
             style="height: 500px; 
                    width: 500px;
                    border: solid 1px grey;">
    <div id="your">Hello</div>
    <div id="content">World!</div>
</snap-drawer>

...
</body>

<script type="module" src="/path/to/snapkin.js"></script>

VanillaJS

Snapkin can be used programmatically as well

import { SnapDrawer } from '@root-goblin/snapkin'

// create new element
const snapElement = new SnapDrawer()

// place into document just like any other HTML element
document.getElementById('my-node').replaceChild(snapElement)

// create new panels
snapElement.newPanelAt(0)

// access panels as a SnapBox[]
snapElement.childPanels[0].content = someElement

// place into some panel directly through SnapDrawer
snapElement.placeInPanel(0, someElement)

Warning Always assign to SnapBox.content, instead of setting innerHTML of any SnapBox element.

Develop and Build

Snapkin uses vite to preview with HMR.

0. Get the code

git clone https://git.sr.ht/~standoffish/snapkin

1. Install dependencies

npm install

2. Start up vite server and make changes

npm run dev

With the server running, it is time to fiddle with the code.

General file structure is as follows:

snapkin/
  ├── src/        -- main source code   <-------------------- START HERE
  ├── dist/       -- build output
  ├── public/     -- bundled assets   <--------------------- snapkin.css
  ├── test/       -- testing framework   <-------------------- style.css
  ├── types/      -- type declarations
  └── index.html  -- testing site entry

Vite will serve index.html and reload as the project files change.

3. Compiling to javascript

snapkin is a typescript project, it requires compiling into js for distrubition. The build script will automatically generate files in dist/

npm run build

Contributing

tl;dr -

git config sendemail.to ~standoffish/[email protected]

sourcehut is an email-based system, the process to pull, build, and submit patches are as follows:

1. Pull repo

git clone https://git.sr.ht/~standoffish/snapkin

2. Make changes

Y'know, fiddle with stuff, break things, eventually fix them and commit.

Once you have a set of commits...

3. Using git send-email to send the patchset

There is an excellent tutorial at https://git-send-email.io/ that I will not repeat.

Note that whenever the tutorial references the 'global configuration file', it is talking about the git global configuration file, which you can find with the following command[^1]:

git config --list --show-origin --show-scope

[^1]: Sourced from this helpful StackOverflow answer