@cocreate/scrollbar 0.0.0-stage → 1.12.0

package/CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to CoCreate-overlay-scroll
+
+This project is work of [many contributors](https://github.com/CoCreateJS/overlay-scroll/graphs/contributors).
+You're encouraged to submit [pull requests](https://github.com/CoCreateJS/overlay-scroll/pulls),
+[propose features and discuss issues](https://github.com/CoCreateJS/overlay-scroll/issues).
+
+In the examples below, substitute your Github username for `contributor` in URLs.
+
+## Fork the Project
+
+Fork the [project on Github](https://github.com/CoCreateJS/overlay-scroll) and check out your copy.
+
+```
+git overlay-scroll https://github.com/contributor/CoCreate-overlay-scroll.git
+cd CoCreate-overlay-scroll
+git remote add upstream https://github.com/CoCreateJS/overlay-scroll.git
+```
+
+## Create a Topic Branch
+
+Make sure your fork is up-to-date and create a topic branch for your feature or bug fix on dev branch.
+
+```
+git checkout dev
+git pull upstream dev
+git checkout -b my-feature-branch
+```
+
+## Write Tests
+
+Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build.
+
+We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
+
+## Write Code
+
+Implement your feature or bug fix.
+
+## Write Documentation
+
+Document any external behavior in the [README](README.md).
+
+## Commit Changes
+
+Make sure git knows your name and email address:
+
+```
+git config --global user.name "Your Name"
+git config --global user.email "contributor@example.com"
+```
+
+We use [semantic-release](https://github.com/semantic-release/semantic-release) as process to generate changelog
+and to release. Write meaningful commits according to 
+[Commit Message Formats](https://github.com/semantic-release/semantic-release#commit-message-format) is important.
+
+```
+git add ...
+git commit -am "commit-type(optional topic): a meaningful message"
+```
+
+Here is an example of the release type that should be done based on a [semantic-release](https://github.com/semantic-release/semantic-release):
+
+| Commit message                                                                                                                                                                                   | Release type               |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| `fix(pencil): stop graphite breaking when too much pressure applied`                                                                                                                             | Patch Release              |
+| `feat(pencil): add 'graphiteWidth' option`                                                                                                                                                       | ~~Minor~~ Feature Release  |
+| `perf(pencil): remove graphiteWidth option`<br><br>`BREAKING CHANGE: The graphiteWidth option has been removed.`<br>`The default graphite width of 10mm is always used for performance reasons.` | ~~Major~~ Breaking Release |
+
+
+## Push
+
+```
+git push origin my-feature-branch
+```
+
+## Make a Pull Request
+
+Go to [https://github.com/CoCreateJS/overlay-scroll](https://github.com/CoCreateJS/overlay-scroll) and select your feature branch.
+Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
+
+## Rebase
+
+If you've been working on a change for a while, rebase with upstream/dev.
+
+```
+git fetch upstream
+git rebase upstream/dev
+git push origin my-feature-branch -f
+```
+
+## Be Patient
+
+It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang in there!
+
+## Thank You
+
+Please do know that we really appreciate and value your time and work. We love you, really.

package/CoCreate.config.js

@@ -0,0 +1,23 @@
+module.exports = {
+    "organization_id": "",
+    "key": "",
+    "host": "",
+    "sources": [
+        {
+            "array": "files",
+            "object": {
+                "_id": "6020801d3c260207bf49caba",
+                "name": "index.html",
+                "path": "/docs/overlay-scroll",
+                "pathname": "/docs/overlay-scroll/index.html",
+                "src": "{{./docs/index.html}}",
+                "host": [
+                    "*"
+                ],
+                "directory": "overlay-scroll",
+                "content-type": "{{content-type}}",
+                "public": "true"
+            }
+        }
+    ]
+};

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 CoCreate LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# CoCreate Scrollbar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A declarative custom scrollbar for native scroll containers with configurable
+axes, track positions, visibility, and automatic DOM lifecycle handling.
+
+The component preserves browser-native scrolling, including wheel, keyboard,
+touch, and programmatic scrolling. It hides the native scrollbar and adds
+custom overlay tracks and draggable thumbs.
+
+## Installation
+
+```shell
+npm install @cocreate/scrollbar
+```
+
+```shell
+yarn add @cocreate/scrollbar
+```
+
+Importing the package loads its styles and initializes every element with a
+`scrollbar` attribute.
+
+```js
+import CoCreateScrollbar from "@cocreate/scrollbar";
+```
+
+## Usage
+
+Give the scrollbar host a constrained width and height. Its first element child
+becomes the native scrolling viewport.
+
+```html
+<div scrollbar style="height: 300px">
+  <div>
+    <!-- Scrollable content -->
+  </div>
+</div>
+```
+
+The host owns the generated tracks. Keep asynchronously loaded content inside
+the viewport rather than placing `src` on the scrollbar host:
+
+```html
+<div scrollbar style="height: 300px">
+  <div>
+    <div src="/components/content.html"></div>
+  </div>
+</div>
+```
+
+This prevents fetched content from replacing the viewport and generated track
+structure.
+
+## Attributes
+
+| Attribute | Values | Default | Purpose |
+| --- | --- | --- | --- |
+| `scrollbar` | Boolean attribute | — | Initializes the component. |
+| `scrollbar-type` | `scrollx`, `scrolly`, or both | `scrollx scrolly` | Enables the requested axes. |
+| `scrollbar-pos` | `left` or `right`, plus `top` or `bottom` | `right bottom` | Positions the vertical and horizontal tracks. |
+| `scrollbar-visible` | `auto` or `show` | `auto` | Shows tracks contextually or keeps them visible. |
+
+### Vertical scrolling only
+
+```html
+<div scrollbar scrollbar-type="scrolly" style="height: 300px">
+  <div>...</div>
+</div>
+```
+
+### Tracks on the top and left
+
+```html
+<div scrollbar scrollbar-pos="top left" style="height: 300px">
+  <div>...</div>
+</div>
+```
+
+### Always-visible tracks
+
+```html
+<div scrollbar scrollbar-visible="show" style="height: 300px">
+  <div>...</div>
+</div>
+```
+
+Attribute changes are applied dynamically. Adding or removing the `scrollbar`
+attribute initializes or destroys the instance, while changing an option
+attribute refreshes it.
+
+## JavaScript API
+
+```js
+const element = document.querySelector("[scrollbar]");
+
+const instance = CoCreateScrollbar.init(element);
+CoCreateScrollbar.get(element);
+CoCreateScrollbar.destroy(element);
+CoCreateScrollbar.initAll();
+```
+
+`init()` accepts an element, a selector, or an array-like collection. Elements
+inserted into or removed from the document are also initialized and destroyed
+automatically through `@cocreate/observer`.
+
+## Update event
+
+The host dispatches `cocreate-scroll-update` whenever its scrollbar geometry is
+recalculated.
+
+```js
+element.addEventListener("cocreate-scroll-update", (event) => {
+  console.log(event.detail.scrollTop, event.detail.maxScrollY);
+});
+```
+
+The event detail includes:
+
+- `scrollTop` and `scrollLeft`
+- `maxScrollY` and `maxScrollX`
+- `clientHeight` and `clientWidth`
+- `thumbVHeight` and `thumbHWidth`
+
+## Styling
+
+Customize the tracks with CSS variables on the scrollbar host:
+
+```css
+.my-scrollbar {
+  --cc-track-bg: rgb(0 0 0 / 8%);
+  --cc-thumb-bg: rgb(99 102 241 / 75%);
+  --cc-thumb-hover-bg: rgb(129 140 248);
+}
+```
+
+The stylesheet also includes `theme-indigo`, `theme-emerald`, `theme-rose`,
+`theme-amber`, `theme-glass`, and `theme-dark` preset classes.
+
+## Project links
+
+- [Documentation](https://CoCreateJS.com/docs/scrollbar)
+- [Issues](https://github.com/CoCreateJS/scrollbar/issues)
+- [Releases](https://github.com/CoCreateJS/scrollbar/releases)
+- [Contributing](https://github.com/CoCreateJS/scrollbar/blob/master/CONTRIBUTING.md)
+
+## License
+
+[MIT](https://github.com/CoCreateJS/scrollbar/blob/master/LICENSE)

package/demo/index.html

@@ -0,0 +1,196 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Scrollbar | CoCreateJS</title>
+
+        <link
+            rel="icon"
+            type="image/png"
+            sizes="32x32"
+            href="../assets/favicon.ico" />
+        <link
+            rel="stylesheet"
+            href="../dist/CoCreate-overlay-scroll.css"
+            type="text/css" />
+
+        <style>
+            * {
+                box-sizing: border-box;
+            }
+
+            body {
+                margin: 0;
+                padding: 32px;
+                color: #1f2937;
+                background: #f3f4f6;
+                font-family: Arial, sans-serif;
+            }
+
+            h1 {
+                margin: 0 0 8px;
+            }
+
+            .description {
+                margin: 0 0 32px;
+                color: #6b7280;
+            }
+
+            .examples {
+                display: grid;
+                grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
+                gap: 24px;
+            }
+
+            .example {
+                padding: 16px;
+                border: 1px solid #e5e7eb;
+                border-radius: 12px;
+                background: #ffffff;
+            }
+
+            .example h2 {
+                margin: 0 0 12px;
+                font-size: 16px;
+            }
+
+            .scrollbar-demo {
+                width: 100%;
+                height: 240px;
+                border: 1px solid #d1d5db;
+                border-radius: 8px;
+                background: #ffffff;
+            }
+
+            .scrollbar-demo.theme-dark {
+                border-color: #374151;
+                color: #f9fafb;
+                background: #111827;
+            }
+
+            .content {
+                display: grid;
+                place-items: center;
+                min-width: 100%;
+                min-height: 100%;
+                padding: 24px;
+                color: #374151;
+                background:
+                    linear-gradient(135deg, rgba(99, 102, 241, 0.18), rgba(16, 185, 129, 0.18)),
+                    repeating-linear-gradient(
+                        0deg,
+                        transparent,
+                        transparent 39px,
+                        rgba(107, 114, 128, 0.18) 40px
+                    ),
+                    repeating-linear-gradient(
+                        90deg,
+                        transparent,
+                        transparent 39px,
+                        rgba(107, 114, 128, 0.18) 40px
+                    );
+            }
+
+            .theme-dark .content {
+                color: #f9fafb;
+            }
+
+            .content-both {
+                width: 640px;
+                height: 520px;
+            }
+
+            .content-x {
+                width: 720px;
+                height: 100%;
+            }
+
+            .content-y {
+                width: 100%;
+                height: 640px;
+            }
+        </style>
+    </head>
+
+    <body>
+        <h1>CoCreate Scrollbar</h1>
+        <p class="description">
+            The first child remains the native scrolling viewport. Only the
+            overlay tracks and thumbs are generated.
+        </p>
+
+        <main class="examples">
+            <section class="example">
+                <h2>Horizontal and vertical</h2>
+                <div class="scrollbar-demo" scrollbar>
+                    <div>
+                        <div class="content content-both">Scroll in either direction</div>
+                    </div>
+                </div>
+            </section>
+
+            <section class="example">
+                <h2>Horizontal only</h2>
+                <div
+                    class="scrollbar-demo"
+                    scrollbar
+                    scrollbar-type="scrollx">
+                    <div>
+                        <div class="content content-x">Horizontal scrolling</div>
+                    </div>
+                </div>
+            </section>
+
+            <section class="example">
+                <h2>Vertical only</h2>
+                <div
+                    class="scrollbar-demo"
+                    scrollbar
+                    scrollbar-type="scrolly">
+                    <div>
+                        <div class="content content-y">Vertical scrolling</div>
+                    </div>
+                </div>
+            </section>
+
+            <section class="example">
+                <h2>Top and left</h2>
+                <div
+                    class="scrollbar-demo"
+                    scrollbar
+                    scrollbar-pos="top left">
+                    <div>
+                        <div class="content content-both">Tracks positioned top and left</div>
+                    </div>
+                </div>
+            </section>
+
+            <section class="example">
+                <h2>Always visible</h2>
+                <div
+                    class="scrollbar-demo theme-emerald"
+                    scrollbar
+                    scrollbar-visible="show">
+                    <div>
+                        <div class="content content-both">Tracks remain visible</div>
+                    </div>
+                </div>
+            </section>
+
+            <section class="example">
+                <h2>Dark theme</h2>
+                <div
+                    class="scrollbar-demo theme-dark"
+                    scrollbar
+                    scrollbar-visible="show">
+                    <div>
+                        <div class="content content-both">Dark scrollbar theme</div>
+                    </div>
+                </div>
+            </section>
+        </main>
+
+        <script src="../dist/CoCreate-overlay-scroll.js"></script>
+    </body>
+</html>