qss 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8e93da5bd3a65eb8804f5416a1a0315f23110bb6027703c71974b7fa4443d73
+  data.tar.gz: d00e38e05740739f64aff39d17f491558f76a0556ec71abaa7781c278059c60c
+SHA512:
+  metadata.gz: dc74ce934ef4007d538d184b46822b89bbb3e6ee1c0a2ff90900ae69729434e5413dac0380c33976ae2ba43cf01a9a30e6b67140f4055fdadf758781b31f7be1
+  data.tar.gz: aa18e0742c0dfc5bb26067fed5dff96f52b28f0e495634b9aac87e1ead4ed60ae5124cae80b12f5b4fce43f44f2a06f7d8f71f2f7c8e99f0c68b3147f4799931

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to the qss gem. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [Semantic Versioning](https://semver.org/) (before 1.0, minor versions may break the API).
+
+## [0.1.0] - unreleased
+
+First release, extracted from the Parapet project.
+
+### Added
+- Core stylesheet (`qss/qss_core.scss`, compiled `qss/qss_core.css`): utilities on a 1000-unit canvas grid; the unit
+  (`--qnt`, canvas width / 1000) computed by CSS alone (`0.1cqw` of the canvas; the viewport width outside one).
+- Base reset for QSS actors at the canvas id's weight only, so every core utility applies without the JS engine.
+- Neutral `!default` SCSS settings (`qss/_qss_defaults.scss`); a project sets its own before importing core.
+- Optional runtime engine (`qss/qss-engine.js`): rules for uncovered bracket classes, measured element edges.
+- `QSS::QssNativeAuditor`: id grammar (`{qualifier}-{baseObject}`, `QSSObject` custom types) with a per-project
+  registry, `qss-function` / `qss-relation` attributes, explicit dimensions for every actor, unit rules (no raw CSS
+  lengths on QSS structure; rem or % only in foreign content), `!important`, z-index and inline-style checks.
+- `QSS::QssAuditor`: the older class-whitelist auditor.
+- `QSS.configure(root:, config:)`: a project's settings read at runtime; paths resolve against its root.
+- `QSS::Blueprints` (`QSS.grid`, `QSS.object`): layout arithmetic and object blueprints.
+- `QSS::Engine`: Rails engine for the asset pipeline, loaded only when Rails is present.
+- `qss-sync`: writes a project's SCSS settings (`--core` regenerates the gem's own generated sections).
+- `qss-core-render-check`: renders the compiled CSS alone in headless Chrome and checks core utilities.

data/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing to QSS
+
+Thank you for helping. Issues and pull requests live at https://bitbucket.org/kmf2/qss.
+
+## Reporting a bug
+
+Please include the QSS version, Ruby (and Rails) version, the smallest markup that shows the problem, and what the
+auditor or browser did versus what you expected.
+
+## Changing code
+
+1. `bundle install`
+2. Make the change, with a spec for it under `spec/`.
+3. Run `bundle exec rake` (RuboCop, then the render check) and `bundle exec rspec`; all must pass.
+4. If you changed `config/grammar.yml`, run `bundle exec rake sync` and commit the regenerated sections. Never edit
+   between the `QSS-GENERATED-BEGIN` / `QSS-GENERATED-END` markers by hand.
+5. If you changed `app/assets/stylesheets/qss/qss_core.scss`, run `bundle exec rake compile` and commit
+   `qss_core.css`.
+6. Add a line to the Unreleased section of `CHANGELOG.md`.
+
+QSS keeps layout readable from source: a change that makes a layout depend on rendering, on JavaScript, or on a
+second coordinate system needs a strong reason, stated in the pull request.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the MIT License.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Kraig Fairhurst
+
+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.

data/QSS-MANIFESTO.md

