@pol-cova/gessi 0.0.1 → 0.0.2

package/AGENTS.md

@@ -0,0 +1,237 @@
+# Gessi repository guide
+
+This file gives coding agents and contributors the context needed to change or
+integrate Gessi without first reverse-engineering the repository.
+
+## Product
+
+Gessi is a dependency-free CSS and native Web Component library for expressive
+HTML, retro interfaces, and browser-based desktop environments.
+
+The primary usage target is plain HTML:
+
+```html
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@pol-cova/gessi/dist/gessi.js"
+></script>
+```
+
+The same package supports npm, static-site generators, server-rendered
+templates, and JavaScript frameworks. Do not make a framework runtime required.
+
+## Design principles
+
+- Plain HTML is the public API.
+- Keep the runtime dependency-free.
+- Prefer a small semantic component vocabulary over utility-class expansion.
+- Preserve light DOM so content is visible to static output, search engines,
+  project CSS, and no-JavaScript fallbacks.
+- Treat interaction as progressive enhancement.
+- Keep imports safe during SSR and static builds.
+- Components must remain useful across every visual system.
+- Responsive behavior should produce readable document flow without separate
+  mobile markup.
+
+## Repository map
+
+```txt
+src/gessi.css          source stylesheet and all visual systems
+src/components.js      native custom elements and interactions
+src/gessi.js           CDN entry; registers components and loads sibling CSS
+src/fonts/             bundled font assets and license
+
+dist/                  published package output; generated from src/
+docs/                  custom static documentation source
+examples/              complete HTML examples and visual fixtures
+scripts/               build, verification, preview, and release scripts
+.github/workflows/     package verification and GitHub Pages deployment
+```
+
+`dist` is committed and must always match `src`.
+
+## Public entry points
+
+The package exports:
+
+```txt
+@pol-cova/gessi
+@pol-cova/gessi/css
+@pol-cova/gessi/components
+@pol-cova/gessi/gessi.js
+```
+
+- `css` is the stylesheet-only entry.
+- `components` is safe for bundlers and SSR. It does not inject CSS.
+- `gessi.js` is the one-script CDN entry and automatically loads `gessi.css`.
+
+## Visual systems
+
+All themes are selected with `data-gs-style` or the `theme` attribute on
+`gessi-desktop`:
+
+```txt
+neo
+minimal
+retro
+old-tech
+classic-os
+```
+
+Theme CSS must stay scoped. A theme must not alter an unrelated page unless the
+page or component explicitly opts into it.
+
+## Component families
+
+Environment:
+
+```txt
+gessi-desktop
+gessi-window
+gessi-dialog
+```
+
+Navigation and structure:
+
+```txt
+gessi-menu
+gessi-toolbar
+gessi-dock
+gessi-breadcrumb
+gessi-tabs
+gessi-icons
+gessi-icon
+gessi-tree
+gessi-list
+```
+
+System UI:
+
+```txt
+gessi-panel
+gessi-meter
+gessi-alert
+gessi-toast
+gessi-tooltip
+gessi-separator
+```
+
+Media:
+
+```txt
+gessi-media
+gessi-map
+gessi-marker
+gessi-carousel
+```
+
+Use native links, buttons, lists, images, and headings inside components. Do
+not replace semantic elements with click handlers on generic containers.
+
+## Component implementation rules
+
+- Extend the SSR-safe `HTMLElementBase`; never access browser-only globals at
+  module evaluation time without a guard.
+- Enhance once by checking `data-enhanced`.
+- Keep content in light DOM; do not introduce Shadow DOM.
+- Generated controls need an accessible name and correct native element.
+- Public methods and events should be small and documented.
+- Clean up global listeners and timers in `disconnectedCallback`.
+- Keep attribute APIs declarative and usable in static templates.
+- Test keyboard behavior for every interactive component.
+- On narrow screens, positioned OS UI must remain readable and reachable.
+
+## CSS rules
+
+- Public class names use the `gs-` prefix.
+- Reuse existing layout primitives before adding a new class.
+- Scope theme variants beneath `[data-gs-style="…"]`.
+- Use custom properties for intentional public configuration.
+- Respect `prefers-reduced-motion`.
+- Check high contrast, focus-visible states, overflow, and long content.
+- Media effects should compose and must not mutate the original file.
+
+## Documentation
+
+The documentation is intentionally custom and dependency-free. It lives in:
+
+```txt
+docs/index.html
+docs/docs.css
+docs/docs.js
+```
+
+It provides search, copy-ready snippets, live theme previews, component
+reference, media examples, and links to full environments.
+
+When changing public API:
+
+1. Update the relevant docs section.
+2. Add or update a copy-ready example.
+3. Update an example page when visual interaction is involved.
+4. Keep the root README short; detailed reference belongs in `docs/`.
+
+Build the deployable Pages artifact with:
+
+```bash
+npm run docs:build
+```
+
+The generated `_site/` directory is ignored and must not be committed.
+
+## Development commands
+
+```bash
+npm run build        # copy source assets into dist
+npm run check        # verify dist parity, imports, docs, and examples
+npm run docs:build   # build _site for GitHub Pages
+npm run pack:check   # inspect the npm package
+npm run preview      # local server on port 4173
+```
+
+Before committing a public change, run:
+
+```bash
+npm run build
+npm run check
+npm run docs:build
+npm pack --dry-run
+git diff --check
+```
+
+For visual changes, verify both desktop and mobile in a browser. Check the
+custom docs and any affected complete example.
+
+## Integration guidance
+
+When adding Gessi to another repository:
+
+- Use the CDN `gessi.js` entry for plain HTML without a build step.
+- In a bundler, import `@pol-cova/gessi/css` and
+  `@pol-cova/gessi/components`.
+- In Astro, import the CSS in frontmatter and components in a browser module
+  script; native custom elements do not require a framework hydration
+  directive.
+- In SSR code, import `components` normally; registration is browser-guarded.
+- Keep project-specific content layout in ordinary CSS. Gessi owns reusable
+  chrome and interaction, not every application grid.
+- Avoid wrapping custom elements in framework components unless the wrapper
+  adds project-specific behavior.
+
+## GitHub automation
+
+- `verify.yml` builds assets, checks source/output parity, builds docs, and
+  validates npm package contents.
+- `pages.yml` builds `_site` and deploys it to GitHub Pages after pushes to
+  `main`.
+- Public roadmap work is tracked in GitHub issues instead of repository
+  roadmap files.
+
+## Do not
+
+- Add Tailwind-style one-purpose class proliferation.
+- Add React, Vue, or another framework as a runtime requirement.
+- Add a build requirement for CDN/plain HTML users.
+- edit only `dist`; make source changes in `src` and rebuild.
+- Commit `_site`, package tarballs, browser QA captures, or temporary files.
+- Break semantic links/actions by replacing them with visual-only elements.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Code of Conduct
+
+Gessi follows the Contributor Covenant Code of Conduct.
+
+## Our Pledge
+
+We pledge to make participation in this project a respectful, harassment-free
+experience for everyone, regardless of age, body size, disability, ethnicity,
+sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+## Expected Behavior
+
+- Use welcoming and inclusive language.
+- Respect different viewpoints and experiences.
+- Accept constructive feedback gracefully.
+- Focus on what is best for the project and its users.
+- Show empathy toward other community members.
+
+## Unacceptable Behavior
+
+- Harassment, intimidation, or discrimination.
+- Trolling, insulting comments, or personal attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Conduct that would reasonably be considered inappropriate in a professional
+  setting.
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject comments, commits, code, issues,
+and other contributions that do not align with this Code of Conduct. Maintainers
+may also temporarily or permanently ban contributors for behavior they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Reporting
+
+Report concerns by opening a private channel with the project maintainer. Reports
+will be reviewed and handled as respectfully and privately as possible.
+

