Metadata-Version: 2.5
Name: spaday-collab
Version: 0.1.0
Summary: Shared pointers and presence for spaday
Project-URL: Repository, https://github.com/1kbgz/spaday-collab
Project-URL: Homepage, https://github.com/1kbgz/spaday-collab
Author-email: 1kbgz <dev@1kbgz.com>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.11
Requires-Dist: spaday<1.0,>=0.14.2
Provides-Extra: develop
Requires-Dist: build; extra == 'develop'
Requires-Dist: bump-my-version; extra == 'develop'
Requires-Dist: check-dist; extra == 'develop'
Requires-Dist: codespell; extra == 'develop'
Requires-Dist: hatch-js; extra == 'develop'
Requires-Dist: hatchling; extra == 'develop'
Requires-Dist: httpx; extra == 'develop'
Requires-Dist: mdformat; extra == 'develop'
Requires-Dist: mdformat-myst; extra == 'develop'
Requires-Dist: mdformat-tables>=1; extra == 'develop'
Requires-Dist: pydantic>=2; extra == 'develop'
Requires-Dist: pytest; extra == 'develop'
Requires-Dist: pytest-cov; extra == 'develop'
Requires-Dist: ruff; extra == 'develop'
Requires-Dist: starlette; extra == 'develop'
Requires-Dist: transports<0.13,>=0.12.3; extra == 'develop'
Requires-Dist: twine; extra == 'develop'
Requires-Dist: ty; extra == 'develop'
Requires-Dist: uv; extra == 'develop'
Requires-Dist: uvicorn; extra == 'develop'
Requires-Dist: websockets; extra == 'develop'
Requires-Dist: wheel; extra == 'develop'
Provides-Extra: examples
Requires-Dist: pydantic>=2; extra == 'examples'
Requires-Dist: starlette; extra == 'examples'
Requires-Dist: transports<0.13,>=0.12.3; extra == 'examples'
Requires-Dist: uvicorn; extra == 'examples'
Requires-Dist: websockets; extra == 'examples'
Description-Content-Type: text/markdown

<a href="https://github.com/1kbgz/spaday-collab">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://github.com/1kbgz/spaday-collab/raw/main/docs/img/logo-dark.webp?raw=true">
    <img alt="spaday-collab logo, shared pointers inside a browser window" src="https://github.com/1kbgz/spaday-collab/raw/main/docs/img/logo-light.webp?raw=true" width="1200">
  </picture>
</a>

[![Build Status](https://github.com/1kbgz/spaday-collab/actions/workflows/build.yaml/badge.svg)](https://github.com/1kbgz/spaday-collab/actions/workflows/build.yaml)
[![PyPI](https://img.shields.io/pypi/v/spaday-collab.svg)](https://pypi.org/project/spaday-collab/)
[![License](https://img.shields.io/github/license/1kbgz/spaday-collab)](LICENSE)

Optional shared pointers and hover outlines for [spaday](https://github.com/1kbgz/spaday). Use ordinary HTML targets or supply geometry from a virtualized component.

## Install

```bash
pip install "spaday-collab[examples]"
```

## Usage

```python
from spaday import SetField, element, event_value
from spaday_collab import Pointers

page = element(
    "main",
    element("section", "Review this section", **{"data-collab-target": "review"}),
    Pointers()
    .bind("peers", "remote_pointers")
    .on("pointer-change", SetField("local_pointer", event_value("pointer"))),
)
```

A pointer is `{target, x, y}` with coordinates between zero and one. Remote entries are `{peer, pointer, label?, color?}`. The application maps scoped awareness into this list and chooses labels and colors. The included example uses Spaday's `Wire.awareness` and one transports connection for both shared data and pointers.

The browser module also exports `connectPointers`, `domTargets`, and `elementGeometry`. These work without the `Pointers` renderer or a transports connection.

## Documentation

- [Tutorial](https://1kbgz.github.io/spaday-collab/docs/src/tutorial.html): run two users against a shared note.
- [How-to guides](https://1kbgz.github.io/spaday-collab/docs/src/how-to.html): connect awareness, adapt geometry, and replace the display.
- [Reference](https://1kbgz.github.io/spaday-collab/docs/src/reference.html): Python component, browser API, and tokens.
- [Explanation](https://1kbgz.github.io/spaday-collab/docs/src/explanation.html): ownership and lifecycle boundaries.

## Browser Examples

[Open the Pyodide gallery](https://1kbgz.github.io/spaday-collab/lite/). Python creates real `Pointers` components with explicitly labeled sample peers. This single-browser preview has no shared server; use the local example for real collaboration.

## Run the examples locally

```bash
pip install "spaday-collab[examples]"
python -m spaday_collab.example
```

Open http://127.0.0.1:8044/ and http://127.0.0.1:8044/bob in separate browsers. Move over the note or review section to see pointers, then edit the shared note. Demo identities are selected by URL; production applications must authenticate users and assign permissions on the server.

From a checkout, run `make develop`, `make build`, and `make test`. `make pyodide-example` builds `dist/lite`; `make test-pyodide-example` checks that preview in Chromium.

> [!NOTE]
> This library was generated using [copier](https://copier.readthedocs.io/en/stable/) from the [Base Python Project Template repository](https://github.com/python-project-templates/base).