@@ -0,0 +1,61 @@
+# QSS: Quantized Spatial Styling Manifesto
+## Version 1.2 — "Semantic Object Architecture"
+
+### 1. The Core Philosophy
+QSS is NOT a CSS framework. It is a **Spatial Operating System** for the browser. 
+
+Traditional CSS treats the web as a "Document Stream" where elements flow like ink on paper. This is inherently non-deterministic and difficult for AI Agents to reason about without querying the computed DOM.
+
+**QSS rejects flow.** It treats the screen as a 1000-unit 2D CAD canvas. Every element has a mathematical origin and a predictable footprint.
+
+### 2. The Deterministic Stack
+To ensure isolation and predictable rendering, QSS requires the **Safety Trio**:
+
+1.  **Stage (`#qss-canvas`)**: The relative-positioned root. All spatial math is relative to this origin.
+2.  **Wrapper (`#qss-wrapper`)**: Enforces viewport boundaries and provides a "Safety Gutter."
+3.  **Noun (`id="..."`)**: The unique Identity. Every "Object" on the canvas is a Noun defined by its ID.
+4.  **Actor (`.qss`)**: The mandatory base class (The DNA). It enforces `position: absolute` and a "Nuclear Reset."
+
+### 3. Grammar: The "Adjective" System
+Adjectives define the traits, positioning, and state of a Noun.
+
+1.  **Atomic Adjectives** (Classes): `.[prop]\[[val]]` pattern (e.g., `.qss-pos-x[500]`).
+2.  **Parametric Adjectives** (Composite Classes): `.[NounType]\[[p1]|[p2]|...]` pattern.
+
+### 4. Semantic Object Registry & Blueprints
+Version 1.2 introduces **Parametric Blueprints**. While the `id` is the Noun (Identity), the blueprint class (e.g., `.qss-Button`) is a **Composite Adjective** that applies a pre-defined set of traits from `qss-objects.json`.
+
+- **Intrinsic Defaults**: Using `.qss-Button` applies the `intrinsic` dimensions defined in the registry.
+- **Parametric Overrides**: Using `.qss-Button[200|80]` overrides specific dimensions (Width | Height) JIT.
+
+#### Example: Parametric Dropdown Blueprint
+```json
+{
+  "name": "Dropdown",
+  "params": ["w", "h", "row_height"],
+  "intrinsic": { "w": 200, "h": 40 },
+  "slots": [
+    { "name": "header", "pos": [0, 0] },
+    { "name": "list", "pos": [0, 42], "h": "computed" }
+  ]
+}
+```
+
+### 5. Deterministic Helpers (Ruby/JS)
+QSS provides a **Grid Generator** that allows Agents to "stamp" complex layouts without visual checks.
+
+```ruby
+# Ruby instantiation
+<% qss.grid(31, cols: 7, w: 100, h: 100).each do |day| %>
+  <div class="qss qss-pos-x[<%= day.x %>] qss-pos-y[<%= day.y %>]">...</div>
+<% end %>
+```
+
+### 6. Installation
+1. Copy `qss_core.scss` and `_qss_variables.scss` to your stylesheets.
+2. Include `qss-engine.js` for client-side transpilation.
+3. Configure `qss.config.json` with your project palette.
+4. (Optional) Copy `qss.rb` to your `lib/` for server-side spatial math.
+
+---
+*Mathematically Audited. Agent Aware. Deterministic by Design.*

data/README.md