package/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to Gessi
+
+Thanks for helping improve Gessi. It is a dependency-free CSS and Web Component
+library built around plain HTML and progressive enhancement.
+
+Read [AGENTS.md](AGENTS.md) for the architecture, public API constraints, and
+repository map.
+
+## Development
+
+Work from the repository root:
+
+```bash
+npm run build
+npm run check
+npm run docs:build
+```
+
+Preview the documentation and examples:
+
+```bash
+npm run preview
+```
+
+Open `http://localhost:4173/docs/`.
+
+## CSS Guidelines
+
+- Keep public class names under the `gs-` prefix.
+- Prefer semantic components and composable primitives over utility-class
+  proliferation.
+- Keep style systems scoped through `data-gs-style`.
+- Keep the package usable from a CDN in plain HTML.
+- Preserve light DOM, SSR-safe imports, and no-JavaScript readability.
+- Respect `prefers-reduced-motion` for animations.
+
+## Pull Requests
+
+Before opening a pull request:
+
+```bash
+npm run build
+npm run check
+npm run docs:build
+npm pack --dry-run
+```
+
+Include screenshots or a short screen recording for visual changes.
+
+## Releases
+
+Releases are published manually to npm. Do not publish from a pull request.

package/README.md

@@ -1,33 +1,106 @@
 # gessi
 
