forgegraph 0.4.0__tar.gz → 0.5.0__tar.gz

{forgegraph-0.4.0 → forgegraph-0.5.0}/CHANGELOG.md

@@ -1,40 +1,52 @@
 # Changelog
 
-ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written. From 0.2.0 on, each release's entry links its visual changelog: before and after images of every catalog card and regression graph that changed, made with `scripts/visual_changelog.py`.
+ForgeGraph follows [semantic versioning](https://semver.org). Before 1.0, a minor version may change how graphs look or how specs are written.
+
+## 0.5.0 (2026-10-29)
+
+### New Features
+
+- **Nested tabs.** A tab in a layout can now hold tabs of its own, to any depth. The HTML page shows a row of tabs for each level, and switching to another group keeps the same chart showing.
+- **Tick labels per axis.** `axis.x.tick.label` and `axis.y.tick.label` set the size, weight and color of each axis's tick labels separately. Anything they don't set comes from `axis.tick.label`.
+- **Tabs without scripts.** The tabs on a layout's HTML page now work where the page's scripts don't run, such as in a browser with JavaScript turned off. Before, such a page showed every tab, one below another.
+- **Tab bar style.** A layout's `tab_bar.label` and `tab_bar.line` set the look of the tab names and of the line under them on the HTML page. By default they follow the first graph's theme.
+
+### Changes
+
+- **Titles.** Titles now sit `title.gap` above the plot, measured from the line the letters sit on, so titles side by side line up whatever their letters. The default theme's `title.gap` is now 0.41, which keeps its titles where they were. A theme that sets its own `title.gap` will see its titles sit a little higher than in 0.4.
+- **Notes above the plot.** A note placed outside the plot at the top now goes between the title and the plot, instead of above the title.
+- **Tab names on the page.** The tab names are written in the theme's font and color, instead of the browser's font in dark grey.
+
+### Bug Fixes
+
+- Tick labels now use the theme's tick label font and weight. Before, only their size and color were applied.
+- A y-axis title reading upward now sits the same distance from the tick labels whatever its letters.
 
 ## 0.4.0 (2026-10-27)
 
-Images that changed: the [visual changelog](docs/visual-changelog/0.4.0.html).
+### New Features
 
-### Changed
+- **Multiple Series.** GraphSpecs can now have independent Series, enabling full control over the marker, line, and bar properties and not just variation by a palette.
+- **Reference bands.** The `reference_line` layer is now `reference` and has been augmented to also draw lines per element of the series and bands. It also can now compute a value plus offset (e.g. a line at mean + 3 s.d.). This enables drawing of error bands, confidence intervals of model fits, and other more complex references.
+- **More aggregations.** Series, reference lines, and error bars can show the mean, median, percentile, standard deviation, standard error or confidence intervals.
+- **Stepped and smooth lines.** `line.interpolate` can now be steps or a smooth curve in addition to a direct line.
+- **Dates as values.** Dates, such as `2025-08-25`, can now be used directly in all relevant parameters.
 
-- **Breaking for existing specs and configs:** one built-in pack, `forgegraph_default`, replaces `forgegraph_base` and `forgegraph_base_2`. Its specs are `light_theme` (in place of `forgegraph_base/base_theme`), `compact_format` (`base_format`), `wide_format` (`base_layout_format`), `layout` (`layout_example`), `schedule` (`base_schedule`) and `graphspec_example`; `forgegraph_base_2` has no replacement. A main config listing `forgegraph_base` or `forgegraph_base_2` is an error: list `forgegraph_default` instead. light_theme draws 0.3's look. It fixes every text's font and gap, the palettes (the colors, line styles, marker shapes and fills that series take in turn), the ticks' direction, sides and algorithms, and the grid, so a GraphSpec that sets `grid.x.show` needs a theme that leaves it variable; a series may still set its own color, line style, marker shape and line width. The default layout draws no line between tiles and leaves 0.25 × the base size at the figure's edges.
-- The specification files, which define each kind, are in `src/forgegraph/specifications/`, and their pages in `docs/specifications/`; no spec can name or extend them. The built-in pack's pages are in `docs/packs/forgegraph_default/`, and the catalog page is `catalog/forgegraph_default.html`.
-- A category's brackets in a specification file say what the code reads about it, from a fixed set: its style, `same as <sibling>` for a category with a sibling's parameters, and `look from <theme category>` for a layer category whose look comes from the theme. Anything else there is an error, and descriptions are never read, so rewording one changes nothing.
-- A style's member that no file tags, itself or through a category inside `parameters`, is fixed or variable as its general parameter is: a fixed `text.font` fixes every text style's font, even where the theme sets the style's own.
-- `forgegraph schema <kind>` no longer says whether a parameter is fixed: it shows the kind's specification, which isn't what graphs are drawn with. `forgegraph schema graphspec` lists what a GraphSpec can set, and `forgegraph explain` shows what's fixed.
-- A reference layer's `fill.color` may be None: two lines with values make a band only when it isn't.
-- **Breaking for existing specs:** a GraphSpec lists its series by name under `series`, each drawn from its own column (by default, the column of its name) with its own settings: `aggregation`, `split`, `order`, `color`, `color_scale`, `line`, `marker`, `bar` and `value_label`, and the theme's variable series parameters it sets for itself. They replace `axis.*.data.aggregation`, `encoding.*` and `mark.*`; the value axis's `data.column` is None. `arrangement.base_axis`, `arrangement.stacking`, `arrangement.offset` and `arrangement.total.show` replace `series.base_axis`, `series.aggregation`, `series.offset` and `series.value_label.total.show`. A series' color, line style, marker shape and fill take `first`, `series`, a value or a column; series take palette colors in the order they're listed.
-- **Breaking for existing specs:** the `reference` layer replaces `reference_line`: `line_1` and `line_2`, each at a value or from a column, with its own `aggregation` and `offset` (aggregation styles), `scope`, line and label (with `label.inside`), and the `fill` of a band between them. The theme's `layer.reference` replaces `layer.reference_line`.
-- An aggregation style (`function`, `multiplier`, `percentile`) for a series, a reference line and error bars; functions include `percentile`, `stddev`, `stderr` and `ci`.
-- `line.interpolate` draws a series' line straight, in steps (`step_after`, `step_before`, `step_center`) or as a smooth curve that never overshoots its points.
-- A note and a reference layer's lines, labels and fill may set the theme's variable look for themselves.
-- A style key (one from `encoding.line.style.column`, `encoding.marker.shape.column` or `encoding.marker.fill.column`) follows `legend.key.title.text`, as the series' key does: `column_name`, the default, gives each key its own column's name, so default graphs are unchanged; `None` removes every key's title; a text titles one key, and with more than one key drawn it's an error. With no `encoding.color.column`, a style key's samples are drawn in the one series color, not the text color. `render --json` reports `style_keys`, the column each style key drawn explains (for a layout, each tile's), beside `labelling`.
-- A range type `date`: a date, or a date and time, as YAML's bare date (`2025-08-25`, `2025-08-25 06:00:00`) or ISO 8601 text (`"2025-08-25T06:00"`); a time with a zone is at its clock time, as the data's are. `axis.x.min`, `axis.x.max`, `axis.y.min` and `axis.y.max`, a reference line's `value` and `benchmark.value` take it: on a datetime axis or column, a date is drawn exactly where its day number is, and numbers keep working as day numbers. A date on an axis that isn't dates is an error naming the axis's type. Text that reads as a date is a reference line's column only if the data has a column of that name. Provenance records write dates as ISO 8601 text.
-- On a date value axis, what would draw nonsense is an error that says what to do: stacking (`series.aggregation` sum or percent), adding up rows (`axis.*.data.aggregation` sum), bars (`mark.bar.show`, which would start at 1970), and value labels without a date format. A reference line at a date column's aggregate is on a date axis only, at its mean, median, min or max, with multiplier 1. A date axis's `tick.label.format` must have a date directive.
+### Changes
 