@@ -0,0 +1,159 @@
+# QSS: Quantized Spatial Styling
+
+QSS is a CSS layout framework built so that both people and AI agents can read a layout from its source, without
+rendering it. Layout is placed and sized on a 1000-unit grid across a **canvas** element: one **qnt** is one
+thousandth of the canvas width, computed by CSS alone. QSS ships compiled CSS, its SCSS sources, an optional
+JavaScript engine, and two **auditors** that check views against QSS's rules. It includes a Rails engine for the
+asset pipeline; the auditors and configuration also work in plain Ruby.
+
+> **Status: 0.1.0, early.** QSS was extracted from the Parapet project (a Rails development tool),
+> which is its first consumer. Expect names and APIs to change before 1.0. See [CHANGELOG.md](CHANGELOG.md).
+> Why QSS is designed this way: [docs/DESIGN_HISTORY.md](docs/DESIGN_HISTORY.md).
+
+## Vocabulary
+
+- **Canvas**: the element QSS measures against, `<div id="qss-canvas">` by default.
+- **Actor**: an element with class `qss` inside the canvas. Actors declare their size; QSS's reset keeps them from
+  shrinking or growing implicitly.
+- **qnt**: the QSS unit, `canvas width / 1000`. `w[240]` means 240 qnt wide: 24% of the canvas, at any screen size.
+- **Noun, adjective, attribute**: an element's `id` is its noun (its identity), its classes are adjectives (its
+  traits), and `qss-function` / `qss-relation` are QSS attributes. See [QSS-MANIFESTO.md](QSS-MANIFESTO.md).
+- **Foreign content**: anything inside class `foreign` (or `qss-payload-override`) is left to ordinary CSS.
+
+## Installation (Rails)
+
+```ruby
+# Gemfile
+gem "qss"
+```
+
+The gem's Rails engine puts QSS's assets on your asset pipeline (`qss/qss_core.css`, `qss/qss_core.scss`,
+`qss/qss-engine.js`).
+
+### Markup
+
+An id is `{qualifier}-{baseObject}`: the base object is an HTML tag, the qualifier says which one. A qualifier is
+declared once in your registry, recording what it adds to its base. Structural frames (`nav`, `main`, ...) carry
+`contain-layout`.
+
+```erb
+<div id="qss-canvas">
+  <nav id="main-nav" class="qss anchored contain-layout w[200] h-full"> ... </nav>
+  <section id="content-section" class="qss anchored contain-layout w[800] h-full"> ... </section>
+</div>
+```
+
+```yaml
+# config/qss_registry.yml (auditor.registry_path in your config, below)
+types:
+  main-nav:
+    extends: nav
+  content-section:
+    extends: section
+```
+
+This example audits green with `QSS::QssNativeAuditor` (below).
+
+### Stylesheet: neutral defaults
+
+```erb
+<%= stylesheet_link_tag "qss/qss_core" %>
+```
+
+### Stylesheet: with your own settings
+
+Set your values first, then import core; core's settings are `!default`, so yours win. Put
+`QSS.stylesheets_path` on your Sass load path so `qss/qss_core` resolves:
+
+```scss
+// app/assets/stylesheets/application.scss
+@import "qss_variables";   // generated from your config by qss-sync (below)
+@import "qss/qss_core";
+```
+
+```ruby
+Sass.compile("app/assets/stylesheets/application.scss",
+             load_paths: ["app/assets/stylesheets", QSS.stylesheets_path])
+```
+
+### The JavaScript engine (optional)
+
+The compiled CSS works on its own. The engine adds rules at runtime for bracket classes the compiled CSS does not
+cover, and exports measured element edges as CSS variables:
+
+```erb
+<%= javascript_include_tag "qss/qss-engine", defer: true %>
+<script>
+  document.addEventListener("DOMContentLoaded", () => { QSSEngine.startPulse(); QSSEngine.startObserver(); });
+</script>
+```
+
+## Configuration
+
+QSS starts neutral. A project declares its own settings in one YAML file and tells QSS where it is:
+
+```ruby
+# config/initializers/qss.rb
+QSS.configure(root: Rails.root, config: "config/qss_config.yml")
+```
+
+```yaml
+# config/qss_config.yml -- every key is optional; see the gem's config/grammar.yml for the defaults
+config:
+  portal_root: "#overlay-root"      # overlays render here; "" = rules scoped to the canvas only
+  palette:
+    brand-main: "#0f1115"
+  group_names: [menu]               # named groups for group-*:hover style classes
+auditor:
+  id_prefix: "app-"                  # optional project id prefix
+  registry_path: "config/qss_registry.yml"
+sync_targets:
+  variables: app/assets/stylesheets/_qss_variables.scss
+```
+
+Relative paths resolve against the declared `root`, never the working directory.
+
+### Generating your SCSS settings
+
+```sh
+QSS_CONSUMER_CONFIG=config/qss_config.yml bundle exec qss-sync
+```
+
+This writes your `_qss_variables.scss` (the `sync_targets.variables` path). Without `QSS_CONSUMER_CONFIG` it reads
+`config/qss_config.yml` from the current directory.
+
+## Auditing views
+
+```ruby
+result = QSS::QssNativeAuditor.audit_file("app/views/layouts/application.html.erb")
+result[:status] # => "green", "orange" or "red"
+result[:issues] # => [{ type:, message:, severity: }, ...] (plus code: on most identity and unit findings)
+```
+
+RED means a rule is violated: fix the markup, or reconsider the rule. ORANGE is a judgment call. Examples of rules:
+every actor declares its width and height (or opts out with `qss-content-driven`); structure carries no raw CSS
+lengths (sizes are in qnt or canvas percentages); no `!important`; ids follow the `{qualifier}-{baseObject}`
+grammar. `QSS::QssAuditor` is the older class-whitelist auditor: it predates the bracket vocabulary (it reports
+`w[200]` as unknown) and is kept for projects that still use its whitelist.
+
+## Requirements
+
+- Ruby 3.2 or newer. Rails is optional (needed only for the asset-pipeline engine).
+- A current browser with CSS container query units (`cqw`), `@property` and `:where()`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec          # the test suite (plain Ruby)
+bundle exec rake rubocop   # lint
+bundle exec rake compile   # rebuild app/assets/stylesheets/qss/qss_core.css
+bundle exec rake sync      # regenerate the generated sections from config/grammar.yml
+bundle exec rake render_check   # render qss_core.css alone in headless Chrome (needs selenium-webdriver)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [MIT-LICENSE](MIT-LICENSE).