-A tiny style kit for expressive HTML.
+[![npm](https://img.shields.io/npm/v/@pol-cova/gessi?color=15151f&label=npm)](https://www.npmjs.com/package/@pol-cova/gessi)
+[![license](https://img.shields.io/npm/l/@pol-cova/gessi?color=15151f)](LICENSE)
+[![documentation](https://img.shields.io/badge/docs-live-3468e8)](https://pol-cova.github.io/gessi/)
 
-Gessi gives plain HTML a little more rhythm without asking for classes,
-components, or build tooling. Drop in the stylesheet and write semantic markup.
+Gessi is a dependency-free CSS and Web Component library for expressive HTML,
+retro interfaces, and browser-based desktop environments.
 
-## Install
+It works directly in plain HTML from a CDN and also supports npm, static-site
+generators, server-rendered templates, and JavaScript frameworks.
 
-```bash
-npm install @pol-cova/gessi
-```
+[Documentation](https://pol-cova.github.io/gessi/) ·
+[Examples](https://pol-cova.github.io/gessi/examples/) ·
+[npm](https://www.npmjs.com/package/@pol-cova/gessi)
 
-## CDN
+## Quick start
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@pol-cova/gessi/dist/gessi.css">
+<script
+  type="module"
+  src="https://cdn.jsdelivr.net/npm/@pol-cova/gessi/dist/gessi.js"
+></script>
+
+<gessi-desktop menu="◆ My OS,File,View,Help" clock="09:41">
+  <gessi-window title="hello.html" width="38rem" active draggable>
+    <h1>One script, plain HTML</h1>
+    <p>No package manager, bundler, or framework required.</p>
+  </gessi-window>
+</gessi-desktop>
 ```
 
+The script registers the components and loads the stylesheet. For the earliest
+styled paint, include the CSS separately:
+
 ```html
-<link rel="stylesheet" href="https://unpkg.com/@pol-cova/gessi/dist/gessi.css">
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@pol-cova/gessi/dist/gessi.css"
+  data-gessi-styles
+>
 ```
 
-## Local usage
+## Install
+
+```bash
+npm install @pol-cova/gessi
+```
 
-```html
-<link rel="stylesheet" href="./dist/gessi.css">
+```js
+import "@pol-cova/gessi/css";
+import "@pol-cova/gessi/components";
 ```
 
+## What is included
+
+- Five visual systems: `neo`, `minimal`, `retro`, `old-tech`, and `classic-os`.
+- Desktop environments, draggable windows, nested windows, and dialogs.
+- Menus, toolbars, docks, breadcrumbs, tabs, trees, icons, and notifications.
+- Maps, markers, carousels, and composable image effects.
+- Responsive behavior that converts desktop layouts into readable mobile flow.
+- Light DOM, progressive enhancement, SSR-safe imports, and zero dependencies.
+- CSS primitives for cards, buttons, forms, layouts, badges, and content pages.
+
+The complete component API, attributes, keyboard controls, effects, and
+copy-ready recipes are available in the
+[interactive documentation](https://pol-cova.github.io/gessi/).
+
+## Examples
+
+- [Product OS](https://pol-cova.github.io/gessi/examples/product-os.html)
+- [Classic OS](https://pol-cova.github.io/gessi/examples/classic-os.html)
+- [Media OS](https://pol-cova.github.io/gessi/examples/media-os.html)
+- [Plain HTML](https://pol-cova.github.io/gessi/examples/standalone.html)
+- [CSS-only fallback](https://pol-cova.github.io/gessi/examples/no-js.html)
+
 ## Development
 
-The source file lives at `src/gessi.css`. The published CSS is copied to
-`dist/gessi.css`.
+```bash
+npm run build
+npm run check
+npm run docs:build
+npm run preview
+```
+
+Open `http://localhost:4173/docs/`.
+
+Source:
+
+```txt
+src/gessi.css
+src/components.js
+src/gessi.js
+```
+
+`npm run build` copies the public assets into `dist`. Pushes to `main` verify
+the package and deploy the documentation site to GitHub Pages.
+
+## Contributing
+
+Issues and pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md)
+before proposing public API changes.
+
+## License
+
+MIT. Departure Mono is included under its own MIT license.

package/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+## Supported Versions
+
+Gessi is early-stage. Security fixes target the latest published version.
+
+## Reporting a Vulnerability
+
+If you find a security issue, please do not open a public issue with exploit
+details.
+
+Instead, contact the maintainer privately through GitHub or npm. Include:
+
+- A short description of the issue.
+- Steps to reproduce it.
+- Any affected versions or CDN URLs.
+- Suggested fixes, if you have them.
+
+The maintainer will review the report and respond as soon as possible.
+