collective.fragmentsblock 1.0.0a2__tar.gz

collective_fragmentsblock-1.0.0a2/.copier-answers.yml

@@ -0,0 +1,14 @@
+# Do not edit this file manually.
+# This file is auto-generated by Copier.
+# Changes here will be overwritten when you update the template.
+_src_path: /home/dev/.copier-templates/plone-copier-templates/backend_addon
+author_email: md@derico.de
+author_name: Maik Derstappen
+github_organization: collective
+is_headless: false
+package_description: 'Aurora fragment block: reusable content fragments referenced
+    live from central fragment documents'
+package_name: collective.fragmentsblock
+package_title: Collective Fragmentsblock
+plone_version: '6.0'
+

collective_fragmentsblock-1.0.0a2/.editorconfig

@@ -0,0 +1,21 @@
+[*]
+charset = utf-8
+end_of_line = lf
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+
+[*.{cfg,ini,toml}]
+indent_size = 4
+
+[*.{xml,zcml,html,pt,zpt}]
+indent_size = 2
+
+[*.{css,js,json}]
+indent_size = 2
+
+[*.{yml,yaml}]
+indent_size = 2

collective_fragmentsblock-1.0.0a2/.github/workflows/ci.yml

@@ -0,0 +1,114 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      BLICCA_TOKEN: ${{ secrets.BLICCA_TOKEN }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      # plone.blicca.auroraeditor is PRIVATE and not on PyPI: it is the editor
+      # this block mounts in and the source of the rendering API the package
+      # imports, so without it nothing installs and nothing is tested. A
+      # missing token is a red job on purpose — a green run over a package
+      # that could not be installed says nothing.
+      - name: Require the host checkout token
+        if: env.BLICCA_TOKEN == ''
+        run: |
+          echo "::error::BLICCA_TOKEN is not set. This package depends on"
+          echo "::error::plone.blicca.auroraeditor, which is private and not"
+          echo "::error::on PyPI, so the tests cannot run."
+          exit 1
+
+      # pyproject resolves the sources below from `../<name>`, so this
+      # repository checks itself out into a subdirectory and its siblings land
+      # beside it, exactly as they sit under the site's `sources/`.
+      - uses: actions/checkout@v5
+        with:
+          path: collective.fragmentsblock
+
+      - uses: actions/checkout@v5
+        with:
+          repository: derico-de/plone.blicca.auroraeditor
+          token: ${{ env.BLICCA_TOKEN }}
+          path: plone.blicca.auroraeditor
+
+      - name: Set up uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run tests
+        working-directory: collective.fragmentsblock
+        run: uv run --frozen --extra test pytest -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Run ruff
+        run: uvx ruff@0.16.6 check .
+
+  bundle:
+    # The editor half is committed build output — there is no Node on the
+    # deploy host (block add-on contract §3.1) — so nothing rebuilds it at
+    # install time and it rots the moment someone edits bundle-src/src/ and
+    # forgets. The `git diff --exit-code` below is what makes committing an
+    # artifact safe rather than merely convenient.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      # pnpm is pinned here rather than by a `packageManager` field in
+      # bundle-src/package.json: pnpm 12 answers that field by writing a
+      # `packageManagerDependencies` block into the lockfile — its own binary
+      # for every platform — and the lockfile is not the place for that.
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 12.3.4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: bundle-src/.nvmrc
+          cache: pnpm
+          cache-dependency-path: bundle-src/pnpm-lock.yaml
+
+      # `working-directory`, not `--dir`: the repository root has no
+      # package.json, and pnpm resolves the workspace from where it stands.
+      - name: Install
+        run: pnpm install --frozen-lockfile
+        working-directory: bundle-src
+
+      - name: Build
+        run: pnpm build
+        working-directory: bundle-src
+
+      # After the build: the harness reads the built artifact.
+      - name: Test
+        run: pnpm test
+        working-directory: bundle-src
+
+      # If this fails, someone edited bundle-src/src/ and did not rebuild.
+      - name: The committed bundle is the one this source builds
+        run: git diff --exit-code -- src/collective/fragmentsblock/static/

collective_fragmentsblock-1.0.0a2/.gitignore

@@ -0,0 +1,97 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Type checkers / linters
+.mypy_cache/
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Translations (compiled catalogs are generated; .pot/.po are tracked)
+*.mo
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs / editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Node / frontend tooling (themes, mockup patterns, svelte apps)
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.pnpm-store/
+.parcel-cache/
+.vite/
+
+# Build outputs from frontend tooling (in addition to top-level dist/)
+src/collective/fragmentsblock/**/dist/
+src/collective/fragmentsblock/**/.cache/
+
+# Plone / Zope runtime data
+*.fs
+*.fs.index
+*.fs.lock
+*.fs.tmp
+blobs/
+
+# Project specific
+*.log
+.DS_Store
+Thumbs.db

collective_fragmentsblock-1.0.0a2/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

collective_fragmentsblock-1.0.0a2/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## 1.0.0a2 (2026-10-08)
+
+
+- Nothing changed yet.
+
+
+## 1.0.0a1 (2026-10-04)
+
+- The editor needs nothing from a provider add-on any more. The fragment
+  block's `install()` fetches the new `@fragments` service and registers
+  every provider's fragments before the first render; the host awaits it
+  (`plone.blicca.auroraeditor` 1.0.0a3, block-api 1.2, declared on the
+  record by upgrade step 1001). A theme ships its `fragments/*.html` and
+  the `fragments:folder` line, no editor bundle, no record, no rebuild.
+  `IFragmentsProvider` gains `records()`; a fragment's title is its
+  first-line `<!-- title: … -->` comment, else derived from the file name
+  (ADR 0002).
+
+- Add the `fragments:folder` ZCML directive. A provider add-on registers
+  its fragments folder with one line in `configure.zcml` and no Python
+  code. The folder is resolved relative to the package, checked at
+  startup, and registered under the package name unless `name` is given.
+
+- Register the `INonInstallable` utility that hides the uninstall profile.
+  `HiddenProfiles` was defined in `setuphandlers.py` but never registered in
+  `configure.zcml`, so it hid nothing: harmless while this package has no
+  upgrade profile, and a profile offered as an installable add-on of its own
+  the moment one is scaffolded.
+
+- A fragment block now **names itself with the fragment's title** while blocks
+  are dragged. The editor collapses the canvas to one row per block and reads
+  each row's identifying line off the rendered block — but a fragment is a
+  piece of a design and is often pure decoration with no text at all, so every
+  fragment row read "Fragment" against an empty line and two of them in one
+  page were indistinguishable exactly while being reordered. The view stamps
+  `data-block-summary` with the record's title (block add-on contract §1.6),
+  which is the same string the picker offers, so the row reads "Fragment —
+  Balkenlage (Trenner)". Editing affordance only: the attribute is inert on
+  the classic page, whose server-rendered markup does not carry it.
+
+- The fragment block's settings form now carries **block width** and
+  **background** — the two placement controls, offered because a fragment
+  is a piece of a design rather than a whole one: a contact box wants the
+  narrow column, a divider the full bleed, and the same file may want both
+  on two different pages. Both are Aurora style fields, so the editor and
+  the classic renderer stamp the class and custom properties on the block
+  wrapper generically — no change to either view component or to
+  `@@aurora-block-fragment`. Width defaults to `default`, the width
+  fragment blocks already rendered at, so existing content is unchanged;
+  the background slots are read from the host's registered palette and the
+  field is omitted on a host that registers none.
+
+- Initial release: the Aurora **fragment block** (`@type: fragment`) —
+  drop registered **design fragments** (static HTML files, typically cut
+  verbatim from a design mockup) into any Aurora-edited page. Aurora-first:
+  provider add-ons register `{id, title, html}` records into the shared
+  `@plone/registry` singleton from their install function
+  (`type: collective.fragmentsblock.fragment`); the block enumerates them
+  for its picker and renders the markup client-side, as-is, with optional
+  `${var}` substitution from the block's persisted `variables` mapping
+  (HTML-escaped, missing variables empty). Blicca classic pages render the
+  same file server-side via `@@aurora-block-fragment` and named
+  `IFragmentsProvider` utilities (`FragmentsFolder` reads
+  `<id>.html` files from a provider package directory) with identical
+  substitution semantics. Fail-soft placeholders everywhere; ships both
+  halves of the Blicca block add-on contract, with the committed editor
+  bundle built from `bundle-src/`
+  (`@plone-collective/aurora-fragment-block`). Variables render on both
+  surfaces but have no sidebar UI yet — see
+  `docs/adr/0001-fragments-are-registered-static-markup.md` for the design
+  and its deferred parts.

collective_fragmentsblock-1.0.0a2/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: collective.fragmentsblock
+Version: 1.0.0a2
+Summary: Aurora fragment block: static design fragments registered by add-ons, rendered as-is
+Project-URL: Homepage, https://github.com/collective/collective.fragmentsblock
+Project-URL: Documentation, https://github.com/collective/collective.fragmentsblock
+Project-URL: Repository, https://github.com/collective/collective.fragmentsblock.git
+Project-URL: Issues, https://github.com/collective/collective.fragmentsblock/issues
+Author-email: Maik Derstappen <md@derico.de>
+License: GPL-2.0-or-later
+Keywords: CMS,Plone
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Plone
+Classifier: Framework :: Plone :: 6.0
+Classifier: Framework :: Plone :: Addon
+Classifier: License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: plone-blicca-auroraeditor>=1.0.0a3
+Requires-Dist: plone-restapi
+Requires-Dist: plone>=6.0
+Provides-Extra: test
+Requires-Dist: plone-app-testing; extra == 'test'
+Requires-Dist: plone-testing; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-plone>=0.5.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# collective.fragmentsblock
+
+A **Fragment** block for the Aurora editor in [Plone](https://plone.org) Blicca.
+
+A fragment is a static piece of HTML, usually cut straight from the design
+mockup: a contact box, a seal, a call-to-action banner, a partner-logo
+strip. Your theme ships it as a file in a folder it registers with one line
+of ZCML. Editors then pick it from a list and drop it into a page. The
+markup is rendered exactly as it is in the file, both in the editor and on
+published pages.
+
+Editors never edit the markup. When the file changes, every page using the
+fragment updates on the next deployment.
+
+## Installation
+
+Add `collective.fragmentsblock` to your project dependencies and install it
+in the Plone add-ons control panel.
+
+Requirements: Plone 6, Python 3.10 or newer, and `plone.blicca.auroraeditor`
+1.0.0a3 or newer (block-api 1.2: the editor waits for this block to fetch its
+fragments before it renders).
+
+This package only provides the block. Fragments come from your own add-on,
+typically the theme package. See the next section.
+
+## Register a fragment
+
+Fragments live in a folder of your add-on, one HTML file per fragment. The
+server reads the files when it renders classic pages, and the editor fetches
+the same files from the server when it opens. Nothing is built, bundled or
+copied.
+
+```
+src/my/theme/
+├── fragments/
+│   ├── contact-box.html
+│   └── seal.html
+└── configure.zcml
+```
+
+The file name is the fragment id. Ids must match `^[A-Za-z0-9][A-Za-z0-9_-]*$`
+and are unique across the whole site, so prefix them if more than one
+add-on may provide fragments. A file whose name is not a valid id is skipped
+with a warning.
+
+Register the folder in your `configure.zcml`:
+
+```xml
+<!-- my/theme/configure.zcml -->
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:fragments="http://namespaces.plone.org/fragmentsblock">
+
+  <include package="collective.fragmentsblock" file="meta.zcml" />
+
+  <fragments:folder directory="fragments" />
+
+</configure>
+```
+
+`directory` is relative to your package. The folder is registered under
+your package name. Pass `name="..."` if you need another one. A folder that
+does not exist is an error at startup, not an empty picker.
+
+That is all. Restart Plone and the fragments appear in the picker.
+
+### Titles
+
+Editors pick a fragment by its title. Put it in a comment on the first line
+of the file:
+
+```html
+<!-- title: Contact box -->
+<aside class="contact-box">
+  ...
+</aside>
+```
+
+Without that comment the title is derived from the file name:
+`contact-box.html` becomes "Contact box", `partner_logos.html` becomes
+"Partner logos". The comment is part of the markup and is rendered with it;
+browsers ignore it.
+
+## Add a fragment to a page
+
+1. Open the page in the Aurora editor.
+2. Type `/` and choose **Fragment** from the slash menu.
+3. In the block settings, pick the fragment from the **Fragment** list.
+
+The fragment renders immediately. Two more settings control placement:
+
+- **Block width**: `narrow`, `default`, `layout` or `full`. Defaults to
+  `default`.
+- **Background**: a named colour slot from your theme's palette, such as
+  `Grey` or `Accent`. The field only appears if the theme registers a
+  palette.
+
+Both paint the block wrapper around the fragment, not the fragment itself.
+
+If a fragment's add-on gets uninstalled, the editor shows a note in place
+of the block and the published page renders nothing there. Pages never
+break.
+
+## Good to know
+
+- **Fragment HTML is trusted.** It ships with your add-on and is not
+  sanitised. A `<script>` in it runs on the published page.
+- **Variables.** Markup may contain `${name}` tokens. They are filled from
+  the block's `variables` mapping, HTML-escaped, with missing names
+  rendered empty. There is no editor UI for this yet. The mapping can be
+  set through the REST API or an upgrade step. For now, if a fragment
+  needs different values on different pages, ship one fragment per
+  variant.
+- **Wrapper.** Both the editor and the server wrap the markup in a
+  `<div class="block-fragment">`. Mockup HTML written for a grid or flex
+  parent needs to account for that.
+- **The editor fetches `@fragments`.** When the editor opens, the fragment
+  block requests `<site>/@fragments` with the session cookie and registers
+  what comes back before the first render. The list is every provider's
+  `records()`; where two providers use the same id, the one whose name sorts
+  first wins, on both surfaces. If the request fails, the block stays
+  available with an empty picker and existing fragment blocks say so instead
+  of rendering nothing.
+- **Other sources.** A folder of files is the stock provider. For anything
+  else, register a named utility that implements `IFragmentsProvider`:
+  `get(fragment_id)` returns the HTML or `None`, and `records()` lists every
+  fragment as `{"id", "title", "html"}`.
+- **Registering from JavaScript still works.** An Aurora add-on may register
+  fragments itself, with `registerFragment(config, {id, title, html})` from
+  the npm package `@plone-collective/aurora-fragment-block` or with a bare
+  `config.registerUtility` of type `collective.fragmentsblock.fragment`. The
+  server then needs a matching provider, or the fragment renders only in the
+  editor.
+
+## Development
+
+The editor half lives in `bundle-src/` and is built into the Python
+package's `static/` folder. The build output is committed.
+
+```shell
+cd bundle-src
+pnpm install
+pnpm build
+pnpm test
+```
+
+Python tests:
+
+```shell
+uv run --extra test pytest
+```
+
+## License
+
+GPLv2 for the Python package, MIT for the npm package.
+
+## Author
+
+Maik Derstappen, [derico.de](https://derico.de), <md@derico.de>

collective_fragmentsblock-1.0.0a2/README.md

@@ -0,0 +1,160 @@
+# collective.fragmentsblock
+
+A **Fragment** block for the Aurora editor in [Plone](https://plone.org) Blicca.
+
+A fragment is a static piece of HTML, usually cut straight from the design
+mockup: a contact box, a seal, a call-to-action banner, a partner-logo
+strip. Your theme ships it as a file in a folder it registers with one line
+of ZCML. Editors then pick it from a list and drop it into a page. The
+markup is rendered exactly as it is in the file, both in the editor and on
+published pages.
+
+Editors never edit the markup. When the file changes, every page using the
+fragment updates on the next deployment.
+
+## Installation
+
+Add `collective.fragmentsblock` to your project dependencies and install it
+in the Plone add-ons control panel.
+
+Requirements: Plone 6, Python 3.10 or newer, and `plone.blicca.auroraeditor`
+1.0.0a3 or newer (block-api 1.2: the editor waits for this block to fetch its
+fragments before it renders).
+
+This package only provides the block. Fragments come from your own add-on,
+typically the theme package. See the next section.
+
+## Register a fragment
+
+Fragments live in a folder of your add-on, one HTML file per fragment. The
+server reads the files when it renders classic pages, and the editor fetches
+the same files from the server when it opens. Nothing is built, bundled or
+copied.
+
+```
+src/my/theme/
+├── fragments/
+│   ├── contact-box.html
+│   └── seal.html
+└── configure.zcml
+```
+
+The file name is the fragment id. Ids must match `^[A-Za-z0-9][A-Za-z0-9_-]*$`
+and are unique across the whole site, so prefix them if more than one
+add-on may provide fragments. A file whose name is not a valid id is skipped
+with a warning.
+
+Register the folder in your `configure.zcml`:
+
+```xml
+<!-- my/theme/configure.zcml -->
+<configure
+    xmlns="http://namespaces.zope.org/zope"
+    xmlns:fragments="http://namespaces.plone.org/fragmentsblock">
+
+  <include package="collective.fragmentsblock" file="meta.zcml" />
+
+  <fragments:folder directory="fragments" />
+
+</configure>
+```
+
+`directory` is relative to your package. The folder is registered under
+your package name. Pass `name="..."` if you need another one. A folder that
+does not exist is an error at startup, not an empty picker.
+
+That is all. Restart Plone and the fragments appear in the picker.
+
+### Titles
+
+Editors pick a fragment by its title. Put it in a comment on the first line
+of the file:
+
+```html
+<!-- title: Contact box -->
+<aside class="contact-box">
+  ...
+</aside>
+```
+
+Without that comment the title is derived from the file name:
+`contact-box.html` becomes "Contact box", `partner_logos.html` becomes
+"Partner logos". The comment is part of the markup and is rendered with it;
+browsers ignore it.
+
+## Add a fragment to a page
+
+1. Open the page in the Aurora editor.
+2. Type `/` and choose **Fragment** from the slash menu.
+3. In the block settings, pick the fragment from the **Fragment** list.
+
+The fragment renders immediately. Two more settings control placement:
+
+- **Block width**: `narrow`, `default`, `layout` or `full`. Defaults to
+  `default`.
+- **Background**: a named colour slot from your theme's palette, such as
+  `Grey` or `Accent`. The field only appears if the theme registers a
+  palette.
+
+Both paint the block wrapper around the fragment, not the fragment itself.
+
+If a fragment's add-on gets uninstalled, the editor shows a note in place
+of the block and the published page renders nothing there. Pages never
+break.
+
+## Good to know
+
+- **Fragment HTML is trusted.** It ships with your add-on and is not
+  sanitised. A `<script>` in it runs on the published page.
+- **Variables.** Markup may contain `${name}` tokens. They are filled from
+  the block's `variables` mapping, HTML-escaped, with missing names
+  rendered empty. There is no editor UI for this yet. The mapping can be
+  set through the REST API or an upgrade step. For now, if a fragment
+  needs different values on different pages, ship one fragment per
+  variant.
+- **Wrapper.** Both the editor and the server wrap the markup in a
+  `<div class="block-fragment">`. Mockup HTML written for a grid or flex
+  parent needs to account for that.
+- **The editor fetches `@fragments`.** When the editor opens, the fragment
+  block requests `<site>/@fragments` with the session cookie and registers
+  what comes back before the first render. The list is every provider's
+  `records()`; where two providers use the same id, the one whose name sorts
+  first wins, on both surfaces. If the request fails, the block stays
+  available with an empty picker and existing fragment blocks say so instead
+  of rendering nothing.
+- **Other sources.** A folder of files is the stock provider. For anything
+  else, register a named utility that implements `IFragmentsProvider`:
+  `get(fragment_id)` returns the HTML or `None`, and `records()` lists every
+  fragment as `{"id", "title", "html"}`.
+- **Registering from JavaScript still works.** An Aurora add-on may register
+  fragments itself, with `registerFragment(config, {id, title, html})` from
+  the npm package `@plone-collective/aurora-fragment-block` or with a bare
+  `config.registerUtility` of type `collective.fragmentsblock.fragment`. The
+  server then needs a matching provider, or the fragment renders only in the
+  editor.
+
+## Development
+
+The editor half lives in `bundle-src/` and is built into the Python
+package's `static/` folder. The build output is committed.
+
+```shell
+cd bundle-src
+pnpm install
+pnpm build
+pnpm test
+```
+
+Python tests:
+
+```shell
+uv run --extra test pytest
+```
+
+## License
+
+GPLv2 for the Python package, MIT for the npm package.
+
+## Author
+
+Maik Derstappen, [derico.de](https://derico.de), <md@derico.de>

collective_fragmentsblock-1.0.0a2/bundle-src/.nvmrc

@@ -0,0 +1 @@
+24