-### Fixed
+- **One built-in pack, `forgegraph_default`.** `forgegraph_base` is renamed `forgegraph_default` and its specifications have been renamed. `forgegraph_base_2` has been removed. Please update your config and any GraphSpecs or packs referencing the old packs. The default theme has been tuned slightly to fix more parameters, reducing complexity of graph design.
+- **Themes, formats and GraphSpecs are written differently.** Each has one `parameters` tree, and `!fix` and `!var` tags are used to set what a GraphSpec can change, in place of the `fixed_parameters` and `variable_parameters` blocks. A theme sets the parameters of all text and all lines once, under `text` and `line`, and each category that uses them, such as the title or the tick labels, only needs to modify the parameters that are different from that default.
+- **Simplified Specifications.** Numerous simplifications to the way specifications are written, making them easier to read and modify.
 
-- In a theme whose text is light, powers of ten on a log axis and superscripts in labels no longer give a `font-fallback` lint issue. They were always drawn in the theme's font and weight; the issue came from the faces matplotlib loads for maths but doesn't draw these with.
-- The `outside-limits` and `log-axis-values` lint checks count only data points. A reference line's ends and an error bar's ends no longer count as points outside a set axis limit, or as values of 0 or below on a log axis.
-- A style key on the benchmark's column matches the drawing: its entries are the groups the series are styled by, so a value after the benchmark no longer gets the next value's style, and the benchmark, drawn in its own style, has no style sample and is named once, by `legend.method`. When `legend.method: key` doesn't fit, the error says why: every position in `legend.key.positions` is taken or covers data, naming the position each style key took.
-- YAML's null (`null`, `~` or nothing) is None everywhere a spec can say None. `extends: null` failed with `KeyError: None`, and a file extending null wasn't required to list every parameter.
-- Computed values are compared with an axis's limits allowing for float noise: a value is past a limit only if it's past by more than 1e-9 of the axis's span, measured in powers of ten on a log axis. A stack that totals `axis.y.max` but for its last digits isn't reported by `outside-limits`; a reference line at a computed value that equals a set limit isn't an error; bars whose values are 0 but for float noise still stand on the axis; and a tick a hair past the end of the view, which matplotlib draws, is measured for layout and lint and counts when log labels choose between plain numbers and powers of ten.
-- Dates and times draw the same on y as on x: every value placed on an axis (the data, its aggregates, stacks, reference lines, error bars and limits) becomes a number the same way, so a date y axis has date ticks, a reference line at a date column's aggregate lands on it, and error bars from a date column's spread are in days. With value labels off, a date `tick.label.format` such as `"%H:%M"` on y is no longer refused as a number format; value labels and a reference line's value on a date axis are written in a date format.
+### Bug Fixes
 
