inklet 4.0.0.dev9__tar.gz → 4.0.0.dev11__tar.gz

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/.github/workflows/publish.yml

@@ -6,7 +6,7 @@ on:
       tag:
         description: Published GitHub release tag
         required: true
-        default: v4.0.0.dev9
+        default: v4.0.0.dev11
         type: string
       dry_run:
         description: Validate release files without uploading to PyPI
@@ -43,7 +43,7 @@ jobs:
           RELEASE_TAG: ${{ inputs.tag }}
         run: |
           [[ "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(\.dev[0-9]+)?$ ]] || {
-            echo 'Expected a stable or development tag such as v3.1.0 or v4.0.0.dev9' >&2
+            echo 'Expected a stable or development tag such as v3.1.0 or v4.0.0.dev11' >&2
             exit 1
           }
           gh release view "$RELEASE_TAG" --json isDraft,isPrerelease > "$RUNNER_TEMP/release.json"

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 4.0.0.dev11 — 2026-09-12
+
+Eleventh development preview: unified composition layout, labels and appearance.
+3.1.0 remains the stable release.
+
+- Add supported keyed line/marker styles, text/callout appearance and module box
+  styles to the local composition editor, using the same Python compiler.
+- Organize controls into Layout, Labels and Styles. Apply changes across sections
+  as one atomic edit with shared undo/redo, reset and saved-state reconstruction.
+- Save typed named appearance decisions in schema 0.4, accepting legacy 0.1–0.3
+  files. Explicit null style fields remove authored keywords for automatic styling.
+- Preserve data-driven marker sizes and colours; report incompatible style targets
+  after source revisions while retaining compatible label/layout edits on discard.
+- Cover combined browser edits, two-width SVG/PDF agreement, inherited styles,
+  text remeasurement, live data and alias reconciliation; update illustrated docs.
+
+## 4.0.0.dev10 — 2026-09-12
+
+Tenth development preview: reproducible named label and callout editing.
+3.1.0 remains the stable release.
+
+- Edit string module captions, text components, keyed plot titles/text/callouts
+  and named composition annotations in the local layout editor.
+- Expose callout text, preferred side, physical clearance and leader visibility;
+  remeasure content and dependent connections through the Python compiler.
+- Save typed label identities and changed fields in layout schema 0.3, accepting
+  legacy 0.1/0.2 files, undo/redo, independent copies and shared definitions.
+- Report removed or incompatible labels individually; explicit discard preserves
+  compatible edits on the same object. Leave unedited source decisions live.
+- Add browser controls, source revision and two-width SVG/PDF roundtrip checks,
+  installed-package coverage and an illustrated guide and example.
+
 ## 4.0.0.dev9 — 2026-09-12
 
 Ninth development preview: mouse movement and proportional artwork scaling.

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: inklet
-Version: 4.0.0.dev9
+Version: 4.0.0.dev11
 Summary: Scientific figures with live data, measured layout, and consistent vector exports.
 Project-URL: Repository, https://github.com/Mapika/inklet
 Project-URL: Documentation, https://inklet.readthedocs.io/en/latest/
@@ -81,16 +81,16 @@ their signatures and report schemas may change.
 
 ## 4.0 development preview
 
-**4.0.0.dev9** adds mouse movement and proportional artwork scaling to the
-local layout editor. Drag named objects and groups, use corner handles, undo
-gestures, and save choices that reproduce through the Python compiler.
+**4.0.0.dev11** connects layout, label and appearance editing in the local
+composition editor. Adjust supported plot, text and module styles alongside
+layout, undo changes together, and save choices that reproduce through Python.
 ```sh
-python -m pip install "inklet==4.0.0.dev9"
+python -m pip install "inklet==4.0.0.dev11"
 ```
 
 [Preview guide and examples](https://inklet.readthedocs.io/en/latest/development-preview/) ·
 [4.0 roadmap](https://inklet.readthedocs.io/en/latest/roadmap/) ·
-[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev9)
+[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev11)
 
 This is an opt-in development release. Experimental APIs and saved-state schemas
 may change; 3.1.0 remains the stable release. General browser editing,

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/README.md

@@ -31,16 +31,16 @@ their signatures and report schemas may change.
 
 ## 4.0 development preview
 
-**4.0.0.dev9** adds mouse movement and proportional artwork scaling to the
-local layout editor. Drag named objects and groups, use corner handles, undo
-gestures, and save choices that reproduce through the Python compiler.
+**4.0.0.dev11** connects layout, label and appearance editing in the local
+composition editor. Adjust supported plot, text and module styles alongside
+layout, undo changes together, and save choices that reproduce through Python.
 ```sh
-python -m pip install "inklet==4.0.0.dev9"
+python -m pip install "inklet==4.0.0.dev11"
 ```
 
 [Preview guide and examples](https://inklet.readthedocs.io/en/latest/development-preview/) ·
 [4.0 roadmap](https://inklet.readthedocs.io/en/latest/roadmap/) ·
-[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev9)
+[Release notes](https://github.com/Mapika/inklet/releases/tag/v4.0.0.dev11)
 
 This is an opt-in development release. Experimental APIs and saved-state schemas
 may change; 3.1.0 remains the stable release. General browser editing,

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/docs/api.md

@@ -225,12 +225,12 @@ A figure assembled from named children and measured expressions.
 * `instantiate(**items)` -- Create an independent recipe, filling required slots and replacing defaults.
 * `configure(*, width=None, height=None, unit=None, fit_top=None)` -- Atomically update authored page dimensions or coordinate units.
 * `place(name, **placement)` -- Edit a child's placement without replacing its content or named links.
-* `layout_overrides(reference)` -- Capture changed placements and page fields against a matching reference.
+* `layout_overrides(reference)` -- Capture changed layout, named labels and supported styles against a reference.
 * `with_layout_overrides(value, *, missing='error')` -- Return an independent edited recipe and a reconciliation report.
 * `port(name, target)` -- Expose a child's name:anchor as a reusable composition attachment point.
 * `constrain(value, *, minimum=0, message='composition needs more space')` -- Require an expression to meet a minimum; fail before drawing.
 * `link(source, target, **options)` -- Route a branch or return between named children (`name:port`).
-* `annotate(target, text, **options)` -- Place a measured callout after every child and connection exists.
+* `annotate(target, text, **options)` -- Place a measured callout; a unique name enables saved label editing.
 * `signature(trail=())`
 * `render(context, width=None, height=None)`
 

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/docs/development-preview.md

@@ -1,6 +1,6 @@
-# Inklet 4.0.0.dev9
+# Inklet 4.0.0.dev11
 
-The ninth 4.0 development release includes the linked plotting, mapping,
+The eleventh 4.0 development release includes the linked plotting, mapping,
 engineering and scientific workflows developed since 3.1.0. It is an installable
 snapshot for trying real examples and reporting problems. **3.1.0 remains the
 stable release.** The [4.0 roadmap](roadmap.md) still has open work.
@@ -8,7 +8,7 @@ stable release.** The [4.0 roadmap](roadmap.md) still has open work.
 ```sh
 python -m venv .venv
 source .venv/bin/activate
-python -m pip install "inklet==4.0.0.dev9"
+python -m pip install "inklet==4.0.0.dev11"
 ```
 
 On Windows PowerShell, activate with `.venv\Scripts\Activate.ps1` instead.
@@ -19,9 +19,9 @@ stable releases; see its [installation documentation](https://pip.pypa.io/en/sta
 Optional extras can be installed with the same pin:
 
 ```sh
-python -m pip install "inklet[render,pandas,polars]==4.0.0.dev9"
+python -m pip install "inklet[render,pandas,polars]==4.0.0.dev11"
 # Add calibrated volumes and TIFF workflows when needed:
-python -m pip install "inklet[volume,render]==4.0.0.dev9"
+python -m pip install "inklet[volume,render]==4.0.0.dev11"
 ```
 
 The core preview needs no browser server, NumPy, pandas, Polars or Blender.
@@ -29,7 +29,46 @@ Opening the generated HTML requires a browser. PNG/PDF exports from browser
 figures use separate Chrome/Chromium and Pillow; native Diagram exports retain
 their existing requirements. See [installation](installation.md).
 
-## Mouse movement and scaling in dev9
+## Unified composition authoring in dev11
+
+The [composition editor](layout-editor.md#edit-appearance-alongside-layout) now
+combines Layout, Labels and Styles sections. Pending changes across sections
+compile together as one undo step, with one saved file and matching SVG/PDF
+exports. Supported appearance controls cover keyed lines and markers, text and
+callouts, and module boxes. Text sizes remeasure dependent layout and ports.
+
+![Named plot styles in the composition editor](assets/guides/layout-editor-styles.png)
+
+Only constant marker colours and diameters are editable; data-driven fields
+remain attached to their sources. A source revision that changes an edited
+constant into a data mapping reports an incompatible style target. Explicit
+discard retains compatible layout and labels on the same object.
+
+Schema 0.4 adds typed named style decisions and explicit removal of style
+keywords. Schemas 0.1, 0.2 and 0.3 still load. The separate linked-table editor
+keeps its own format; arbitrary paint editing and general cross-content object
+relationships remain open.
+
+## Named labels and callouts retained from dev10
+
+The [local layout editor](layout-editor.md#edit-labels-and-callouts) now edits
+string module captions, text components, keyed plot titles/text/callouts and
+named composition annotations. Callouts expose preferred side, physical
+clearance and leader visibility. Text changes remeasure content and update
+dependent layout and connections through Python.
+
+Saved choices contain explicit label keys and kinds. Reordering instructions
+preserves identity; removing a key or changing its kind reports an incompatible
+label. Explicit discard retains compatible edits on the same object. Shared
+definitions share text decisions, while unedited source fields remain live.
+
+![Named callout controls and the compiled figure](assets/guides/layout-editor-labels.png)
+
+Dev10 introduced layout schema 0.3 for labels; schemas 0.1 and 0.2 still load. Undo/redo,
+reopening and matching SVG/PDF export include text edits. Axis labels, individual
+callout dragging, camera editing and general object relationships remain open.
+
+## Mouse movement and scaling retained from dev9
 
 The [layout editor](layout-editor.md) now supports direct mouse movement and
 proportional corner scaling of named objects and groups. Alt-click selects a
@@ -44,7 +83,7 @@ retain their separate typography-preserving layout behavior.
 
 ![Mouse selection and proportional scaling in the local editor](assets/guides/layout-editor-gestures.png)
 
-New layout files use schema 0.2 for explicit artwork scale. Dev7/dev8 schema 0.1
+Dev9 introduced schema 0.2 for explicit artwork scale. Dev7/dev8 schema 0.1
 files still load. Named composition objects are editable; individual plot marks,
 axis labels, connector segments and camera parameters remain outside this scope.
 
@@ -63,8 +102,8 @@ remain consistent across repeated edits and resets.
 
 ![The local browser layout inspector](assets/guides/layout-editor.png)
 
-This inspector requires its local Python session. It covers composition layout;
-label content, individual plot marks and cameras remain separate work.
+This inspector requires its local Python session. Named label editing is added
+in dev10; individual plot marks and cameras remain separate work.
 The existing standalone viewers and linked-plot appearance editor retain their
 current scope.
 
@@ -181,7 +220,7 @@ The wheel contains the library. To obtain recipes and fixtures, use the matching
 release checkout or source archive:
 
 ```sh
-git clone --branch v4.0.0.dev9 https://github.com/Mapika/inklet.git
+git clone --branch v4.0.0.dev11 https://github.com/Mapika/inklet.git
 cd inklet
 python -m pip install -e '.[render]'
 python examples/v4/regional_report.py --renderer compiled --editor --output out/regional

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/docs/layout-editor.md

@@ -1,6 +1,6 @@
 # Local layout editor
 
-Available since **4.0.0.dev8**, with mouse gestures in **4.0.0.dev9**, under `inklet.experimental.layout_editor`. Adjust
+Available since **4.0.0.dev8**, with mouse gestures in **4.0.0.dev9**, named label editing in **4.0.0.dev10**, and unified style controls in **4.0.0.dev11**, under `inklet.experimental.layout_editor`. Adjust
 named placements and dimensions in a browser while Python recompiles the
 actual composition. The preview and downloaded SVG/PDF come from the same
 compiled figure, including plots, nested diagrams and native 3D content.
@@ -75,10 +75,101 @@ marks, ticks, axis labels and connector segments remain part of their owning
 plot or diagram. Scaling and movement do not remove authored constraints or
 top-fitting behavior; dependent content can reflow when the compiler rebuilds.
 
+## Edit labels and callouts
+
+![Editing a named plot callout with text, side, clearance and leader controls](assets/guides/layout-editor-labels.png)
+
+Select a composition child, choose **Labels** in **Edit**, then change its fields and choose **Apply
+changes**. The editor supports text components created with `component(i.text,
+...)`, string module captions, and plot `title`, `text` and `annotate`
+instructions with an explicit string `key`. For composition callouts, supply a
+unique `name` and select the composition that owns the callout.
+
+```python
+recipe['chart'].annotate(1, 2, 'Reference observation', key='observation', side='s', clear=4)
+recipe.annotate('caption', 'Measured response', name='response-note', side='e', clear=3)
+editor.command('refresh')
+editor.command('edit', {
+    'path': '/chart',
+    'labels': {'observation': {'kind': 'plot-annotate', 'text': 'Reviewed observation', 'side': 'sw'}},
+})
+```
+
+Callouts expose their preferred compass side, clearance in physical millimetres,
+and leader visibility. Automatic placement can choose another side to avoid
+conflicts. Plot clearance can be left blank to use its automatic value. This
+increment edits callout content and placement preferences; it does not add free
+mouse dragging of individual callouts or axis-label editing.
+
+A label's identity is its composition path, explicit key and kind. For example,
+`/chart` plus `observation` identifies a plot annotation even when its instruction
+moves in the recipe. Replacing that key with a different instruction kind is an
+incompatible target. A removed or incompatible label is reported as
+`/chart#observation`; explicit discard drops that label's edits while retaining
+compatible placement and label edits on the same chart. Renaming a path or key
+changes its identity. Reusing the same key and kind declares the same label.
+
+Text changes are measured by the Python compiler: longer module captions can
+move dependent modules and reroute their connections. Unedited labels, data
+coordinates, styling and other source choices remain live. Shared definitions
+share label edits; use an independent recipe copy for independent captions.
+Undo/redo, reset, saved JSON and SVG/PDF exports include the label edits.
+
+## Edit appearance alongside layout
+
+![Named line and marker styles edited in the composition inspector](assets/guides/layout-editor-styles.png)
+
+Choose **Styles** in **Edit**. Layout, Labels and Styles retain their pending
+changes when switching sections; **Apply changes** compiles them together as
+one undo step. Selecting another content target discards unapplied fields.
+
+| Named content | Available appearance controls |
+| --- | --- |
+| Keyed plot `line` instructions | Stroke colour, physical line width, opacity |
+| Keyed plot `scatter` instructions | Constant colour and diameter, opacity |
+| Text components and string module captions | Fill colour and physical text size |
+| Module boxes | Fill, stroke colour and physical line width |
+| Keyed plot `text`/`annotate` and named composition callouts | Fill colour and physical text size |
+
+Colours accept the colour parser's hex, RGB and named CSS forms; `none` also
+works for fill and stroke. Opacity ranges from 0 to 1. Widths use millimetres;
+marker size is **diameter**, and text size must be positive. Blank style fields
+remove an explicit keyword and use the renderer's automatic/preset behaviour.
+That removal is saved as JSON `null`. **Reset target** instead restores the
+current source's layout, labels and styles together. Parent artwork scaling
+still scales the resulting text and strokes.
+
+```python
+editor.command('edit', {
+    'path': '/caption',
+    'placement': {'x': 18},
+    'labels': {'label': {'kind': 'module-label', 'text': 'Reviewed response'}},
+    'styles': {
+        'text': {'kind': 'module-text', 'size': 4, 'fill': '#203e53'},
+        'box': {'kind': 'module-box', 'fill': '#e9f0f4', 'stroke_width': 0.4},
+    },
+})
+```
+
+Larger text is remeasured, so connected modules and dependent layout update.
+Style edits retain live data, named instruction keys and unedited source choices.
+Data-driven marker colour/diameter controls are omitted, including ramped
+colours. If a source revision turns an edited constant into a data mapping,
+the saved style is reported as incompatible, such as `/chart#style:samples`.
+Explicit discard removes that style target's edits while preserving compatible
+labels and placements on the chart.
+
+Styles use the same named path, key and kind contracts as labels. New saved
+files use schema 0.4; 0.1, 0.2 and 0.3 files still load. This unifies authoring
+within the composition editor. The separate [linked-table style inspector](visual-editing.md)
+retains its own source-bound format; its files are not interchangeable. Plot
+titles, axes, bars, arbitrary factories, gradients and camera/material settings
+are outside this style-control subset.
+
 ## Edit and review
 
-Choose a named path in **Content**, enter the fields you want to change, then
-select **Apply layout**. Other fields retain their definitions.
+Choose a named path in **Content** and a section in **Edit**, enter the fields you want to change, then
+select **Apply changes**. Other fields retain their definitions.
 
 - Child placement fields are X, Y, anchor, width, height and uniform scale. Numbers use the
   containing composition's coordinate unit. For plots, width and height describe
@@ -98,7 +189,7 @@ preview, saved choices and undo history remain available. The inspector does
 not automatically resolve overlap or add constraints: author the required
 measured relationships and minimum sizes in the Python recipe.
 
-**Undo** and **Redo** retain up to 100 successful layout edits. A new edit after
+**Undo** and **Redo** retain up to 100 successful authoring edits. A new edit after
 undo starts a new history branch. Shared nested definitions remain shared:
 editing or resetting one occurrence affects the same definition wherever it
 appears. Distinct placements of that shared content remain independently editable.
@@ -107,8 +198,8 @@ appears. Distinct placements of that shared content remain independently editabl
 
 **Save layout** downloads the versioned JSON described in
 [saved layout choices](layout-overrides.md). **Open layout choices** loads that
-same format. The file contains changed placements and dimensions, not the
-source content, styles, assets or undo history. Keep it alongside the recipe.
+same format. The file contains changed layout, label and supported style fields.
+Other source content, assets and undo history stay outside the file. Keep it alongside the recipe.
 
 **Download SVG** and **Download PDF** export the successful preview revision.
 If another editor tab changes the session first, stale commands and export

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/docs/layout-overrides.md

@@ -1,6 +1,6 @@
 # Save and restore layout choices
 
-Available since **4.0.0.dev7**; uniform artwork scale is added in **dev9**. Save placement and dimension edits separately from
+Available since **4.0.0.dev7**; uniform artwork scale is added in **dev9**, named text and callout decisions in **dev10**, and supported appearance fields in **dev11**. Save placement and dimension edits separately from
 a [composition recipe](composition-recipes.md), then restore those choices
 when its data, labels or content change. The saved JSON records only differences
 from a reference recipe. Unedited source decisions remain in control.
@@ -21,7 +21,7 @@ Python APIs below or the [local inspector](layout-editor.md) in dev8. This forma
 
 Keep a reference recipe, copy it, then edit placements. The reference and edited
 recipe must have the same named composition structure when capturing changes.
-Content and styles can differ; they are not serialized into the layout file.
+Supported named label differences are captured too. Supported named style differences are captured too; other content is not serialized into the layout file.
 
 ```python
 import json
@@ -52,6 +52,39 @@ identity within the recipe hierarchy. Renaming or moving a target changes its
 identity. Definitions hidden inside component factories or other BuildSpecs
 are not traversed.
 
+## Named label decisions
+
+Changed string module captions and text components are captured alongside layout.
+Plot titles, text and annotations require explicit string instruction keys;
+composition annotations require unique names. See the [label editor](layout-editor.md#edit-labels-and-callouts)
+for controls, identity rules and an executable example. Captures compare only
+matching label keys and kinds; they do not serialize added or removed content.
+
+A saved label entry includes its kind and only the fields that changed:
+
+```json
+{"schema":"inklet.composition-layout/0.4","targets":{"/caption":{"labels":{"label":{"kind":"module-label","text":"Reviewed response"}}}}}
+```
+
+Readers accept legacy schemas 0.1, 0.2 and 0.3. New captures use 0.4; older readers
+must be upgraded before opening them. Label fields are rejected under older
+schema identifiers. Removed/incompatible labels appear as `path#key` in the
+orphan report. Explicit `missing='drop'` retains compatible edits on that path.
+
+## Named appearance decisions
+
+Schema 0.4 adds a `styles` group beside `placement`, `page` and `labels`.
+Each named style contains its `kind` and changed fields. The [appearance guide](layout-editor.md#edit-appearance-alongside-layout)
+lists supported controls, units, data-mapping exclusions and a combined edit.
+A `null` style value removes an explicit keyword; unedited source fields stay
+live. Capturing changes compares compatible named style keys and kinds, not
+arbitrary renderer nodes or paint objects.
+
+Source revisions that remove a style key, change its kind or replace a constant
+with a data mapping produce a `path#style:key` orphan. With explicit discard,
+compatible layout and label edits on the same path survive. The separate
+linked-table visual-override format is not converted by this loader.
+
 ## Restore on the current recipe
 
 ```python
@@ -85,7 +118,7 @@ updated_figure = render(updated)
 updated_figure.save('updated.svg')
 ```
 
-The file stores layout decisions, not content, datasets, labels, plot styles,
+The file stores layout, supported labels and styles, not datasets,
 links, ports, constraints, factories or camera parameters. Keep the Python
 recipe and its assets alongside it. The containing document can supply its own
 render dimensions; restoring authored page dimensions does not override that
@@ -123,12 +156,13 @@ of 32 operations. Malformed files, nonfinite numbers, invalid properties and
 contradictory edits to a shared nested definition are rejected, including when
 `missing='drop'` is used.
 
-New files use `inklet.composition-layout/0.2`, which adds a positive uniform
-artwork scale. The loader also accepts `inklet.composition-layout/0.1` files
-from dev7/dev8; those cannot contain scale fields. Unknown schemas are rejected.
-Upgrade older readers before opening a new 0.2 file. The file is a JSON object with `schema` and `targets`; each target has
-changed `placement` and/or `page` fields. It is a development-preview format,
-not a general Python object serializer or an asset manifest.
+New files use `inklet.composition-layout/0.4`, adding named appearance decisions.
+The loader also accepts 0.1 files from dev7/dev8 (without scale), 0.2 files from
+dev9 (without labels) and 0.3 files from dev10 (without styles). Unknown schemas
+are rejected. Upgrade older readers before opening a 0.4 file. The JSON object
+contains `schema` and `targets`; each target has changed `placement`, `page`,
+`labels` and/or `styles` fields. This development-preview format is not a general
+Python object serializer or an asset manifest.
 
 ## Review revised content
 

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/docs/roadmap.md

@@ -60,8 +60,13 @@ Dev8 adds a [local layout inspector](layout-editor.md) backed by Python
 compilation, with saved choices, undo/redo and explicit source refresh.
 Dev9 adds mouse movement, proportional artwork scaling and keyboard nudges
 for named composition children, with preserved measured positions and saved
-choices. Serialized project templates, asset manifests, shared selection
-relationships, label/camera editing and finer-grained manipulation remain open. Subsequent work
+choices. Dev10 adds saved named text and callout editing across modules, text
+components, keyed plot instructions and composition annotations, including typed
+identity reconciliation. Dev11 connects supported plot, text and module styles
+to that same layout/label history, saved state and reconciliation workflow,
+with data-driven marker fields protected from constant overrides.
+Serialized project templates, asset manifests, shared selection
+relationships, axis-label/camera editing and finer-grained manipulation remain open. Subsequent work
 should extend authoring and cross-content identity beyond this bounded inspector.
 
 ## Who this should serve

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/examples/layout_editor.py

@@ -10,6 +10,7 @@ def main():
     parser.add_argument('--port',type=int,default=0,help='Local port; 0 chooses an available port')
     args=parser.parse_args()
     reports,_=make_reports()
+    reports[0]['chart'].annotate(2,3,'Reference observation',key='observation',side='s',clear=4)
     with LayoutEditor(reports[0],preset='scientific.general').start(port=args.port) as editor:
         print(f'Open {editor.url} — press Ctrl+C to stop.',flush=True)
         try:threading.Event().wait()

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "inklet"
-version = "4.0.0.dev9"
+version = "4.0.0.dev11"
 description = "Scientific figures with live data, measured layout, and consistent vector exports."
 readme = "README.md"
 authors = [{name = "Mark Marosi"}]

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/src/inklet/__init__.py

@@ -470,4 +470,4 @@ __all__ = [
     "mm", "pt", "COLUMN_SINGLE", "COLUMN_DOUBLE",
 ]
 
-__version__ = "4.0.0.dev9"
+__version__ = "4.0.0.dev11"

{inklet-4.0.0.dev9 → inklet-4.0.0.dev11}/src/inklet/document/composition.py

@@ -193,10 +193,10 @@ class Composition(BuildSpec):
         raise KeyError(name)
 
     def layout_overrides(self, reference):
-        """Capture changed placements and page fields against a matching reference.
+        """Capture changed layout, named labels and supported styles against a reference.
 
         Return JSON-compatible, versioned decisions keyed by named child paths.
-        Content, styles, data, links and constraints remain in the Python recipe.
+        Other content, data, links and constraints remain in Python.
         """
         from .layout_overrides import capture
         return capture(self, reference)
@@ -234,7 +234,12 @@ class Composition(BuildSpec):
         return self
 
     def annotate(self, target, text, **options):
-        """Place a measured callout after every child and connection exists."""
+        """Place a measured callout; a unique name enables saved label editing."""
+        name = options.get('name')
+        if name is not None:
+            if not isinstance(name,str) or not name: raise ValueError('annotation name must be a nonempty string')
+            if any(opts.get('name')==name for _,_,opts in self._annotations):
+                raise LayoutError(f'duplicate annotation name {name!r}')
         self._annotations.append((target, text, freeze(options)))
         return self
 

inklet-4.0.0.dev11/src/inklet/document/label_overrides.py

@@ -0,0 +1,91 @@
+"""Explicit text targets within named recipes; never infer identity from ink."""
+from __future__ import annotations
+
+import math
+
+from .spec import ComponentSpec, PlotSpec
+from .module import ModuleSpec
+
+
+def targets(item):
+    """Return keyed, typed label controls and internal replacement locations."""
+    from .. import text
+    from .composition import Composition
+    found = {}
+
+    def add(key, kind, value, location, options=None):
+        if not isinstance(key, str) or not key or not isinstance(value, str): return
+        if key in found: raise ValueError(f'duplicate editable label key {key!r}')
+        fields = dict(kind=kind, text=value)
+        if options is not None:
+            from ..core import mm
+            clear = options.get('clear')
+            fields.update(side=options.get('side', 'n'), leader=options.get('leader', True))
+            # A measured clearance remains authored until explicitly replaced.
+            from .composition import LayoutValue
+            if not isinstance(clear, LayoutValue): fields['clear'] = None if clear is None else mm(clear)
+        found[key] = (fields, location)
+
+    if isinstance(item, ModuleSpec): add('label', 'module-label', item.label, ('module',))
+    elif isinstance(item, ComponentSpec) and item.factory is text:
+        add('text', 'component-text', item.args[0] if item.args else item.kwargs.get('content'), ('component',))
+    elif isinstance(item, PlotSpec):
+        for index, (key, method, args, options) in enumerate(item._steps):
+            if method not in ('title', 'text', 'annotate'): continue
+            position = 0 if method == 'title' else 2
+            keyword = 'text' if method == 'annotate' else 'content'
+            value = args[position] if len(args)>position else options.get(keyword)
+            add(key, 'plot-'+method, value, ('plot', index, position, keyword),
+                options if method == 'annotate' else None)
+    elif isinstance(item, Composition):
+        for index, (_, value, options) in enumerate(item._annotations):
+            add(options.get('name'), 'composition-annotation', value, ('annotation', index),
+                {'clear':2, **options})
+    return found
+
+
+def validate(value):
+    if not isinstance(value, dict) or not value: raise ValueError('labels must be a nonempty object')
+    result = {}
+    for key, fields in value.items():
+        if not isinstance(key, str) or not key or not isinstance(fields, dict):
+            raise ValueError('labels require nonempty string keys and field objects')
+        kind = fields.get('kind')
+        allowed = {'kind', 'text'}
+        if kind in ('plot-annotate', 'composition-annotation'): allowed |= {'side', 'clear', 'leader'}
+        if (kind not in ('module-label','component-text','plot-title','plot-text','plot-annotate','composition-annotation')
+                or not set(fields)<=allowed or len(fields)<2):
+            raise ValueError('invalid label kind or fields')
+        for name, val in fields.items():
+            if name=='text' and not isinstance(val, str): raise ValueError('label text must be a string')
+            if name=='side' and val not in ('n','ne','e','se','s','sw','w','nw'):
+                raise ValueError('invalid annotation side')
+            if name=='leader' and type(val) is not bool: raise ValueError('label leader must be a boolean')
+            if name=='clear' and not (val is None and kind=='plot-annotate'):
+                if type(val) not in (int,float) or not math.isfinite(val) or val<0:
+                    raise ValueError('label clearance must be finite nonnegative millimetres')
+        result[key] = dict(fields)
+    return result
+
+
+def apply(item, edits):
+    available = targets(item)
+    for key, fields in edits.items():
+        current, location = available[key]
+        changes = {k:v for k,v in fields.items() if k!='kind'}
+        value = changes.pop('text', current['text'])
+        if location[0]=='module': item.configure(value)
+        elif location[0]=='component':
+            if item.args: item.args = (value, *item.args[1:])
+            else: item.kwargs['content'] = value
+        elif location[0]=='plot':
+            _, index, position, keyword = location
+            found, method, args, kwargs = item._steps[index]
+            args, kwargs = list(args), dict(kwargs)
+            if len(args)>position: args[position] = value
+            else: kwargs[keyword] = value
+            item._steps[index] = (found, method, tuple(args), kwargs | changes)
+        else:
+            _, index = location
+            target, _, options = item._annotations[index]
+            item._annotations[index] = (target, value, options | changes)