-## 0.3.0 (2026-10-25)
+- Dates on the y axis draw as they do on x: date ticks, reference lines at a date column's mean or median, and error bars in days.
+- The lint no longer counts reference lines and error bars as data points outside the axis limits, or as values of 0 or below on a log axis.
+- Values that differ from an axis limit only by rounding are no longer reported as outside it.
+- In a theme with a light font weight, powers of ten on a log axis no longer give a `font-fallback` lint issue.
+- `null` and `~` are accepted everywhere a spec can say None.
 
-Images that changed: the [visual changelog](docs/visual-changelog/0.3.0.html).
+## 0.3.0 (2026-10-25)
 
 ### Added
 
@@ -78,8 +90,6 @@ Images that changed: the [visual changelog](docs/visual-changelog/0.3.0.html).
 
 ## 0.2.0 (2026-10-24)
 
-Images that changed: the [visual changelog](docs/visual-changelog/0.2.0.html).
-
 ### Changed
 
 - Error bars are black by default in both built-in themes, and their color (`layer.error_bar.color`) is a variable parameter: a GraphSpec may set `series` or any hex color.

{forgegraph-0.4.0 → forgegraph-0.5.0}/CONTRIBUTING.md

@@ -9,7 +9,7 @@ uv sync
 uv run pre-commit install
 ```
 
-While you work, `uv run pytest` runs the development suite: every test not marked slow, in parallel. The full suite adds the slow ones (every catalog card drawn, the image baselines, the catalog pages, and any test over a second). CI runs it on every pull request, and it's the one to run before a release:
+While you work, `uv run pytest` runs the development suite: every test not marked slow, in parallel. The full suite adds the slow ones (every catalog card drawn, the image baselines, the catalog pages, and any test over a second). CI runs it on every pull request that changes more than pages no test reads (`review/`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/` other than the spec and pack pages), and it's the one to run before a release:
 
 ```bash
 uv run pytest --full && uv run ruff check . && uv run ruff format --check && uv run pyright
@@ -39,6 +39,6 @@ Open a GitHub issue describing the graph you need, ideally with an example image
 
 1. Set the new version in pyproject.toml and in the built-in pack's pack.yaml, and for a new minor version, its `requires` (`">=0.4, <0.5"` for 0.4).
 2. Rebuild the catalog and mirrors (above).
-3. Write the visual changelog, `uv run python scripts/visual_changelog.py v<last version>`, and the CHANGELOG entry, linking it.
+3. Write the CHANGELOG entry: the key features a user would want to know were added, changed or removed, and the bugs fixed.
 4. Merge with CI green, and tag the merge commit `v<version>`.
 5. Run the Publish workflow.

{forgegraph-0.4.0 → forgegraph-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgegraph
-Version: 0.4.0
+Version: 0.5.0
 Summary: Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents.
 Project-URL: Repository, https://github.com/sskaye/forgegraph
 Project-URL: Issues, https://github.com/sskaye/forgegraph/issues

{forgegraph-0.4.0 → forgegraph-0.5.0}/docs/design/architecture.md

@@ -429,7 +429,7 @@ Every output embeds a provenance record, at its format's provenance.level (full,
 - **One version number: the library's**, using semver. The built-in packs are released with it and carry its version; other packs have their own, like any package.
   - **Major:** a breaking change to a spec format.
   - **Minor:** releases may change how graphs look.
-- **Visual changelog:** each release lists every appearance change, with before and after images of every catalog card and regression graph that changed.
+- **Visual changelog:** `scripts/visual_changelog.py` shows before and after images of every catalog card and regression graph that changed between two commits, for checking how a change alters the look.
 - **Pinning:** projects and scheduled renders pin versions through their lockfile, so a dashboard can't change appearance overnight.
 - **No telemetry.** Feature requests come from the request flow and GitHub issues.
 

{forgegraph-0.4.0 → forgegraph-0.5.0}/docs/packs/forgegraph_default/layouts/layout.md

@@ -21,11 +21,18 @@ parameters: !var          *# !var/!fix sets whether a layout may chang
         border:\
             show: false          *# \[true, false\]; Whether to also draw the line around the outside of the tiles, through the middle of the inner gap.*\
         corner_radius: 0          *# \[float ≥ 0\]; The radius of the corners of each tile's background, × base size.*\
-    tabs:          *# The layout's tabs, in order, each under the name shown on its tab. A layout's tabs replace those it inherits.*\
+    tab_bar:          *# The row of tab names at the top of the HTML page of a layout with more than one tab.*\
+        label:          *# \[text style\]; The tab names. Its defaults are the first tile's theme's text. The selected tab is underlined in its color.*\
+            alignment: left          *# \[left, center, right\]; The text alignment.*\
+        line:          *# \[line style\]; The line under the tab bar, and the border's top when the border is drawn. Its defaults are the first tile's theme's line.*\
+            style: None          *# \[None, solid, dashed, dotted\]; The line style. If None, no line is drawn.*\
+            width: 0.05          *# \[float ≥ 0\]; The width, × base size. If 0, no line is drawn.*\
+            color: "#D9D9D9"          *# \[hex color\]; The color.*\
+    tabs:          *# The layout's tabs, in order, each under the name shown on its tab. A tab holds a grid and its tiles, or tabs of its own, to any depth. A layout's tabs replace those it inherits.*\
         main:\
             grid:\
                 areas: \[\[a\]\]          *# \[text grid\]; A list of tiles for each row. A . leaves a cell blank. A name repeated over a rectangle of cells makes that tile span them, e.g. \[a, a\] makes tile a span two columns.*\
                 column_widths: None          *# \[None, floats > 0\]; The relative widths of the columns' plot boxes. If None, they're equal.*\
                 row_heights: None          *# \[None, floats > 0\]; The relative heights of the rows' plot boxes. If None, they're equal, or as tall as the tiles need.*\
             tiles:          *# The GraphSpec drawn in each area of the grid, under the area's name.*\
-                a: None          *# \[text\]; The GraphSpec file: an absolute path, a path starting with \~, or a path relative to this file. A layout must set it.*
+                a: None          *# \[text\]; The GraphSpec file: an absolute path, a path starting with ~, or a path relative to this file. A layout must set it.*

{forgegraph-0.4.0 → forgegraph-0.5.0}/docs/packs/forgegraph_default/pack.md

@@ -3,14 +3,14 @@
 This page mirrors src/forgegraph/packs/forgegraph_default/pack.yaml, which is the specification. A test fails if they ever differ.
 
 name: forgegraph_default          *# \[text\]; The pack's name, either a folder where the pack is stored or a pip pack's entry point.*\
-version: 0.4.0          *# \[text\]; The pack's release version.*\
+version: 0.5.0          *# \[text\]; The pack's release version.*\
 description: ForgeGraph's built-in default pack. So it’s always possible to create a graph.          *# \[text\]; One line, describing what the pack is.*\
 issues: https://github.com/sskaye/forgegraph/issues          *# \[text\]; Where to file feature requests and bug reports about the pack.*\
-requires: <!-- fmc:1 -->">=0.4, <0.5"<!-- /fmc:1 -->          *# \[None, version specifier\]; The ForgeGraph version required for the pack. pip format, e.g. ">=0.6, <1". If None, it works with any version.*
+requires: <!-- fmc:1 -->">=0.5, <0.6"<!-- /fmc:1 -->          *# \[None, version specifier\]; The ForgeGraph version required for the pack. pip format, e.g. ">=0.6, <1". If None, it works with any version.*
 
 <!-- forgemark-comments
 - id: 1
-  anchor_text: "\">=0.4, <0.5\""
+  anchor_text: "\">=0.5, <0.6\""
   context_before: "xt\\]; Where to file feature requests and bug reports about the pack.*\\ requires:"
   context_after: "# \\[None, version specifier\\]; The ForgeGraph version required for the pack."
   author: "Steven Kaye"
@@ -26,4 +26,8 @@ requires: <!-- fmc:1 -->">=0.4, <0.5"<!-- /fmc:1 -->          *# \[Non
       timestamp: 2026-10-28T03:30:17Z
       body: |
         With the 0.4.0 release, this now reads ">=0.4, <0.5" and the pack version is 0.4.0.
+    - author: Claude
+      timestamp: 2026-10-29T05:13:44Z
+      body: |
+        With the 0.5.0 release, this now reads ">=0.5, <0.6" and the pack version is 0.5.0.
 -->

{forgegraph-0.4.0 → forgegraph-0.5.0}/docs/packs/forgegraph_default/themes/light_theme.md

@@ -26,7 +26,7 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
     title:          *# \[text style\]; The graph's title.*\
         size: 1.05          *# \[float > 0\]; The size, × base size.*\
         weight: semibold          *# \[light, regular, medium, semibold, bold\]; The weight.*\
-        gap: 0.5          *# \[float ≥ 0\]; The gap between the text and whatever is around it, × base size.*\
+        gap: 0.41          *# \[float ≥ 0\]; The gap between the text and whatever is around it, × base size.*\
     axis:\
         title:          *# \[text style\]; The axis titles.*\
             size: 1.05          *# \[float > 0\]; The size, × base size.*\

forgegraph-0.5.0/docs/specifications/layout_example.md

@@ -0,0 +1,88 @@
+# Layout specification: layout_example
+
+This page mirrors src/forgegraph/specifications/layout_example.yaml, which is the specification. A test fails if they ever differ.
+
+name: layout_example          *# \[text\]; The name of the layout.*\
+version: 0          *# \[int ≥ 0\]; The version number of the specification.*\
+description: An example layout to define the specification.          *# \[text\]; The description of the layout.*\
+extends: None          *# \[None, layout\]; Each parameter not listed is inherited from this layout. If None, this file must list every parameter.*\
+ \
+parameters: !var          *# !var/!fix sets whether a layout may change a property. Subcategories/parameters inherit the setting of the one above them unless explicitly overridden.*\
+    specifications:\
+        format: forgegraph_default/wide_format          *# \[format\]; The format that sets the layout's size and output, in place of its tiles' formats.*\
+    separators:          *# The space and lines between and around the figures. The gaps use the background.color of the first tile's theme.*\
+        gap:\
+            inner: 1.5          *# \[float ≥ 0\]; The space between the figure's edges and the outer tiles, × base size.*\
+            outer: 1.5          *# \[float ≥ 0\]; The space between neighboring tiles, from the outermost text or line of one to that of the next, × base size.*\
+        line:          *# \[line style\]; The line along the middle of each gap between tiles. Its defaults are the first tile's theme's line.*\
+        border:\
+            show: false          *# \[true, false\]; Whether to also draw the line around the outside of the tiles, through the middle of the inner gap.*\
+        corner_radius: 0          *# \[float ≥ 0\]; The radius of the corners of each tile's background, × base size.*\
+    tab_bar:          *# The row of tab names at the top of the HTML page of a layout with more than one tab.*\
+        label:          *# \[text style\]; The tab names. Its defaults are the first tile's theme's text. The selected tab is underlined in its color.*\
+        line:          *# \[line style\]; The line under the tab bar, and the border's top when the border is drawn. Its defaults are the first tile's theme's line.*\
+    tabs:          *# The layout's tabs, in order, <!-- fmc:1 -->each under the name shown on its tab<!-- /fmc:1 -->. A tab holds a grid and its tiles, or tabs of its own, to any depth. A layout's tabs replace those it inherits.*\
+        main:\
+            grid:\
+                areas: \[\[a\]\]          *# \[text grid\]; A list of tiles for each row. A . leaves a cell blank. A name repeated over a rectangle of cells makes that tile span them, e.g. \[a, a\] makes tile a span two columns.*\
+                column_widths: None          *# \[None, floats > 0\]; The relative widths of the columns' plot boxes. If None, they're equal.*\
+                row_heights: None          *# \[None, floats > 0\]; The relative heights of the rows' plot boxes. If None, they're equal, or as tall as the tiles need.*\
+            tiles:          *# The GraphSpec drawn in each area of the grid, under the area's name.*\
+                a: None          *# \[text\]; The GraphSpec file: an absolute path, a path starting with ~, or a path relative to this file. A layout must set it.*
+
+<!-- forgemark-comments
+- id: 1
+  anchor_text: "each under the name shown on its tab"
+  context_before: "faults are the first tile's theme's line.*\\ tabs: # The layout's tabs, in order,"
+  context_after: ". A tab holds a grid and its tiles, or tabs of its own, to any depth."
+  author: Claude
+  timestamp: 2026-10-29T03:24:33Z
+  resolved: false
+  body: |
+    Proposal for the HTML page's tab bar, with no new parameter.
+    
+    Problem: the page draws the tab names in the browser's font and in dark grey (#333333), whatever the theme. A layout with a dark background gets an unreadable tab bar, and the tab names never match the figures' text.
+    
+    Proposed change: the tab bar takes its look from what the layout already has, as the gaps already take the first tile's theme's background.color.
+    1. Each tab's name, as written under tabs, is drawn in the first tile's theme's general text: its font, weight and color, at text.size × the layout's base size.
+    2. The selected tab is underlined in that text color.
+    3. The line under the tab bar is separators.line, whose defaults are the first tile's theme's line.
+    4. The page embeds the font, since a browser shows a typeface only if the viewer has it installed or the page carries it.
+    
+    Nothing is added to this specification or the theme's. The tabs description would end: "Their names are written in the first tile's theme's text."
+    
+    Alternative: a tab_label text style here, with the first tile's theme's text as its defaults, as separators.line takes the theme's line. It would let a layout style its tab names apart from the figures' text, but nothing has asked for that.
+    
+    Recommendation: no new parameter.
+  replies:
+    - author: Steven
+      timestamp: "2026-10-29T03:40:06.714Z"
+      body: |-
+        Better to have the control.
+        Proposal:
+        - Under tabs, add the param “tab_label” (or whatever the standard name is for the text that appears in a tab), which should be text_style, enabling setting of the params of the tab title text. 
+        - The selected tab is underlined in that text color
+        - Add an additional parameter for the line under the tab bar. Again, name whatever that’s normally called and make it line style.
+        -  The page embeds the font, since a browser shows a typeface only if the viewer has it installed or the page carries it.
+    - author: Claude
+      timestamp: 2026-10-29T03:41:14Z
+      body: |
+        Agreed, with one change to where the parameters go and suggested names.
+        
+        1. They can't go under tabs. tabs is a mapping of the author's own tab names, so a parameter there would read as a tab named tab_label, and a layout couldn't name a tab that. They need a category of their own beside tabs and separators.
+        2. Names: the usual name for the strip of tabs is the "tab bar", for the text in a tab its "label", and for the line under the bar a "divider". "line" matches separators.line, so I'd use it over divider.
+        
+        Proposed lines:
+        
+            tab_bar:          # The row of tab names at the top of the HTML page of a layout with more than one tab.
+                label:          # [text style]; The tab names. Its defaults are the first tile's theme's text. The selected tab is underlined in its color.
+                line:          # [line style]; The line under the tab bar. Its defaults are the first tile's theme's line.
+        
+        3. The selected tab is marked only by its underline. Today it's also drawn semibold; dropping that lets label.weight decide every tab's weight.
+        4. With nested tabs (#67), every level's tab bar uses the same style.
+        5. These change only the HTML page, since images and PDFs have no tab bar.
+    - author: Claude
+      timestamp: 2026-10-29T05:16:29Z
+      body: |
+        Built in sskaye/forgegraph#75 as agreed: tab_bar.label and tab_bar.line, below on this page. The selected tab is underlined in the label's color, the label's alignment places the names and its gap spaces them, the page embeds the label's font, and the line can be solid, dashed or dotted. The default pack's layout keeps no line under the bar.
+-->

{forgegraph-0.4.0 → forgegraph-0.5.0}/docs/specifications/theme.md

@@ -39,6 +39,12 @@ parameters: !var          *# !var/!fix sets whether a GraphSpec may ch
             minor:          *# \[line style\]; The minor tick marks.*\
                 count: 0          *# \[int ≥ 0\]; The number of minor ticks between major ticks. If 0, there are none.*\
                 length: 0.15          *# \[float ≥ 0\]; The minor tick length, × base size.*\
+        x:\
+            tick:\
+                label:          *# \[text style, look from axis.tick.label\]; The x-axis tick labels. Each parameter not set here is axis.tick.label's.*\
+        y:\
+            tick:\
+                label:          *# \[text style, look from axis.tick.label\]; The y-axis tick labels. Each parameter not set here is axis.tick.label's.*\
         max_extension: 0.15          *# \[0-1\]; The most an axis may be extended to fit direct labels, notes and line labels inside the plot area, × its range. If 0, it's never extended.*\
     plot_area:\
         border:          *# \[line style\]; The plot area's border.*\

{forgegraph-0.4.0 → forgegraph-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "forgegraph"
-version = "0.4.0"
+version = "0.5.0"
 description = "Fast, consistent, publication-quality graphs from pandas DataFrames, usable by people and AI agents."
 readme = "README.md"
 license = "MIT AND OFL-1.1"

{forgegraph-0.4.0 → forgegraph-0.5.0}/src/forgegraph/cli/schema.py

@@ -111,6 +111,16 @@ def schema(
                 }
                 for p in [*grid.values(), tile]
             ]
+            out[k].append(
+                {
+                    "parameter": "tabs.<tab>.tabs.<tab>",
+                    "default": None,
+                    "range": "a tab",
+                    "required": False,
+                    "description": "A tab's own tabs, each under its name, in place of its grid "
+                    "and tiles; they may hold tabs too.",
+                }
+            )
 
     def text() -> None:
         for note in out.pop("notes", []):

{forgegraph-0.4.0 → forgegraph-0.5.0}/src/forgegraph/drawing/axes.py

@@ -361,7 +361,7 @@ def ticks_and_labels(
         raise DrawError(f"{prefix}.scale: log, but the axis is categorical")
     t = style.theme
     order = str(t["axis.tick.label.date_order"])
-    gap = style.pt("axis.tick.label.gap")
+    gap = style.pt(f"{prefix}.tick.label.gap")
     locator: Locator
     if algorithm == "all":
         locator = FixedLocator(sorted(set(float(v) for v in values if not np.isnan(v))))
@@ -375,7 +375,7 @@ def ticks_and_labels(
         locator = LogTicks(
             str(t["axis.tick.log_algorithm"]),
             str(t["axis.tick.algorithm"]),
-            style.pt("axis.tick.label.gap"),
+            gap,
             integer=kind == "integer",
         )
     elif kind == "date":
@@ -415,7 +415,7 @@ def ticks_and_labels(
         formatter = Wrapped(
             formatter or axis.get_major_formatter(),
             int(t["axis.tick.label.max_wrap"]),
-            style.pt("axis.tick.label.gap"),
+            gap,
         )
     if formatter is not None:
         axis.set_major_formatter(formatter)
@@ -431,11 +431,12 @@ def _spacing(values: np.ndarray) -> float | None:
 
 
 def check_fit(ax: Axes, gt: dict[str, Any], style: Style) -> None:
-    """Tick labels that run together, or come within the theme's axis.tick.label.gap of each
-    other, are an error: all and manual are never thinned, and auto's algorithms count
-    labels by their height, not their width, so long labels can still meet."""
-    gap = style.pt("axis.tick.label.gap") * ax.figure.dpi / 72
+    """Tick labels that run together, or come within the theme's tick label gap of each
+    other (axis.x.tick.label.gap or axis.y's), are an error: all and manual are never
+    thinned, and auto's algorithms count labels by their height, not their width, so long
+    labels can still meet."""
     for name, axis in (("x", ax.xaxis), ("y", ax.yaxis)):
+        gap = style.pt(f"axis.{name}.tick.label.gap") * ax.figure.dpi / 72
         algorithm = gt[f"axis.{name}.tick.algorithm"]
         # get_majorticklabels updates the ticks first: before a draw they're stale
         if _run_together([t for t in axis.get_majorticklabels() if t.get_text()], gap):

{forgegraph-0.4.0 → forgegraph-0.5.0}/src/forgegraph/drawing/layers.py

@@ -42,6 +42,7 @@ from matplotlib.transforms import Bbox
 from forgegraph.drawing import labels, limits, marks
 from forgegraph.drawing.axes import number_text, numbers, on_axis
 from forgegraph.drawing.errors import DrawError
+from forgegraph.drawing.key import keys
 from forgegraph.drawing.markup import markup
 from forgegraph.drawing.style import Style, unset
 from forgegraph.drawing.text import measure
@@ -726,9 +727,28 @@ def _draw_bars(
     caps.set_transform(transform)
 
 
+TOP_NOTE = "_forgegraph_top_note"  # on a note above the plot box: its gap, in points
+
+
+def _under_top_notes(ax: Axes, renderer: Any) -> float:
+    """How far above the plot box a note outside at the top starts, in display pixels: past
+    the x-axis's tick labels on top, and past a key outside at the top."""
+    plot = ax.get_window_extent(renderer)
+    reach = 0.0
+    if any(t.label2.get_visible() and t.label2.get_text() for t in ax.xaxis.get_major_ticks()):
+        box = ax.xaxis.get_tightbbox(renderer)
+        reach = max(reach, box.y1 - plot.y1) if box is not None else reach
+    for k in keys(ax):
+        if k.outside and k.position and k.position.startswith("top"):
+            room = k.height + k.style.pt("legend.key.gap.outer")
+            reach = max(reach, room * ax.figure.dpi / 72)  # type: ignore[union-attr]
+    return reach
+
+
 def notes_outside(ax: Axes, layers: dict[str, dict[str, Any]], style: Style) -> None:
-    """Notes outside the plot area: above the title, or below the x-axis title. Drawn before
-    layout, which makes room for them."""
+    """Notes outside the plot area: at the top, between the title and the plot box (above a
+    key outside at the top), or below the x-axis title. Drawn before layout, which makes room
+    for them; the title moves up over a note at the top."""
     for name, layer in layers.items():
         if layer["type"] != "note" or layer["inside"]:
             continue
@@ -743,19 +763,19 @@ def notes_outside(ax: Axes, layers: dict[str, dict[str, Any]], style: Style) ->
         own = look(style, layer)
         gap = own.pt("layer.note.gap")
         top = vertical == "top"
-        anchor = ax.title if top else ax.xaxis.label
 
-        def edge(renderer: Any, anchor: Any = anchor, top: bool = top) -> Bbox:
+        def edge(renderer: Any, top: bool = top) -> Bbox:
             plot = ax.get_window_extent(renderer)
-            if anchor.get_text():
-                box = anchor.get_window_extent(renderer)
-            elif top:
-                box = plot
+            if top:
+                reach = _under_top_notes(ax, renderer)
+                return Bbox.from_extents(plot.x0, plot.y0, plot.x1, plot.y1 + reach)
+            if ax.xaxis.label.get_text():
+                box = ax.xaxis.label.get_window_extent(renderer)
             else:
                 box = ax.xaxis.get_tightbbox(renderer) or plot
             return Bbox.from_extents(plot.x0, box.y0, plot.x1, box.y1)
 
-        _note(
+        note = _note(
             ax,
             layer["text"],
             (fraction, 1.0 if top else 0.0),
@@ -765,6 +785,8 @@ def notes_outside(ax: Axes, layers: dict[str, dict[str, Any]], style: Style) ->
             "bottom" if top else "top",
             own,
         )
+        if top:
+            setattr(note, TOP_NOTE, gap)
 
 
 def _note(